doc/libunistring_4.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
   2 <html>
   3 <!-- Created on March, 30 2010 by texi2html 1.78a -->
   4 <!--
   5 Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
   6             Karl Berry  <karl@freefriends.org>
   7             Olaf Bachmann <obachman@mathematik.uni-kl.de>
   8             and many others.
   9 Maintained by: Many creative people.
  10 Send bugs and suggestions to <texi2html-bug@nongnu.org>
  11
  12 -->
  13 <head>
  14 <title>GNU libunistring: 4. Elementary Unicode string functions &lt;unistr.h&gt;</title>
  15
  16 <meta name="description" content="GNU libunistring: 4. Elementary Unicode string functions &lt;unistr.h&gt;">
  17 <meta name="keywords" content="GNU libunistring: 4. Elementary Unicode string functions &lt;unistr.h&gt;">
  18 <meta name="resource-type" content="document">
  19 <meta name="distribution" content="global">
  20 <meta name="Generator" content="texi2html 1.78a">
  21 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  22 <style type="text/css">
  23 <!--
  24 a.summary-letter {text-decoration: none}
  25 pre.display {font-family: serif}
  26 pre.format {font-family: serif}
  27 pre.menu-comment {font-family: serif}
  28 pre.menu-preformatted {font-family: serif}
  29 pre.smalldisplay {font-family: serif; font-size: smaller}
  30 pre.smallexample {font-size: smaller}
  31 pre.smallformat {font-family: serif; font-size: smaller}
  32 pre.smalllisp {font-size: smaller}
  33 span.roman {font-family:serif; font-weight:normal;}
  34 span.sansserif {font-family:sans-serif; font-weight:normal;}
  35 ul.toc {list-style: none}
  36 -->
  37 </style>
  38
  39
  40 </head>
  41
  42 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  43
  44 <table cellpadding="1" cellspacing="1" border="0">
  45 <tr><td valign="middle" align="left">[<a href="libunistring_3.html#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  46 <td valign="middle" align="left">[<a href="libunistring_5.html#SEC17" title="Next chapter"> &gt;&gt; </a>]</td>
  47 <td valign="middle" align="left"> &nbsp; </td>
  48 <td valign="middle" align="left"> &nbsp; </td>
  49 <td valign="middle" align="left"> &nbsp; </td>
  50 <td valign="middle" align="left"> &nbsp; </td>
  51 <td valign="middle" align="left"> &nbsp; </td>
  52 <td valign="middle" align="left">[<a href="libunistring.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
  53 <td valign="middle" align="left">[<a href="libunistring.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  54 <td valign="middle" align="left">[<a href="libunistring_18.html#SEC71" title="Index">Index</a>]</td>
  55 <td valign="middle" align="left">[<a href="libunistring_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  56 </tr></table>
  57
  58 <hr size="2">
  59 <a name="unistr_002eh"></a>
  60 <a name="SEC11"></a>
  61 <h1 class="chapter"> <a href="libunistring.html#TOC11">4. Elementary Unicode string functions <code>&lt;unistr.h&gt;</code></a> </h1>
  62
  63 <p>This include file declares elementary functions for Unicode strings.  It is
  64 essentially the equivalent of what <code>&lt;string.h&gt;</code> is for C strings.
  65 </p>
  66
  67 <hr size="6">
  68 <a name="Elementary-string-checks"></a>
  69 <a name="SEC12"></a>
  70 <h2 class="section"> <a href="libunistring.html#TOC12">4.1 Elementary string checks</a> </h2>
  71
  72 <p>The following function is available to verify the integrity of a Unicode string.
  73 </p>
  74 <dl>
  75 <dt><u>Function:</u> const uint8_t * <b>u8_check</b><i> (const uint8_t *<var>s</var>, size_t <var>n</var>)</i>
  76 <a name="IDX20"></a>
  77 </dt>
  78 <dt><u>Function:</u> const uint16_t * <b>u16_check</b><i> (const uint16_t *<var>s</var>, size_t <var>n</var>)</i>
  79 <a name="IDX21"></a>
  80 </dt>
  81 <dt><u>Function:</u> const uint32_t * <b>u32_check</b><i> (const uint32_t *<var>s</var>, size_t <var>n</var>)</i>
  82 <a name="IDX22"></a>
  83 </dt>
  84 <dd><p>This function checks whether a Unicode string is well-formed.
  85 It returns NULL if valid, or a pointer to the first invalid unit otherwise.
  86 </p></dd></dl>
  87
  88 <hr size="6">
  89 <a name="Elementary-string-conversions"></a>
  90 <a name="SEC13"></a>
  91 <h2 class="section"> <a href="libunistring.html#TOC13">4.2 Elementary string conversions</a> </h2>
  92
  93 <p>The following functions perform conversions between the different forms of Unicode strings.
  94 </p>
  95 <dl>
  96 <dt><u>Function:</u> uint16_t * <b>u8_to_u16</b><i> (const uint8_t *<var>s</var>, size_t <var>n</var>, uint16_t *<var>resultbuf</var>, size_t *<var>lengthp</var>)</i>
  97 <a name="IDX23"></a>
  98 </dt>
  99 <dd><p>Converts an UTF-8 string to an UTF-16 string.
 100 </p></dd></dl>
 101
 102 <dl>
 103 <dt><u>Function:</u> uint32_t * <b>u8_to_u32</b><i> (const uint8_t *<var>s</var>, size_t <var>n</var>, uint32_t *<var>resultbuf</var>, size_t *<var>lengthp</var>)</i>
 104 <a name="IDX24"></a>
 105 </dt>
 106 <dd><p>Converts an UTF-8 string to an UTF-32 string.
 107 </p></dd></dl>
 108
 109 <dl>
 110 <dt><u>Function:</u> uint8_t * <b>u16_to_u8</b><i> (const uint16_t *<var>s</var>, size_t <var>n</var>, uint8_t *<var>resultbuf</var>, size_t *<var>lengthp</var>)</i>
 111 <a name="IDX25"></a>
 112 </dt>
 113 <dd><p>Converts an UTF-16 string to an UTF-8 string.
 114 </p></dd></dl>
 115
 116 <dl>
 117 <dt><u>Function:</u> uint32_t * <b>u16_to_u32</b><i> (const uint16_t *<var>s</var>, size_t <var>n</var>, uint32_t *<var>resultbuf</var>, size_t *<var>lengthp</var>)</i>
 118 <a name="IDX26"></a>
 119 </dt>
 120 <dd><p>Converts an UTF-16 string to an UTF-32 string.
 121 </p></dd></dl>
 122
 123 <dl>
 124 <dt><u>Function:</u> uint8_t * <b>u32_to_u8</b><i> (const uint32_t *<var>s</var>, size_t <var>n</var>, uint8_t *<var>resultbuf</var>, size_t *<var>lengthp</var>)</i>
 125 <a name="IDX27"></a>
 126 </dt>
 127 <dd><p>Converts an UTF-32 string to an UTF-8 string.
 128 </p></dd></dl>
 129
 130 <dl>
 131 <dt><u>Function:</u> uint16_t * <b>u32_to_u16</b><i> (const uint32_t *<var>s</var>, size_t <var>n</var>, uint16_t *<var>resultbuf</var>, size_t *<var>lengthp</var>)</i>
 132 <a name="IDX28"></a>
 133 </dt>
 134 <dd><p>Converts an UTF-32 string to an UTF-16 string.
 135 </p></dd></dl>
 136
 137 <hr size="6">
 138 <a name="Elementary-string-functions"></a>
 139 <a name="SEC14"></a>
 140 <h2 class="section"> <a href="libunistring.html#TOC14">4.3 Elementary string functions</a> </h2>
 141
 142 <p>The following functions inspect and return details about the first character
 143 in a Unicode string.
 144 </p>
 145 <dl>
 146 <dt><u>Function:</u> int <b>u8_mblen</b><i> (const uint8_t *<var>s</var>, size_t <var>n</var>)</i>
 147 <a name="IDX29"></a>
 148 </dt>
 149 <dt><u>Function:</u> int <b>u16_mblen</b><i> (const uint16_t *<var>s</var>, size_t <var>n</var>)</i>
 150 <a name="IDX30"></a>
 151 </dt>
 152 <dt><u>Function:</u> int <b>u32_mblen</b><i> (const uint32_t *<var>s</var>, size_t <var>n</var>)</i>
 153 <a name="IDX31"></a>
 154 </dt>
 155 <dd><p>Returns the length (number of units) of the first character in <var>s</var>, which
 156 is no longer than <var>n</var>.  Returns 0 if it is the NUL character.  Returns -1
 157 upon failure.
 158 </p>
 159 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/mblen.html"><code>mblen</code></a>, except that it operates on a
 160 Unicode string and that <var>s</var> must not be NULL.
 161 </p></dd></dl>
 162
 163 <dl>
 164 <dt><u>Function:</u> int <b>u8_mbtouc_unsafe</b><i> (ucs4_t *<var>puc</var>, const uint8_t *<var>s</var>, size_t <var>n</var>)</i>
 165 <a name="IDX32"></a>
 166 </dt>
 167 <dt><u>Function:</u> int <b>u16_mbtouc_unsafe</b><i> (ucs4_t *<var>puc</var>, const uint16_t *<var>s</var>, size_t <var>n</var>)</i>
 168 <a name="IDX33"></a>
 169 </dt>
 170 <dt><u>Function:</u> int <b>u32_mbtouc_unsafe</b><i> (ucs4_t *<var>puc</var>, const uint32_t *<var>s</var>, size_t <var>n</var>)</i>
 171 <a name="IDX34"></a>
 172 </dt>
 173 <dd><p>Returns the length (number of units) of the first character in <var>s</var>,
 174 putting its <code>ucs4_t</code> representation in <code>*<var>puc</var></code>.  Upon failure,
 175 <code>*<var>puc</var></code> is set to <code>0xfffd</code>, and an appropriate number of units
 176 is returned.
 177 </p>
 178 <p>The number of available units, <var>n</var>, must be &gt; 0.
 179 </p>
 180 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/mbtowc.html"><code>mbtowc</code></a>, except that it operates on a
 181 Unicode string, <var>puc</var> and <var>s</var> must not be NULL, <var>n</var> must be &gt; 0,
 182 and the NUL character is not treated specially.
 183 </p></dd></dl>
 184
 185 <dl>
 186 <dt><u>Function:</u> int <b>u8_mbtouc</b><i> (ucs4_t *<var>puc</var>, const uint8_t *<var>s</var>, size_t <var>n</var>)</i>
 187 <a name="IDX35"></a>
 188 </dt>
 189 <dt><u>Function:</u> int <b>u16_mbtouc</b><i> (ucs4_t *<var>puc</var>, const uint16_t *<var>s</var>, size_t <var>n</var>)</i>
 190 <a name="IDX36"></a>
 191 </dt>
 192 <dt><u>Function:</u> int <b>u32_mbtouc</b><i> (ucs4_t *<var>puc</var>, const uint32_t *<var>s</var>, size_t <var>n</var>)</i>
 193 <a name="IDX37"></a>
 194 </dt>
 195 <dd><p>This function is like <code>u8_mbtouc_unsafe</code>, except that it will detect an
 196 invalid UTF-8 character, even if the library is compiled without
 197 &lsquo;<samp>--enable-safety</samp>&rsquo;.
 198 </p></dd></dl>
 199
 200 <dl>
 201 <dt><u>Function:</u> int <b>u8_mbtoucr</b><i> (ucs4_t *<var>puc</var>, const uint8_t *<var>s</var>, size_t <var>n</var>)</i>
 202 <a name="IDX38"></a>
 203 </dt>
 204 <dt><u>Function:</u> int <b>u16_mbtoucr</b><i> (ucs4_t *<var>puc</var>, const uint16_t *<var>s</var>, size_t <var>n</var>)</i>
 205 <a name="IDX39"></a>
 206 </dt>
 207 <dt><u>Function:</u> int <b>u32_mbtoucr</b><i> (ucs4_t *<var>puc</var>, const uint32_t *<var>s</var>, size_t <var>n</var>)</i>
 208 <a name="IDX40"></a>
 209 </dt>
 210 <dd><p>Returns the length (number of units) of the first character in <var>s</var>,
 211 putting its <code>ucs4_t</code> representation in <code>*<var>puc</var></code>.  Upon failure,
 212 <code>*<var>puc</var></code> is set to <code>0xfffd</code>, and -1 is returned for an invalid
 213 sequence of units, -2 is returned for an incomplete sequence of units.
 214 </p>
 215 <p>The number of available units, <var>n</var>, must be &gt; 0.
 216 </p>
 217 <p>This function is similar to <code>u8_mbtouc</code>, except that the return value
 218 gives more details about the failure, similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/mbrtowc.html"><code>mbrtowc</code></a>.
 219 </p></dd></dl>
 220
 221 <p>The following function stores a Unicode character as a Unicode string in
 222 memory.
 223 </p>
 224 <dl>
 225 <dt><u>Function:</u> int <b>u8_uctomb</b><i> (uint8_t *<var>s</var>, ucs4_t <var>uc</var>, int <var>n</var>)</i>
 226 <a name="IDX41"></a>
 227 </dt>
 228 <dt><u>Function:</u> int <b>u16_uctomb</b><i> (uint16_t *<var>s</var>, ucs4_t <var>uc</var>, int <var>n</var>)</i>
 229 <a name="IDX42"></a>
 230 </dt>
 231 <dt><u>Function:</u> int <b>u32_uctomb</b><i> (uint32_t *<var>s</var>, ucs4_t <var>uc</var>, int <var>n</var>)</i>
 232 <a name="IDX43"></a>
 233 </dt>
 234 <dd><p>Puts the multibyte character represented by <var>uc</var> in <var>s</var>, returning its
 235 length.  Returns -1 upon failure, -2 if the number of available units, <var>n</var>,
 236 is too small.  The latter case cannot occur if <var>n</var> &gt;= 6/2/1, respectively.
 237 </p>
 238 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wctomb.html"><code>wctomb</code></a>, except that it operates on a
 239 Unicode strings, <var>s</var> must not be NULL, and the argument <var>n</var> must be
 240 specified.
 241 </p></dd></dl>
 242
 243 <a name="IDX44"></a>
 244 <p>The following functions copy Unicode strings in memory.
 245 </p>
 246 <dl>
 247 <dt><u>Function:</u> uint8_t * <b>u8_cpy</b><i> (uint8_t *<var>dest</var>, const uint8_t *<var>src</var>, size_t <var>n</var>)</i>
 248 <a name="IDX45"></a>
 249 </dt>
 250 <dt><u>Function:</u> uint16_t * <b>u16_cpy</b><i> (uint16_t *<var>dest</var>, const uint16_t *<var>src</var>, size_t <var>n</var>)</i>
 251 <a name="IDX46"></a>
 252 </dt>
 253 <dt><u>Function:</u> uint32_t * <b>u32_cpy</b><i> (uint32_t *<var>dest</var>, const uint32_t *<var>src</var>, size_t <var>n</var>)</i>
 254 <a name="IDX47"></a>
 255 </dt>
 256 <dd><p>Copies <var>n</var> units from <var>src</var> to <var>dest</var>.
 257 </p>
 258 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/memcpy.html"><code>memcpy</code></a>, except that it operates on
 259 Unicode strings.
 260 </p></dd></dl>
 261
 262 <dl>
 263 <dt><u>Function:</u> uint8_t * <b>u8_move</b><i> (uint8_t *<var>dest</var>, const uint8_t *<var>src</var>, size_t <var>n</var>)</i>
 264 <a name="IDX48"></a>
 265 </dt>
 266 <dt><u>Function:</u> uint16_t * <b>u16_move</b><i> (uint16_t *<var>dest</var>, const uint16_t *<var>src</var>, size_t <var>n</var>)</i>
 267 <a name="IDX49"></a>
 268 </dt>
 269 <dt><u>Function:</u> uint32_t * <b>u32_move</b><i> (uint32_t *<var>dest</var>, const uint32_t *<var>src</var>, size_t <var>n</var>)</i>
 270 <a name="IDX50"></a>
 271 </dt>
 272 <dd><p>Copies <var>n</var> units from <var>src</var> to <var>dest</var>, guaranteeing correct
 273 behavior for overlapping memory areas.
 274 </p>
 275 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/memmove.html"><code>memmove</code></a>, except that it operates on
 276 Unicode strings.
 277 </p></dd></dl>
 278
 279 <p>The following function fills a Unicode string.
 280 </p>
 281 <dl>
 282 <dt><u>Function:</u> uint8_t * <b>u8_set</b><i> (uint8_t *<var>s</var>, ucs4_t <var>uc</var>, size_t <var>n</var>)</i>
 283 <a name="IDX51"></a>
 284 </dt>
 285 <dt><u>Function:</u> uint16_t * <b>u16_set</b><i> (uint16_t *<var>s</var>, ucs4_t <var>uc</var>, size_t <var>n</var>)</i>
 286 <a name="IDX52"></a>
 287 </dt>
 288 <dt><u>Function:</u> uint32_t * <b>u32_set</b><i> (uint32_t *<var>s</var>, ucs4_t <var>uc</var>, size_t <var>n</var>)</i>
 289 <a name="IDX53"></a>
 290 </dt>
 291 <dd><p>Sets the first <var>n</var> characters of <var>s</var> to <var>uc</var>.  <var>uc</var> should be
 292 a character that occupies only 1 unit.
 293 </p>
 294 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/memset.html"><code>memset</code></a>, except that it operates on
 295 Unicode strings.
 296 </p></dd></dl>
 297
 298 <a name="IDX54"></a>
 299 <p>The following function compares two Unicode strings of the same length.
 300 </p>
 301 <dl>
 302 <dt><u>Function:</u> int <b>u8_cmp</b><i> (const uint8_t *<var>s1</var>, const uint8_t *<var>s2</var>, size_t <var>n</var>)</i>
 303 <a name="IDX55"></a>
 304 </dt>
 305 <dt><u>Function:</u> int <b>u16_cmp</b><i> (const uint16_t *<var>s1</var>, const uint16_t *<var>s2</var>, size_t <var>n</var>)</i>
 306 <a name="IDX56"></a>
 307 </dt>
 308 <dt><u>Function:</u> int <b>u32_cmp</b><i> (const uint32_t *<var>s1</var>, const uint32_t *<var>s2</var>, size_t <var>n</var>)</i>
 309 <a name="IDX57"></a>
 310 </dt>
 311 <dd><p>Compares <var>s1</var> and <var>s2</var>, each of length <var>n</var>, lexicographically.
 312 Returns a negative value if <var>s1</var> compares smaller than <var>s2</var>,
 313 a positive value if <var>s1</var> compares larger than <var>s2</var>, or 0 if
 314 they compare equal.
 315 </p>
 316 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/memcmp.html"><code>memcmp</code></a>, except that it operates on
 317 Unicode strings.
 318 </p></dd></dl>
 319
 320 <p>The following function compares two Unicode strings of possibly different
 321 lengths.
 322 </p>
 323 <dl>
 324 <dt><u>Function:</u> int <b>u8_cmp2</b><i> (const uint8_t *<var>s1</var>, size_t <var>n1</var>, const uint8_t *<var>s2</var>, size_t <var>n2</var>)</i>
 325 <a name="IDX58"></a>
 326 </dt>
 327 <dt><u>Function:</u> int <b>u16_cmp2</b><i> (const uint16_t *<var>s1</var>, size_t <var>n1</var>, const uint16_t *<var>s2</var>, size_t <var>n2</var>)</i>
 328 <a name="IDX59"></a>
 329 </dt>
 330 <dt><u>Function:</u> int <b>u32_cmp2</b><i> (const uint32_t *<var>s1</var>, size_t <var>n1</var>, const uint32_t *<var>s2</var>, size_t <var>n2</var>)</i>
 331 <a name="IDX60"></a>
 332 </dt>
 333 <dd><p>Compares <var>s1</var> and <var>s2</var>, lexicographically.
 334 Returns a negative value if <var>s1</var> compares smaller than <var>s2</var>,
 335 a positive value if <var>s1</var> compares larger than <var>s2</var>, or 0 if
 336 they compare equal.
 337 </p>
 338 <p>This function is similar to the gnulib function <code>memcmp2</code>, except that it
 339 operates on Unicode strings.
 340 </p></dd></dl>
 341
 342 <a name="IDX61"></a>
 343 <p>The following function searches for a given Unicode character.
 344 </p>
 345 <dl>
 346 <dt><u>Function:</u> uint8_t * <b>u8_chr</b><i> (const uint8_t *<var>s</var>, size_t <var>n</var>, ucs4_t <var>uc</var>)</i>
 347 <a name="IDX62"></a>
 348 </dt>
 349 <dt><u>Function:</u> uint16_t * <b>u16_chr</b><i> (const uint16_t *<var>s</var>, size_t <var>n</var>, ucs4_t <var>uc</var>)</i>
 350 <a name="IDX63"></a>
 351 </dt>
 352 <dt><u>Function:</u> uint32_t * <b>u32_chr</b><i> (const uint32_t *<var>s</var>, size_t <var>n</var>, ucs4_t <var>uc</var>)</i>
 353 <a name="IDX64"></a>
 354 </dt>
 355 <dd><p>Searches the string at <var>s</var> for <var>uc</var>.  Returns a pointer to the first
 356 occurrence of <var>uc</var> in <var>s</var>, or NULL if <var>uc</var> does not occur in
 357 <var>s</var>.
 358 </p>
 359 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/memchr.html"><code>memchr</code></a>, except that it operates on
 360 Unicode strings.
 361 </p></dd></dl>
 362
 363 <a name="IDX65"></a>
 364 <p>The following function counts the number of Unicode characters.
 365 </p>
 366 <dl>
 367 <dt><u>Function:</u> size_t <b>u8_mbsnlen</b><i> (const uint8_t *<var>s</var>, size_t <var>n</var>)</i>
 368 <a name="IDX66"></a>
 369 </dt>
 370 <dt><u>Function:</u> size_t <b>u16_mbsnlen</b><i> (const uint16_t *<var>s</var>, size_t <var>n</var>)</i>
 371 <a name="IDX67"></a>
 372 </dt>
 373 <dt><u>Function:</u> size_t <b>u32_mbsnlen</b><i> (const uint32_t *<var>s</var>, size_t <var>n</var>)</i>
 374 <a name="IDX68"></a>
 375 </dt>
 376 <dd><p>Counts and returns the number of Unicode characters in the <var>n</var> units
 377 from <var>s</var>.
 378 </p>
 379 <p>This function is similar to the gnulib function <code>mbsnlen</code>, except that
 380 it operates on Unicode strings.
 381 </p></dd></dl>
 382
 383 <hr size="6">
 384 <a name="Elementary-string-functions-with-memory-allocation"></a>
 385 <a name="SEC15"></a>
 386 <h2 class="section"> <a href="libunistring.html#TOC15">4.4 Elementary string functions with memory allocation</a> </h2>
 387
 388 <p>The following function copies a Unicode string.
 389 </p>
 390 <dl>
 391 <dt><u>Function:</u> uint8_t * <b>u8_cpy_alloc</b><i> (const uint8_t *<var>s</var>, size_t <var>n</var>)</i>
 392 <a name="IDX69"></a>
 393 </dt>
 394 <dt><u>Function:</u> uint16_t * <b>u16_cpy_alloc</b><i> (const uint16_t *<var>s</var>, size_t <var>n</var>)</i>
 395 <a name="IDX70"></a>
 396 </dt>
 397 <dt><u>Function:</u> uint32_t * <b>u32_cpy_alloc</b><i> (const uint32_t *<var>s</var>, size_t <var>n</var>)</i>
 398 <a name="IDX71"></a>
 399 </dt>
 400 <dd><p>Makes a freshly allocated copy of <var>s</var>, of length <var>n</var>.
 401 </p></dd></dl>
 402
 403 <hr size="6">
 404 <a name="Elementary-string-functions-on-NUL-terminated-strings"></a>
 405 <a name="SEC16"></a>
 406 <h2 class="section"> <a href="libunistring.html#TOC16">4.5 Elementary string functions on NUL terminated strings</a> </h2>
 407
 408 <p>The following functions inspect and return details about the first character
 409 in a Unicode string.
 410 </p>
 411 <dl>
 412 <dt><u>Function:</u> int <b>u8_strmblen</b><i> (const uint8_t *<var>s</var>)</i>
 413 <a name="IDX72"></a>
 414 </dt>
 415 <dt><u>Function:</u> int <b>u16_strmblen</b><i> (const uint16_t *<var>s</var>)</i>
 416 <a name="IDX73"></a>
 417 </dt>
 418 <dt><u>Function:</u> int <b>u32_strmblen</b><i> (const uint32_t *<var>s</var>)</i>
 419 <a name="IDX74"></a>
 420 </dt>
 421 <dd><p>Returns the length (number of units) of the first character in <var>s</var>.
 422 Returns 0 if it is the NUL character.  Returns -1 upon failure.
 423 </p></dd></dl>
 424
 425 <a name="IDX75"></a>
 426 <dl>
 427 <dt><u>Function:</u> int <b>u8_strmbtouc</b><i> (ucs4_t *<var>puc</var>, const uint8_t *<var>s</var>)</i>
 428 <a name="IDX76"></a>
 429 </dt>
 430 <dt><u>Function:</u> int <b>u16_strmbtouc</b><i> (ucs4_t *<var>puc</var>, const uint16_t *<var>s</var>)</i>
 431 <a name="IDX77"></a>
 432 </dt>
 433 <dt><u>Function:</u> int <b>u32_strmbtouc</b><i> (ucs4_t *<var>puc</var>, const uint32_t *<var>s</var>)</i>
 434 <a name="IDX78"></a>
 435 </dt>
 436 <dd><p>Returns the length (number of units) of the first character in <var>s</var>,
 437 putting its <code>ucs4_t</code> representation in <code>*<var>puc</var></code>.  Returns 0
 438 if it is the NUL character.  Returns -1 upon failure.
 439 </p></dd></dl>
 440
 441 <dl>
 442 <dt><u>Function:</u> const uint8_t * <b>u8_next</b><i> (ucs4_t *<var>puc</var>, const uint8_t *<var>s</var>)</i>
 443 <a name="IDX79"></a>
 444 </dt>
 445 <dt><u>Function:</u> const uint16_t * <b>u16_next</b><i> (ucs4_t *<var>puc</var>, const uint16_t *<var>s</var>)</i>
 446 <a name="IDX80"></a>
 447 </dt>
 448 <dt><u>Function:</u> const uint32_t * <b>u32_next</b><i> (ucs4_t *<var>puc</var>, const uint32_t *<var>s</var>)</i>
 449 <a name="IDX81"></a>
 450 </dt>
 451 <dd><p>Forward iteration step.  Advances the pointer past the next character,
 452 or returns NULL if the end of the string has been reached.  Puts the
 453 character's <code>ucs4_t</code> representation in <code>*<var>puc</var></code>.
 454 </p></dd></dl>
 455
 456 <p>The following function inspects and returns details about the previous
 457 character in a Unicode string.
 458 </p>
 459 <dl>
 460 <dt><u>Function:</u> const uint8_t * <b>u8_prev</b><i> (ucs4_t *<var>puc</var>, const uint8_t *<var>s</var>, const uint8_t *<var>start</var>)</i>
 461 <a name="IDX82"></a>
 462 </dt>
 463 <dt><u>Function:</u> const uint16_t * <b>u16_prev</b><i> (ucs4_t *<var>puc</var>, const uint16_t *<var>s</var>, const uint16_t *<var>start</var>)</i>
 464 <a name="IDX83"></a>
 465 </dt>
 466 <dt><u>Function:</u> const uint32_t * <b>u32_prev</b><i> (ucs4_t *<var>puc</var>, const uint32_t *<var>s</var>, const uint32_t *<var>start</var>)</i>
 467 <a name="IDX84"></a>
 468 </dt>
 469 <dd><p>Backward iteration step.  Advances the pointer to point to the previous
 470 character, or returns NULL if the beginning of the string had been reached.
 471 Puts the character's <code>ucs4_t</code> representation in <code>*<var>puc</var></code>.
 472 </p></dd></dl>
 473
 474 <p>The following functions determine the length of a Unicode string.
 475 </p>
 476 <dl>
 477 <dt><u>Function:</u> size_t <b>u8_strlen</b><i> (const uint8_t *<var>s</var>)</i>
 478 <a name="IDX85"></a>
 479 </dt>
 480 <dt><u>Function:</u> size_t <b>u16_strlen</b><i> (const uint16_t *<var>s</var>)</i>
 481 <a name="IDX86"></a>
 482 </dt>
 483 <dt><u>Function:</u> size_t <b>u32_strlen</b><i> (const uint32_t *<var>s</var>)</i>
 484 <a name="IDX87"></a>
 485 </dt>
 486 <dd><p>Returns the number of units in <var>s</var>.
 487 </p>
 488 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strlen.html"><code>strlen</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcslen.html"><code>wcslen</code></a>, except
 489 that it operates on Unicode strings.
 490 </p></dd></dl>
 491
 492 <dl>
 493 <dt><u>Function:</u> size_t <b>u8_strnlen</b><i> (const uint8_t *<var>s</var>, size_t <var>maxlen</var>)</i>
 494 <a name="IDX88"></a>
 495 </dt>
 496 <dt><u>Function:</u> size_t <b>u16_strnlen</b><i> (const uint16_t *<var>s</var>, size_t <var>maxlen</var>)</i>
 497 <a name="IDX89"></a>
 498 </dt>
 499 <dt><u>Function:</u> size_t <b>u32_strnlen</b><i> (const uint32_t *<var>s</var>, size_t <var>maxlen</var>)</i>
 500 <a name="IDX90"></a>
 501 </dt>
 502 <dd><p>Returns the number of units in <var>s</var>, but at most <var>maxlen</var>.
 503 </p>
 504 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strnlen.html"><code>strnlen</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcsnlen.html"><code>wcsnlen</code></a>, except
 505 that it operates on Unicode strings.
 506 </p></dd></dl>
 507
 508 <a name="IDX91"></a>
 509 <p>The following functions copy portions of Unicode strings in memory.
 510 </p>
 511 <dl>
 512 <dt><u>Function:</u> uint8_t * <b>u8_strcpy</b><i> (uint8_t *<var>dest</var>, const uint8_t *<var>src</var>)</i>
 513 <a name="IDX92"></a>
 514 </dt>
 515 <dt><u>Function:</u> uint16_t * <b>u16_strcpy</b><i> (uint16_t *<var>dest</var>, const uint16_t *<var>src</var>)</i>
 516 <a name="IDX93"></a>
 517 </dt>
 518 <dt><u>Function:</u> uint32_t * <b>u32_strcpy</b><i> (uint32_t *<var>dest</var>, const uint32_t *<var>src</var>)</i>
 519 <a name="IDX94"></a>
 520 </dt>
 521 <dd><p>Copies <var>src</var> to <var>dest</var>.
 522 </p>
 523 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strcpy.html"><code>strcpy</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcscpy.html"><code>wcscpy</code></a>, except
 524 that it operates on Unicode strings.
 525 </p></dd></dl>
 526
 527 <dl>
 528 <dt><u>Function:</u> uint8_t * <b>u8_stpcpy</b><i> (uint8_t *<var>dest</var>, const uint8_t *<var>src</var>)</i>
 529 <a name="IDX95"></a>
 530 </dt>
 531 <dt><u>Function:</u> uint16_t * <b>u16_stpcpy</b><i> (uint16_t *<var>dest</var>, const uint16_t *<var>src</var>)</i>
 532 <a name="IDX96"></a>
 533 </dt>
 534 <dt><u>Function:</u> uint32_t * <b>u32_stpcpy</b><i> (uint32_t *<var>dest</var>, const uint32_t *<var>src</var>)</i>
 535 <a name="IDX97"></a>
 536 </dt>
 537 <dd><p>Copies <var>src</var> to <var>dest</var>, returning the address of the terminating NUL
 538 in <var>dest</var>.
 539 </p>
 540 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/stpcpy.html"><code>stpcpy</code></a>, except that it operates on
 541 Unicode strings.
 542 </p></dd></dl>
 543
 544 <dl>
 545 <dt><u>Function:</u> uint8_t * <b>u8_strncpy</b><i> (uint8_t *<var>dest</var>, const uint8_t *<var>src</var>, size_t <var>n</var>)</i>
 546 <a name="IDX98"></a>
 547 </dt>
 548 <dt><u>Function:</u> uint16_t * <b>u16_strncpy</b><i> (uint16_t *<var>dest</var>, const uint16_t *<var>src</var>, size_t <var>n</var>)</i>
 549 <a name="IDX99"></a>
 550 </dt>
 551 <dt><u>Function:</u> uint32_t * <b>u32_strncpy</b><i> (uint32_t *<var>dest</var>, const uint32_t *<var>src</var>, size_t <var>n</var>)</i>
 552 <a name="IDX100"></a>
 553 </dt>
 554 <dd><p>Copies no more than <var>n</var> units of <var>src</var> to <var>dest</var>.
 555 </p>
 556 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strncpy.html"><code>strncpy</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcsncpy.html"><code>wcsncpy</code></a>, except
 557 that it operates on Unicode strings.
 558 </p></dd></dl>
 559
 560 <dl>
 561 <dt><u>Function:</u> uint8_t * <b>u8_stpncpy</b><i> (uint8_t *<var>dest</var>, const uint8_t *<var>src</var>, size_t <var>n</var>)</i>
 562 <a name="IDX101"></a>
 563 </dt>
 564 <dt><u>Function:</u> uint16_t * <b>u16_stpncpy</b><i> (uint16_t *<var>dest</var>, const uint16_t *<var>src</var>, size_t <var>n</var>)</i>
 565 <a name="IDX102"></a>
 566 </dt>
 567 <dt><u>Function:</u> uint32_t * <b>u32_stpncpy</b><i> (uint32_t *<var>dest</var>, const uint32_t *<var>src</var>, size_t <var>n</var>)</i>
 568 <a name="IDX103"></a>
 569 </dt>
 570 <dd><p>Copies no more than <var>n</var> units of <var>src</var> to <var>dest</var>.  Returns a
 571 pointer past the last non-NUL unit written into <var>dest</var>.  In other words,
 572 if the units written into <var>dest</var> include a NUL, the return value is the
 573 address of the first such NUL unit, otherwise it is
 574 <code><var>dest</var> + <var>n</var></code>.
 575 </p>
 576 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/stpncpy.html"><code>stpncpy</code></a>, except that it operates on
 577 Unicode strings.
 578 </p></dd></dl>
 579
 580 <dl>
 581 <dt><u>Function:</u> uint8_t * <b>u8_strcat</b><i> (uint8_t *<var>dest</var>, const uint8_t *<var>src</var>)</i>
 582 <a name="IDX104"></a>
 583 </dt>
 584 <dt><u>Function:</u> uint16_t * <b>u16_strcat</b><i> (uint16_t *<var>dest</var>, const uint16_t *<var>src</var>)</i>
 585 <a name="IDX105"></a>
 586 </dt>
 587 <dt><u>Function:</u> uint32_t * <b>u32_strcat</b><i> (uint32_t *<var>dest</var>, const uint32_t *<var>src</var>)</i>
 588 <a name="IDX106"></a>
 589 </dt>
 590 <dd><p>Appends <var>src</var> onto <var>dest</var>.
 591 </p>
 592 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strcat.html"><code>strcat</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcscat.html"><code>wcscat</code></a>, except
 593 that it operates on Unicode strings.
 594 </p></dd></dl>
 595
 596 <dl>
 597 <dt><u>Function:</u> uint8_t * <b>u8_strncat</b><i> (uint8_t *<var>dest</var>, const uint8_t *<var>src</var>, size_t <var>n</var>)</i>
 598 <a name="IDX107"></a>
 599 </dt>
 600 <dt><u>Function:</u> uint16_t * <b>u16_strncat</b><i> (uint16_t *<var>dest</var>, const uint16_t *<var>src</var>, size_t <var>n</var>)</i>
 601 <a name="IDX108"></a>
 602 </dt>
 603 <dt><u>Function:</u> uint32_t * <b>u32_strncat</b><i> (uint32_t *<var>dest</var>, const uint32_t *<var>src</var>, size_t <var>n</var>)</i>
 604 <a name="IDX109"></a>
 605 </dt>
 606 <dd><p>Appends no more than <var>n</var> units of <var>src</var> onto <var>dest</var>.
 607 </p>
 608 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strncat.html"><code>strncat</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcsncat.html"><code>wcsncat</code></a>, except
 609 that it operates on Unicode strings.
 610 </p></dd></dl>
 611
 612 <a name="IDX110"></a>
 613 <p>The following functions compare two Unicode strings.
 614 </p>
 615 <dl>
 616 <dt><u>Function:</u> int <b>u8_strcmp</b><i> (const uint8_t *<var>s1</var>, const uint8_t *<var>s2</var>)</i>
 617 <a name="IDX111"></a>
 618 </dt>
 619 <dt><u>Function:</u> int <b>u16_strcmp</b><i> (const uint16_t *<var>s1</var>, const uint16_t *<var>s2</var>)</i>
 620 <a name="IDX112"></a>
 621 </dt>
 622 <dt><u>Function:</u> int <b>u32_strcmp</b><i> (const uint32_t *<var>s1</var>, const uint32_t *<var>s2</var>)</i>
 623 <a name="IDX113"></a>
 624 </dt>
 625 <dd><p>Compares <var>s1</var> and <var>s2</var>, lexicographically.
 626 Returns a negative value if <var>s1</var> compares smaller than <var>s2</var>,
 627 a positive value if <var>s1</var> compares larger than <var>s2</var>, or 0 if
 628 they compare equal.
 629 </p>
 630 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strcmp.html"><code>strcmp</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcscmp.html"><code>wcscmp</code></a>, except
 631 that it operates on Unicode strings.
 632 </p></dd></dl>
 633
 634 <a name="IDX114"></a>
 635 <dl>
 636 <dt><u>Function:</u> int <b>u8_strcoll</b><i> (const uint8_t *<var>s1</var>, const uint8_t *<var>s2</var>)</i>
 637 <a name="IDX115"></a>
 638 </dt>
 639 <dt><u>Function:</u> int <b>u16_strcoll</b><i> (const uint16_t *<var>s1</var>, const uint16_t *<var>s2</var>)</i>
 640 <a name="IDX116"></a>
 641 </dt>
 642 <dt><u>Function:</u> int <b>u32_strcoll</b><i> (const uint32_t *<var>s1</var>, const uint32_t *<var>s2</var>)</i>
 643 <a name="IDX117"></a>
 644 </dt>
 645 <dd><p>Compares <var>s1</var> and <var>s2</var> using the collation rules of the current
 646 locale.
 647 Returns -1 if <var>s1</var> &lt; <var>s2</var>, 0 if <var>s1</var> = <var>s2</var>, 1 if
 648 <var>s1</var> &gt; <var>s2</var>.  Upon failure, sets <code>errno</code> and returns any value.
 649 </p>
 650 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strcoll.html"><code>strcoll</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcscoll.html"><code>wcscoll</code></a>, except
 651 that it operates on Unicode strings.
 652 </p>
 653 <p>Note that this function may consider different canonical normalizations
 654 of the same string as having a large distance.  It is therefore better to
 655 use the function <code>u8_normcoll</code> instead of this one; see <a href="libunistring_12.html#SEC42">Normalization forms (composition and decomposition) <code>&lt;uninorm.h&gt;</code></a>.
 656 </p></dd></dl>
 657
 658 <dl>
 659 <dt><u>Function:</u> int <b>u8_strncmp</b><i> (const uint8_t *<var>s1</var>, const uint8_t *<var>s2</var>, size_t <var>n</var>)</i>
 660 <a name="IDX118"></a>
 661 </dt>
 662 <dt><u>Function:</u> int <b>u16_strncmp</b><i> (const uint16_t *<var>s1</var>, const uint16_t *<var>s2</var>, size_t <var>n</var>)</i>
 663 <a name="IDX119"></a>
 664 </dt>
 665 <dt><u>Function:</u> int <b>u32_strncmp</b><i> (const uint32_t *<var>s1</var>, const uint32_t *<var>s2</var>, size_t <var>n</var>)</i>
 666 <a name="IDX120"></a>
 667 </dt>
 668 <dd><p>Compares no more than <var>n</var> units of <var>s1</var> and <var>s2</var>.
 669 </p>
 670 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strncmp.html"><code>strncmp</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcsncmp.html"><code>wcsncmp</code></a>, except
 671 that it operates on Unicode strings.
 672 </p></dd></dl>
 673
 674 <a name="IDX121"></a>
 675 <p>The following function allocates a duplicate of a Unicode string.
 676 </p>
 677 <dl>
 678 <dt><u>Function:</u> uint8_t * <b>u8_strdup</b><i> (const uint8_t *<var>s</var>)</i>
 679 <a name="IDX122"></a>
 680 </dt>
 681 <dt><u>Function:</u> uint16_t * <b>u16_strdup</b><i> (const uint16_t *<var>s</var>)</i>
 682 <a name="IDX123"></a>
 683 </dt>
 684 <dt><u>Function:</u> uint32_t * <b>u32_strdup</b><i> (const uint32_t *<var>s</var>)</i>
 685 <a name="IDX124"></a>
 686 </dt>
 687 <dd><p>Duplicates <var>s</var>, returning an identical malloc'd string.
 688 </p>
 689 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strdup.html"><code>strdup</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcsdup.html"><code>wcsdup</code></a>, except
 690 that it operates on Unicode strings.
 691 </p></dd></dl>
 692
 693 <a name="IDX125"></a>
 694 <p>The following functions search for a given Unicode character.
 695 </p>
 696 <dl>
 697 <dt><u>Function:</u> uint8_t * <b>u8_strchr</b><i> (const uint8_t *<var>str</var>, ucs4_t <var>uc</var>)</i>
 698 <a name="IDX126"></a>
 699 </dt>
 700 <dt><u>Function:</u> uint16_t * <b>u16_strchr</b><i> (const uint16_t *<var>str</var>, ucs4_t <var>uc</var>)</i>
 701 <a name="IDX127"></a>
 702 </dt>
 703 <dt><u>Function:</u> uint32_t * <b>u32_strchr</b><i> (const uint32_t *<var>str</var>, ucs4_t <var>uc</var>)</i>
 704 <a name="IDX128"></a>
 705 </dt>
 706 <dd><p>Finds the first occurrence of <var>uc</var> in <var>str</var>.
 707 </p>
 708 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strchr.html"><code>strchr</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcschr.html"><code>wcschr</code></a>, except
 709 that it operates on Unicode strings.
 710 </p></dd></dl>
 711
 712 <dl>
 713 <dt><u>Function:</u> uint8_t * <b>u8_strrchr</b><i> (const uint8_t *<var>str</var>, ucs4_t <var>uc</var>)</i>
 714 <a name="IDX129"></a>
 715 </dt>
 716 <dt><u>Function:</u> uint16_t * <b>u16_strrchr</b><i> (const uint16_t *<var>str</var>, ucs4_t <var>uc</var>)</i>
 717 <a name="IDX130"></a>
 718 </dt>
 719 <dt><u>Function:</u> uint32_t * <b>u32_strrchr</b><i> (const uint32_t *<var>str</var>, ucs4_t <var>uc</var>)</i>
 720 <a name="IDX131"></a>
 721 </dt>
 722 <dd><p>Finds the last occurrence of <var>uc</var> in <var>str</var>.
 723 </p>
 724 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strrchr.html"><code>strrchr</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcsrchr.html"><code>wcsrchr</code></a>, except
 725 that it operates on Unicode strings.
 726 </p></dd></dl>
 727
 728 <p>The following functions search for the first occurrence of some Unicode
 729 character in or outside a given set of Unicode characters.
 730 </p>
 731 <dl>
 732 <dt><u>Function:</u> size_t <b>u8_strcspn</b><i> (const uint8_t *<var>str</var>, const uint8_t *<var>reject</var>)</i>
 733 <a name="IDX132"></a>
 734 </dt>
 735 <dt><u>Function:</u> size_t <b>u16_strcspn</b><i> (const uint16_t *<var>str</var>, const uint16_t *<var>reject</var>)</i>
 736 <a name="IDX133"></a>
 737 </dt>
 738 <dt><u>Function:</u> size_t <b>u32_strcspn</b><i> (const uint32_t *<var>str</var>, const uint32_t *<var>reject</var>)</i>
 739 <a name="IDX134"></a>
 740 </dt>
 741 <dd><p>Returns the length of the initial segment of <var>str</var> which consists entirely
 742 of Unicode characters not in <var>reject</var>.
 743 </p>
 744 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strcspn.html"><code>strcspn</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcscspn.html"><code>wcscspn</code></a>, except
 745 that it operates on Unicode strings.
 746 </p></dd></dl>
 747
 748 <dl>
 749 <dt><u>Function:</u> size_t <b>u8_strspn</b><i> (const uint8_t *<var>str</var>, const uint8_t *<var>accept</var>)</i>
 750 <a name="IDX135"></a>
 751 </dt>
 752 <dt><u>Function:</u> size_t <b>u16_strspn</b><i> (const uint16_t *<var>str</var>, const uint16_t *<var>accept</var>)</i>
 753 <a name="IDX136"></a>
 754 </dt>
 755 <dt><u>Function:</u> size_t <b>u32_strspn</b><i> (const uint32_t *<var>str</var>, const uint32_t *<var>accept</var>)</i>
 756 <a name="IDX137"></a>
 757 </dt>
 758 <dd><p>Returns the length of the initial segment of <var>str</var> which consists entirely
 759 of Unicode characters in <var>accept</var>.
 760 </p>
 761 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strspn.html"><code>strspn</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcsspn.html"><code>wcsspn</code></a>, except
 762 that it operates on Unicode strings.
 763 </p></dd></dl>
 764
 765 <dl>
 766 <dt><u>Function:</u> uint8_t * <b>u8_strpbrk</b><i> (const uint8_t *<var>str</var>, const uint8_t *<var>accept</var>)</i>
 767 <a name="IDX138"></a>
 768 </dt>
 769 <dt><u>Function:</u> uint16_t * <b>u16_strpbrk</b><i> (const uint16_t *<var>str</var>, const uint16_t *<var>accept</var>)</i>
 770 <a name="IDX139"></a>
 771 </dt>
 772 <dt><u>Function:</u> uint32_t * <b>u32_strpbrk</b><i> (const uint32_t *<var>str</var>, const uint32_t *<var>accept</var>)</i>
 773 <a name="IDX140"></a>
 774 </dt>
 775 <dd><p>Finds the first occurrence in <var>str</var> of any character in <var>accept</var>.
 776 </p>
 777 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strpbrk.html"><code>strpbrk</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcspbrk.html"><code>wcspbrk</code></a>, except
 778 that it operates on Unicode strings.
 779 </p></dd></dl>
 780
 781 <a name="IDX141"></a>
 782 <p>The following functions search whether a given Unicode string is a substring
 783 of another Unicode string.
 784 </p>
 785 <dl>
 786 <dt><u>Function:</u> uint8_t * <b>u8_strstr</b><i> (const uint8_t *<var>haystack</var>, const uint8_t *<var>needle</var>)</i>
 787 <a name="IDX142"></a>
 788 </dt>
 789 <dt><u>Function:</u> uint16_t * <b>u16_strstr</b><i> (const uint16_t *<var>haystack</var>, const uint16_t *<var>needle</var>)</i>
 790 <a name="IDX143"></a>
 791 </dt>
 792 <dt><u>Function:</u> uint32_t * <b>u32_strstr</b><i> (const uint32_t *<var>haystack</var>, const uint32_t *<var>needle</var>)</i>
 793 <a name="IDX144"></a>
 794 </dt>
 795 <dd><p>Finds the first occurrence of <var>needle</var> in <var>haystack</var>.
 796 </p>
 797 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strstr.html"><code>strstr</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcsstr.html"><code>wcsstr</code></a>, except
 798 that it operates on Unicode strings.
 799 </p></dd></dl>
 800
 801 <dl>
 802 <dt><u>Function:</u> bool <b>u8_startswith</b><i> (const uint8_t *<var>str</var>, const uint8_t *<var>prefix</var>)</i>
 803 <a name="IDX145"></a>
 804 </dt>
 805 <dt><u>Function:</u> bool <b>u16_startswith</b><i> (const uint16_t *<var>str</var>, const uint16_t *<var>prefix</var>)</i>
 806 <a name="IDX146"></a>
 807 </dt>
 808 <dt><u>Function:</u> bool <b>u32_startswith</b><i> (const uint32_t *<var>str</var>, const uint32_t *<var>prefix</var>)</i>
 809 <a name="IDX147"></a>
 810 </dt>
 811 <dd><p>Tests whether <var>str</var> starts with <var>prefix</var>.
 812 </p></dd></dl>
 813
 814 <dl>
 815 <dt><u>Function:</u> bool <b>u8_endswith</b><i> (const uint8_t *<var>str</var>, const uint8_t *<var>suffix</var>)</i>
 816 <a name="IDX148"></a>
 817 </dt>
 818 <dt><u>Function:</u> bool <b>u16_endswith</b><i> (const uint16_t *<var>str</var>, const uint16_t *<var>suffix</var>)</i>
 819 <a name="IDX149"></a>
 820 </dt>
 821 <dt><u>Function:</u> bool <b>u32_endswith</b><i> (const uint32_t *<var>str</var>, const uint32_t *<var>suffix</var>)</i>
 822 <a name="IDX150"></a>
 823 </dt>
 824 <dd><p>Tests whether <var>str</var> ends with <var>suffix</var>.
 825 </p></dd></dl>
 826
 827 <p>The following function does one step in tokenizing a Unicode string.
 828 </p>
 829 <dl>
 830 <dt><u>Function:</u> uint8_t * <b>u8_strtok</b><i> (uint8_t *<var>str</var>, const uint8_t *<var>delim</var>, uint8_t **<var>ptr</var>)</i>
 831 <a name="IDX151"></a>
 832 </dt>
 833 <dt><u>Function:</u> uint16_t * <b>u16_strtok</b><i> (uint16_t *<var>str</var>, const uint16_t *<var>delim</var>, uint16_t **<var>ptr</var>)</i>
 834 <a name="IDX152"></a>
 835 </dt>
 836 <dt><u>Function:</u> uint32_t * <b>u32_strtok</b><i> (uint32_t *<var>str</var>, const uint32_t *<var>delim</var>, uint32_t **<var>ptr</var>)</i>
 837 <a name="IDX153"></a>
 838 </dt>
 839 <dd><p>Divides <var>str</var> into tokens separated by characters in <var>delim</var>.
 840 </p>
 841 <p>This function is similar to <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/strtok_r.html"><code>strtok_r</code></a> and <a href="http://www.opengroup.org/onlinepubs/9699919799/functions/wcstok.html"><code>wcstok</code></a>, except
 842 that it operates on Unicode strings.  Its interface is actually more similar to
 843 <code>wcstok</code> than to <code>strtok</code>.
 844 </p></dd></dl>
 845 <hr size="6">
 846 <table cellpadding="1" cellspacing="1" border="0">
 847 <tr><td valign="middle" align="left">[<a href="#SEC11" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
 848 <td valign="middle" align="left">[<a href="libunistring_5.html#SEC17" title="Next chapter"> &gt;&gt; </a>]</td>
 849 <td valign="middle" align="left"> &nbsp; </td>
 850 <td valign="middle" align="left"> &nbsp; </td>
 851 <td valign="middle" align="left"> &nbsp; </td>
 852 <td valign="middle" align="left"> &nbsp; </td>
 853 <td valign="middle" align="left"> &nbsp; </td>
 854 <td valign="middle" align="left">[<a href="libunistring.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
 855 <td valign="middle" align="left">[<a href="libunistring.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
 856 <td valign="middle" align="left">[<a href="libunistring_18.html#SEC71" title="Index">Index</a>]</td>
 857 <td valign="middle" align="left">[<a href="libunistring_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
 858 </tr></table>
 859 <p>
 860  <font size="-1">
 861   This document was generated by <em>Bruno Haible</em> on <em>March, 30 2010</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html 1.78a</em></a>.
 862  </font>
 863  <br>
 864
 865 </p>
 866 </body>
 867 </html>