doc/unistr.texi

   1 @node unistr.h
   2 @chapter Elementary Unicode string functions @code{<unistr.h>}
   3
   4 This include file declares elementary functions for Unicode strings.  It is
   5 essentially the equivalent of what @code{<string.h>} is for C strings.
   6
   7 @menu
   8 * Elementary string checks::
   9 * Elementary string conversions::
  10 * Elementary string functions::
  11 * Elementary string functions with memory allocation::
  12 * Elementary string functions on NUL terminated strings::
  13 @end menu
  14
  15 @node Elementary string checks
  16 @section Elementary string checks
  17
  18 @cindex validity
  19 @cindex verification
  20 The following function is available to verify the integrity of a Unicode string.
  21
  22 @deftypefun {const uint8_t *} u8_check (const uint8_t *@var{s}, size_t @var{n})
  23 @deftypefunx {const uint16_t *} u16_check (const uint16_t *@var{s}, size_t @var{n})
  24 @deftypefunx {const uint32_t *} u32_check (const uint32_t *@var{s}, size_t @var{n})
  25 This function checks whether a Unicode string is well-formed.
  26 It returns NULL if valid, or a pointer to the first invalid unit otherwise.
  27 @end deftypefun
  28
  29 @node Elementary string conversions
  30 @section Elementary string conversions
  31
  32 @cindex converting
  33 The following functions perform conversions between the different forms of Unicode strings.
  34
  35 @deftypefun {uint16_t *} u8_to_u16 (const uint8_t *@var{s}, size_t @var{n}, uint16_t *@var{resultbuf}, size_t *@var{lengthp})
  36 Converts an UTF-8 string to an UTF-16 string.
  37 @end deftypefun
  38
  39 @deftypefun {uint32_t *} u8_to_u32 (const uint8_t *@var{s}, size_t @var{n}, uint32_t *@var{resultbuf}, size_t *@var{lengthp})
  40 Converts an UTF-8 string to an UTF-32 string.
  41 @end deftypefun
  42
  43 @deftypefun {uint8_t *} u16_to_u8 (const uint16_t *@var{s}, size_t @var{n}, uint8_t *@var{resultbuf}, size_t *@var{lengthp})
  44 Converts an UTF-16 string to an UTF-8 string.
  45 @end deftypefun
  46
  47 @deftypefun {uint32_t *} u16_to_u32 (const uint16_t *@var{s}, size_t @var{n}, uint32_t *@var{resultbuf}, size_t *@var{lengthp})
  48 Converts an UTF-16 string to an UTF-32 string.
  49 @end deftypefun
  50
  51 @deftypefun {uint8_t *} u32_to_u8 (const uint32_t *@var{s}, size_t @var{n}, uint8_t *@var{resultbuf}, size_t *@var{lengthp})
  52 Converts an UTF-32 string to an UTF-8 string.
  53 @end deftypefun
  54
  55 @deftypefun {uint16_t *} u32_to_u16 (const uint32_t *@var{s}, size_t @var{n}, uint16_t *@var{resultbuf}, size_t *@var{lengthp})
  56 Converts an UTF-32 string to an UTF-16 string.
  57 @end deftypefun
  58
  59 @node Elementary string functions
  60 @section Elementary string functions
  61
  62 @cindex iterating
  63 The following functions inspect and return details about the first character
  64 in a Unicode string.
  65
  66 @deftypefun int u8_mblen (const uint8_t *@var{s}, size_t @var{n})
  67 @deftypefunx int u16_mblen (const uint16_t *@var{s}, size_t @var{n})
  68 @deftypefunx int u32_mblen (const uint32_t *@var{s}, size_t @var{n})
  69 Returns the length (number of units) of the first character in @var{s}, which
  70 is no longer than @var{n}.  Returns 0 if it is the NUL character.  Returns -1
  71 upon failure.
  72
  73 This function is similar to @posixfunc{mblen}, except that it operates on a
  74 Unicode string and that @var{s} must not be NULL.
  75 @end deftypefun
  76
  77 @deftypefun int u8_mbtouc_unsafe (ucs4_t *@var{puc}, const uint8_t *@var{s}, size_t @var{n})
  78 @deftypefunx int u16_mbtouc_unsafe (ucs4_t *@var{puc}, const uint16_t *@var{s}, size_t @var{n})
  79 @deftypefunx int u32_mbtouc_unsafe (ucs4_t *@var{puc}, const uint32_t *@var{s}, size_t @var{n})
  80 Returns the length (number of units) of the first character in @var{s},
  81 putting its @code{ucs4_t} representation in @code{*@var{puc}}.  Upon failure,
  82 @code{*@var{puc}} is set to @code{0xfffd}, and an appropriate number of units
  83 is returned.
  84
  85 The number of available units, @var{n}, must be > 0.
  86
  87 This function is similar to @posixfunc{mbtowc}, except that it operates on a
  88 Unicode string, @var{puc} and @var{s} must not be NULL, @var{n} must be > 0,
  89 and the NUL character is not treated specially.
  90 @end deftypefun
  91
  92 @deftypefun int u8_mbtouc (ucs4_t *@var{puc}, const uint8_t *@var{s}, size_t @var{n})
  93 @deftypefunx int u16_mbtouc (ucs4_t *@var{puc}, const uint16_t *@var{s}, size_t @var{n})
  94 @deftypefunx int u32_mbtouc (ucs4_t *@var{puc}, const uint32_t *@var{s}, size_t @var{n})
  95 This function is like @code{u8_mbtouc_unsafe}, except that it will detect an
  96 invalid UTF-8 character, even if the library is compiled without
  97 @option{--enable-safety}.
  98 @end deftypefun
  99
 100 @deftypefun int u8_mbtoucr (ucs4_t *@var{puc}, const uint8_t *@var{s}, size_t @var{n})
 101 @deftypefunx int u16_mbtoucr (ucs4_t *@var{puc}, const uint16_t *@var{s}, size_t @var{n})
 102 @deftypefunx int u32_mbtoucr (ucs4_t *@var{puc}, const uint32_t *@var{s}, size_t @var{n})
 103 Returns the length (number of units) of the first character in @var{s},
 104 putting its @code{ucs4_t} representation in @code{*@var{puc}}.  Upon failure,
 105 @code{*@var{puc}} is set to @code{0xfffd}, and -1 is returned for an invalid
 106 sequence of units, -2 is returned for an incomplete sequence of units.
 107
 108 The number of available units, @var{n}, must be > 0.
 109
 110 This function is similar to @code{u8_mbtouc}, except that the return value
 111 gives more details about the failure, similar to @posixfunc{mbrtowc}.
 112 @end deftypefun
 113
 114 The following function stores a Unicode character as a Unicode string in
 115 memory.
 116
 117 @deftypefun int u8_uctomb (uint8_t *@var{s}, ucs4_t @var{uc}, int @var{n})
 118 @deftypefunx int u16_uctomb (uint16_t *@var{s}, ucs4_t @var{uc}, int @var{n})
 119 @deftypefunx int u32_uctomb (uint32_t *@var{s}, ucs4_t @var{uc}, int @var{n})
 120 Puts the multibyte character represented by @var{uc} in @var{s}, returning its
 121 length.  Returns -1 upon failure, -2 if the number of available units, @var{n},
 122 is too small.  The latter case cannot occur if @var{n} >= 6/2/1, respectively.
 123
 124 This function is similar to @posixfunc{wctomb}, except that it operates on a
 125 Unicode strings, @var{s} must not be NULL, and the argument @var{n} must be
 126 specified.
 127 @end deftypefun
 128
 129 @cindex copying
 130 The following functions copy Unicode strings in memory.
 131
 132 @deftypefun {uint8_t *} u8_cpy (uint8_t *@var{dest}, const uint8_t *@var{src}, size_t @var{n})
 133 @deftypefunx {uint16_t *} u16_cpy (uint16_t *@var{dest}, const uint16_t *@var{src}, size_t @var{n})
 134 @deftypefunx {uint32_t *} u32_cpy (uint32_t *@var{dest}, const uint32_t *@var{src}, size_t @var{n})
 135 Copies @var{n} units from @var{src} to @var{dest}.
 136
 137 This function is similar to @posixfunc{memcpy}, except that it operates on
 138 Unicode strings.
 139 @end deftypefun
 140
 141 @deftypefun {uint8_t *} u8_move (uint8_t *@var{dest}, const uint8_t *@var{src}, size_t @var{n})
 142 @deftypefunx {uint16_t *} u16_move (uint16_t *@var{dest}, const uint16_t *@var{src}, size_t @var{n})
 143 @deftypefunx {uint32_t *} u32_move (uint32_t *@var{dest}, const uint32_t *@var{src}, size_t @var{n})
 144 Copies @var{n} units from @var{src} to @var{dest}, guaranteeing correct
 145 behavior for overlapping memory areas.
 146
 147 This function is similar to @posixfunc{memmove}, except that it operates on
 148 Unicode strings.
 149 @end deftypefun
 150
 151 The following function fills a Unicode string.
 152
 153 @deftypefun {uint8_t *} u8_set (uint8_t *@var{s}, ucs4_t @var{uc}, size_t @var{n})
 154 @deftypefunx {uint16_t *} u16_set (uint16_t *@var{s}, ucs4_t @var{uc}, size_t @var{n})
 155 @deftypefunx {uint32_t *} u32_set (uint32_t *@var{s}, ucs4_t @var{uc}, size_t @var{n})
 156 Sets the first @var{n} characters of @var{s} to @var{uc}.  @var{uc} should be
 157 a character that occupies only 1 unit.
 158
 159 This function is similar to @posixfunc{memset}, except that it operates on
 160 Unicode strings.
 161 @end deftypefun
 162
 163 @cindex comparing
 164 The following function compares two Unicode strings of the same length.
 165
 166 @deftypefun int u8_cmp (const uint8_t *@var{s1}, const uint8_t *@var{s2}, size_t @var{n})
 167 @deftypefunx int u16_cmp (const uint16_t *@var{s1}, const uint16_t *@var{s2}, size_t @var{n})
 168 @deftypefunx int u32_cmp (const uint32_t *@var{s1}, const uint32_t *@var{s2}, size_t @var{n})
 169 Compares @var{s1} and @var{s2}, each of length @var{n}, lexicographically.
 170 Returns a negative value if @var{s1} compares smaller than @var{s2},
 171 a positive value if @var{s1} compares larger than @var{s2}, or 0 if
 172 they compare equal.
 173
 174 This function is similar to @posixfunc{memcmp}, except that it operates on
 175 Unicode strings.
 176 @end deftypefun
 177
 178 The following function compares two Unicode strings of possibly different
 179 lengths.
 180
 181 @deftypefun int u8_cmp2 (const uint8_t *@var{s1}, size_t @var{n1}, const uint8_t *@var{s2}, size_t @var{n2})
 182 @deftypefunx int u16_cmp2 (const uint16_t *@var{s1}, size_t @var{n1}, const uint16_t *@var{s2}, size_t @var{n2})
 183 @deftypefunx int u32_cmp2 (const uint32_t *@var{s1}, size_t @var{n1}, const uint32_t *@var{s2}, size_t @var{n2})
 184 Compares @var{s1} and @var{s2}, lexicographically.
 185 Returns a negative value if @var{s1} compares smaller than @var{s2},
 186 a positive value if @var{s1} compares larger than @var{s2}, or 0 if
 187 they compare equal.
 188
 189 This function is similar to the gnulib function @func{memcmp2}, except that it
 190 operates on Unicode strings.
 191 @end deftypefun
 192
 193 @cindex searching, for a character
 194 The following function searches for a given Unicode character.
 195
 196 @deftypefun {uint8_t *} u8_chr (const uint8_t *@var{s}, size_t @var{n}, ucs4_t @var{uc})
 197 @deftypefunx {uint16_t *} u16_chr (const uint16_t *@var{s}, size_t @var{n}, ucs4_t @var{uc})
 198 @deftypefunx {uint32_t *} u32_chr (const uint32_t *@var{s}, size_t @var{n}, ucs4_t @var{uc})
 199 Searches the string at @var{s} for @var{uc}.  Returns a pointer to the first
 200 occurrence of @var{uc} in @var{s}, or NULL if @var{uc} does not occur in
 201 @var{s}.
 202
 203 This function is similar to @posixfunc{memchr}, except that it operates on
 204 Unicode strings.
 205 @end deftypefun
 206
 207 @cindex counting
 208 The following function counts the number of Unicode characters.
 209
 210 @deftypefun size_t u8_mbsnlen (const uint8_t *@var{s}, size_t @var{n})
 211 @deftypefunx size_t u16_mbsnlen (const uint16_t *@var{s}, size_t @var{n})
 212 @deftypefunx size_t u32_mbsnlen (const uint32_t *@var{s}, size_t @var{n})
 213 Counts and returns the number of Unicode characters in the @var{n} units
 214 from @var{s}.
 215
 216 This function is similar to the gnulib function @func{mbsnlen}, except that
 217 it operates on Unicode strings.
 218 @end deftypefun
 219
 220 @node Elementary string functions with memory allocation
 221 @section Elementary string functions with memory allocation
 222
 223 @cindex duplicating
 224 The following function copies a Unicode string.
 225
 226 @deftypefun {uint8_t *} u8_cpy_alloc (const uint8_t *@var{s}, size_t @var{n})
 227 @deftypefunx {uint16_t *} u16_cpy_alloc (const uint16_t *@var{s}, size_t @var{n})
 228 @deftypefunx {uint32_t *} u32_cpy_alloc (const uint32_t *@var{s}, size_t @var{n})
 229 Makes a freshly allocated copy of @var{s}, of length @var{n}.
 230 @end deftypefun
 231
 232 @node Elementary string functions on NUL terminated strings
 233 @section Elementary string functions on NUL terminated strings
 234
 235 The following functions inspect and return details about the first character
 236 in a Unicode string.
 237
 238 @deftypefun int u8_strmblen (const uint8_t *@var{s})
 239 @deftypefunx int u16_strmblen (const uint16_t *@var{s})
 240 @deftypefunx int u32_strmblen (const uint32_t *@var{s})
 241 Returns the length (number of units) of the first character in @var{s}.
 242 Returns 0 if it is the NUL character.  Returns -1 upon failure.
 243 @end deftypefun
 244
 245 @cindex iterating
 246 @deftypefun int u8_strmbtouc (ucs4_t *@var{puc}, const uint8_t *@var{s})
 247 @deftypefunx int u16_strmbtouc (ucs4_t *@var{puc}, const uint16_t *@var{s})
 248 @deftypefunx int u32_strmbtouc (ucs4_t *@var{puc}, const uint32_t *@var{s})
 249 Returns the length (number of units) of the first character in @var{s},
 250 putting its @code{ucs4_t} representation in @code{*@var{puc}}.  Returns 0
 251 if it is the NUL character.  Returns -1 upon failure.
 252 @end deftypefun
 253
 254 @deftypefun {const uint8_t *} u8_next (ucs4_t *@var{puc}, const uint8_t *@var{s})
 255 @deftypefunx {const uint16_t *} u16_next (ucs4_t *@var{puc}, const uint16_t *@var{s})
 256 @deftypefunx {const uint32_t *} u32_next (ucs4_t *@var{puc}, const uint32_t *@var{s})
 257 Forward iteration step.  Advances the pointer past the next character,
 258 or returns NULL if the end of the string has been reached.  Puts the
 259 character's @code{ucs4_t} representation in @code{*@var{puc}}.
 260 @end deftypefun
 261
 262 The following function inspects and returns details about the previous
 263 character in a Unicode string.
 264
 265 @deftypefun {const uint8_t *} u8_prev (ucs4_t *@var{puc}, const uint8_t *@var{s}, const uint8_t *@var{start})
 266 @deftypefunx {const uint16_t *} u16_prev (ucs4_t *@var{puc}, const uint16_t *@var{s}, const uint16_t *@var{start})
 267 @deftypefunx {const uint32_t *} u32_prev (ucs4_t *@var{puc}, const uint32_t *@var{s}, const uint32_t *@var{start})
 268 Backward iteration step.  Advances the pointer to point to the previous
 269 character, or returns NULL if the beginning of the string had been reached.
 270 Puts the character's @code{ucs4_t} representation in @code{*@var{puc}}.
 271 @end deftypefun
 272
 273 The following functions determine the length of a Unicode string.
 274
 275 @deftypefun size_t u8_strlen (const uint8_t *@var{s})
 276 @deftypefunx size_t u16_strlen (const uint16_t *@var{s})
 277 @deftypefunx size_t u32_strlen (const uint32_t *@var{s})
 278 Returns the number of units in @var{s}.
 279
 280 This function is similar to @posixfunc{strlen} and @posixfunc{wcslen}, except
 281 that it operates on Unicode strings.
 282 @end deftypefun
 283
 284 @deftypefun size_t u8_strnlen (const uint8_t *@var{s}, size_t @var{maxlen})
 285 @deftypefunx size_t u16_strnlen (const uint16_t *@var{s}, size_t @var{maxlen})
 286 @deftypefunx size_t u32_strnlen (const uint32_t *@var{s}, size_t @var{maxlen})
 287 Returns the number of units in @var{s}, but at most @var{maxlen}.
 288
 289 This function is similar to @posixfunc{strnlen} and @posixfunc{wcsnlen}, except
 290 that it operates on Unicode strings.
 291 @end deftypefun
 292
 293 @cindex copying
 294 The following functions copy portions of Unicode strings in memory.
 295
 296 @deftypefun {uint8_t *} u8_strcpy (uint8_t *@var{dest}, const uint8_t *@var{src})
 297 @deftypefunx {uint16_t *} u16_strcpy (uint16_t *@var{dest}, const uint16_t *@var{src})
 298 @deftypefunx {uint32_t *} u32_strcpy (uint32_t *@var{dest}, const uint32_t *@var{src})
 299 Copies @var{src} to @var{dest}.
 300
 301 This function is similar to @posixfunc{strcpy} and @posixfunc{wcscpy}, except
 302 that it operates on Unicode strings.
 303 @end deftypefun
 304
 305 @deftypefun {uint8_t *} u8_stpcpy (uint8_t *@var{dest}, const uint8_t *@var{src})
 306 @deftypefunx {uint16_t *} u16_stpcpy (uint16_t *@var{dest}, const uint16_t *@var{src})
 307 @deftypefunx {uint32_t *} u32_stpcpy (uint32_t *@var{dest}, const uint32_t *@var{src})
 308 Copies @var{src} to @var{dest}, returning the address of the terminating NUL
 309 in @var{dest}.
 310
 311 This function is similar to @posixfunc{stpcpy}, except that it operates on
 312 Unicode strings.
 313 @end deftypefun
 314
 315 @deftypefun {uint8_t *} u8_strncpy (uint8_t *@var{dest}, const uint8_t *@var{src}, size_t @var{n})
 316 @deftypefunx {uint16_t *} u16_strncpy (uint16_t *@var{dest}, const uint16_t *@var{src}, size_t @var{n})
 317 @deftypefunx {uint32_t *} u32_strncpy (uint32_t *@var{dest}, const uint32_t *@var{src}, size_t @var{n})
 318 Copies no more than @var{n} units of @var{src} to @var{dest}.
 319
 320 This function is similar to @posixfunc{strncpy} and @posixfunc{wcsncpy}, except
 321 that it operates on Unicode strings.
 322 @end deftypefun
 323
 324 @deftypefun {uint8_t *} u8_stpncpy (uint8_t *@var{dest}, const uint8_t *@var{src}, size_t @var{n})
 325 @deftypefunx {uint16_t *} u16_stpncpy (uint16_t *@var{dest}, const uint16_t *@var{src}, size_t @var{n})
 326 @deftypefunx {uint32_t *} u32_stpncpy (uint32_t *@var{dest}, const uint32_t *@var{src}, size_t @var{n})
 327 Copies no more than @var{n} units of @var{src} to @var{dest}.  Returns a
 328 pointer past the last non-NUL unit written into @var{dest}.  In other words,
 329 if the units written into @var{dest} include a NUL, the return value is the
 330 address of the first such NUL unit, otherwise it is
 331 @code{@var{dest} + @var{n}}.
 332
 333 This function is similar to @posixfunc{stpncpy}, except that it operates on
 334 Unicode strings.
 335 @end deftypefun
 336
 337 @deftypefun {uint8_t *} u8_strcat (uint8_t *@var{dest}, const uint8_t *@var{src})
 338 @deftypefunx {uint16_t *} u16_strcat (uint16_t *@var{dest}, const uint16_t *@var{src})
 339 @deftypefunx {uint32_t *} u32_strcat (uint32_t *@var{dest}, const uint32_t *@var{src})
 340 Appends @var{src} onto @var{dest}.
 341
 342 This function is similar to @posixfunc{strcat} and @posixfunc{wcscat}, except
 343 that it operates on Unicode strings.
 344 @end deftypefun
 345
 346 @deftypefun {uint8_t *} u8_strncat (uint8_t *@var{dest}, const uint8_t *@var{src}, size_t @var{n})
 347 @deftypefunx {uint16_t *} u16_strncat (uint16_t *@var{dest}, const uint16_t *@var{src}, size_t @var{n})
 348 @deftypefunx {uint32_t *} u32_strncat (uint32_t *@var{dest}, const uint32_t *@var{src}, size_t @var{n})
 349 Appends no more than @var{n} units of @var{src} onto @var{dest}.
 350
 351 This function is similar to @posixfunc{strncat} and @posixfunc{wcsncat}, except
 352 that it operates on Unicode strings.
 353 @end deftypefun
 354
 355 @cindex comparing
 356 The following functions compare two Unicode strings.
 357
 358 @deftypefun int u8_strcmp (const uint8_t *@var{s1}, const uint8_t *@var{s2})
 359 @deftypefunx int u16_strcmp (const uint16_t *@var{s1}, const uint16_t *@var{s2})
 360 @deftypefunx int u32_strcmp (const uint32_t *@var{s1}, const uint32_t *@var{s2})
 361 Compares @var{s1} and @var{s2}, lexicographically.
 362 Returns a negative value if @var{s1} compares smaller than @var{s2},
 363 a positive value if @var{s1} compares larger than @var{s2}, or 0 if
 364 they compare equal.
 365
 366 This function is similar to @posixfunc{strcmp} and @posixfunc{wcscmp}, except
 367 that it operates on Unicode strings.
 368 @end deftypefun
 369
 370 @cindex comparing, with collation rules
 371 @deftypefun int u8_strcoll (const uint8_t *@var{s1}, const uint8_t *@var{s2})
 372 @deftypefunx int u16_strcoll (const uint16_t *@var{s1}, const uint16_t *@var{s2})
 373 @deftypefunx int u32_strcoll (const uint32_t *@var{s1}, const uint32_t *@var{s2})
 374 Compares @var{s1} and @var{s2} using the collation rules of the current
 375 locale.
 376 Returns -1 if @var{s1} < @var{s2}, 0 if @var{s1} = @var{s2}, 1 if
 377 @var{s1} > @var{s2}.  Upon failure, sets @code{errno} and returns any value.
 378
 379 This function is similar to @posixfunc{strcoll} and @posixfunc{wcscoll}, except
 380 that it operates on Unicode strings.
 381
 382 Note that this function may consider different canonical normalizations
 383 of the same string as having a large distance.  It is therefore better to
 384 use the function @code{u8_normcoll} instead of this one; see @ref{uninorm.h}.
 385 @end deftypefun
 386
 387 @deftypefun int u8_strncmp (const uint8_t *@var{s1}, const uint8_t *@var{s2}, size_t @var{n})
 388 @deftypefunx int u16_strncmp (const uint16_t *@var{s1}, const uint16_t *@var{s2}, size_t @var{n})
 389 @deftypefunx int u32_strncmp (const uint32_t *@var{s1}, const uint32_t *@var{s2}, size_t @var{n})
 390 Compares no more than @var{n} units of @var{s1} and @var{s2}.
 391
 392 This function is similar to @posixfunc{strncmp} and @posixfunc{wcsncmp}, except
 393 that it operates on Unicode strings.
 394 @end deftypefun
 395
 396 @cindex duplicating
 397 The following function allocates a duplicate of a Unicode string.
 398
 399 @deftypefun {uint8_t *} u8_strdup (const uint8_t *@var{s})
 400 @deftypefunx {uint16_t *} u16_strdup (const uint16_t *@var{s})
 401 @deftypefunx {uint32_t *} u32_strdup (const uint32_t *@var{s})
 402 Duplicates @var{s}, returning an identical malloc'd string.
 403
 404 This function is similar to @posixfunc{strdup} and @posixfunc{wcsdup}, except
 405 that it operates on Unicode strings.
 406 @end deftypefun
 407
 408 @cindex searching, for a character
 409 The following functions search for a given Unicode character.
 410
 411 @deftypefun {uint8_t *} u8_strchr (const uint8_t *@var{str}, ucs4_t @var{uc})
 412 @deftypefunx {uint16_t *} u16_strchr (const uint16_t *@var{str}, ucs4_t @var{uc})
 413 @deftypefunx {uint32_t *} u32_strchr (const uint32_t *@var{str}, ucs4_t @var{uc})
 414 Finds the first occurrence of @var{uc} in @var{str}.
 415
 416 This function is similar to @posixfunc{strchr} and @posixfunc{wcschr}, except
 417 that it operates on Unicode strings.
 418 @end deftypefun
 419
 420 @deftypefun {uint8_t *} u8_strrchr (const uint8_t *@var{str}, ucs4_t @var{uc})
 421 @deftypefunx {uint16_t *} u16_strrchr (const uint16_t *@var{str}, ucs4_t @var{uc})
 422 @deftypefunx {uint32_t *} u32_strrchr (const uint32_t *@var{str}, ucs4_t @var{uc})
 423 Finds the last occurrence of @var{uc} in @var{str}.
 424
 425 This function is similar to @posixfunc{strrchr} and @posixfunc{wcsrchr}, except
 426 that it operates on Unicode strings.
 427 @end deftypefun
 428
 429 The following functions search for the first occurrence of some Unicode
 430 character in or outside a given set of Unicode characters.
 431
 432 @deftypefun size_t u8_strcspn (const uint8_t *@var{str}, const uint8_t *@var{reject})
 433 @deftypefunx size_t u16_strcspn (const uint16_t *@var{str}, const uint16_t *@var{reject})
 434 @deftypefunx size_t u32_strcspn (const uint32_t *@var{str}, const uint32_t *@var{reject})
 435 Returns the length of the initial segment of @var{str} which consists entirely
 436 of Unicode characters not in @var{reject}.
 437
 438 This function is similar to @posixfunc{strcspn} and @posixfunc{wcscspn}, except
 439 that it operates on Unicode strings.
 440 @end deftypefun
 441
 442 @deftypefun size_t u8_strspn (const uint8_t *@var{str}, const uint8_t *@var{accept})
 443 @deftypefunx size_t u16_strspn (const uint16_t *@var{str}, const uint16_t *@var{accept})
 444 @deftypefunx size_t u32_strspn (const uint32_t *@var{str}, const uint32_t *@var{accept})
 445 Returns the length of the initial segment of @var{str} which consists entirely
 446 of Unicode characters in @var{accept}.
 447
 448 This function is similar to @posixfunc{strspn} and @posixfunc{wcsspn}, except
 449 that it operates on Unicode strings.
 450 @end deftypefun
 451
 452 @deftypefun {uint8_t *} u8_strpbrk (const uint8_t *@var{str}, const uint8_t *@var{accept})
 453 @deftypefunx {uint16_t *} u16_strpbrk (const uint16_t *@var{str}, const uint16_t *@var{accept})
 454 @deftypefunx {uint32_t *} u32_strpbrk (const uint32_t *@var{str}, const uint32_t *@var{accept})
 455 Finds the first occurrence in @var{str} of any character in @var{accept}.
 456
 457 This function is similar to @posixfunc{strpbrk} and @posixfunc{wcspbrk}, except
 458 that it operates on Unicode strings.
 459 @end deftypefun
 460
 461 @cindex searching, for a substring
 462 The following functions search whether a given Unicode string is a substring
 463 of another Unicode string.
 464
 465 @deftypefun {uint8_t *} u8_strstr (const uint8_t *@var{haystack}, const uint8_t *@var{needle})
 466 @deftypefunx {uint16_t *} u16_strstr (const uint16_t *@var{haystack}, const uint16_t *@var{needle})
 467 @deftypefunx {uint32_t *} u32_strstr (const uint32_t *@var{haystack}, const uint32_t *@var{needle})
 468 Finds the first occurrence of @var{needle} in @var{haystack}.
 469
 470 This function is similar to @posixfunc{strstr} and @posixfunc{wcsstr}, except
 471 that it operates on Unicode strings.
 472 @end deftypefun
 473
 474 @deftypefun bool u8_startswith (const uint8_t *@var{str}, const uint8_t *@var{prefix})
 475 @deftypefunx bool u16_startswith (const uint16_t *@var{str}, const uint16_t *@var{prefix})
 476 @deftypefunx bool u32_startswith (const uint32_t *@var{str}, const uint32_t *@var{prefix})
 477 Tests whether @var{str} starts with @var{prefix}.
 478 @end deftypefun
 479
 480 @deftypefun bool u8_endswith (const uint8_t *@var{str}, const uint8_t *@var{suffix})
 481 @deftypefunx bool u16_endswith (const uint16_t *@var{str}, const uint16_t *@var{suffix})
 482 @deftypefunx bool u32_endswith (const uint32_t *@var{str}, const uint32_t *@var{suffix})
 483 Tests whether @var{str} ends with @var{suffix}.
 484 @end deftypefun
 485
 486 The following function does one step in tokenizing a Unicode string.
 487
 488 @deftypefun {uint8_t *} u8_strtok (uint8_t *@var{str}, const uint8_t *@var{delim}, uint8_t **@var{ptr})
 489 @deftypefunx {uint16_t *} u16_strtok (uint16_t *@var{str}, const uint16_t *@var{delim}, uint16_t **@var{ptr})
 490 @deftypefunx {uint32_t *} u32_strtok (uint32_t *@var{str}, const uint32_t *@var{delim}, uint32_t **@var{ptr})
 491 Divides @var{str} into tokens separated by characters in @var{delim}.
 492
 493 This function is similar to @posixfunc{strtok_r} and @posixfunc{wcstok}, except
 494 that it operates on Unicode strings.  Its interface is actually more similar to
 495 @code{wcstok} than to @code{strtok}.
 496 @end deftypefun