Documentation of <unistr.h>.

1 files changed, 462 insertions, 0 deletions

diff --git a/doc/unistr.texi b/doc/unistr.texi
new file mode 100644
index 0000000..51f755a
--- /dev/null
+++ b/doc/unistr.texi
@@ -0,0 +1,462 @@
+@node unistr.h
+@chapter Elementary Unicode string functions @code{<unistr.h>}
+
+This include file declares elementary functions for Unicode strings.  It is
+essentially the equivalent of what @code{<string.h>} is for C strings.
+
+@menu
+* Elementary string checks::
+* Elementary string conversions::
+* Elementary string functions::
+* Elementary string functions with memory allocation::
+* Elementary string functions on NUL terminated strings::
+@end menu
+
+@node Elementary string checks
+@section Elementary string checks
+
+The following function is available to verify the integrity of a Unicode string.
+
+@deftypefun {const uint8_t *} u8_check (const uint8_t *@var{s}, size_t @var{n})
+@deftypefunx {const uint16_t *} u16_check (const uint16_t *@var{s}, size_t @var{n})
+@deftypefunx {const uint32_t *} u32_check (const uint32_t *@var{s}, size_t @var{n})
+This function checks whether a Unicode string is well-formed.
+It returns NULL if valid, or a pointer to the first invalid unit otherwise.
+@end deftypefun
+
+@node Elementary string conversions
+@section Elementary string conversions
+
+The following functions perform conversions between the different forms of Unicode strings.
+
+@deftypefun {uint16_t *} u8_to_u16 (const uint8_t *@var{s}, size_t @var{n}, uint16_t *@var{resultbuf}, size_t *@var{lengthp})
+Converts an UTF-8 string to an UTF-16 string.
+@end deftypefun
+
+@deftypefun {uint32_t *} u8_to_u32 (const uint8_t *@var{s}, size_t @var{n}, uint32_t *@var{resultbuf}, size_t *@var{lengthp})
+Converts an UTF-8 string to an UTF-32 string.
+@end deftypefun
+
+@deftypefun {uint8_t *} u16_to_u8 (const uint16_t *@var{s}, size_t @var{n}, uint8_t *@var{resultbuf}, size_t *@var{lengthp})
+Converts an UTF-16 string to an UTF-8 string.
+@end deftypefun
+
+@deftypefun {uint32_t *} u16_to_u32 (const uint16_t *@var{s}, size_t @var{n}, uint32_t *@var{resultbuf}, size_t *@var{lengthp})
+Converts an UTF-16 string to an UTF-32 string.
+@end deftypefun
+
+@deftypefun {uint8_t *} u32_to_u8 (const uint32_t *@var{s}, size_t @var{n}, uint8_t *@var{resultbuf}, size_t *@var{lengthp})
+Converts an UTF-32 string to an UTF-8 string.
+@end deftypefun
+
+@deftypefun {uint16_t *} u32_to_u16 (const uint32_t *@var{s}, size_t @var{n}, uint16_t *@var{resultbuf}, size_t *@var{lengthp})
+Converts an UTF-32 string to an UTF-16 string.
+@end deftypefun
+
+@node Elementary string functions
+@section Elementary string functions
+
+The following functions inspect and return details about the first character
+in a Unicode string.
+
+@deftypefun int u8_mblen (const uint8_t *@var{s}, size_t @var{n})
+@deftypefunx int u16_mblen (const uint16_t *@var{s}, size_t @var{n})
+@deftypefunx int u32_mblen (const uint32_t *@var{s}, size_t @var{n})
+Returns the length (number of units) of the first character in @var{s}, which
+is no longer than @var{n}.  Returns 0 if it is the NUL character.  Returns -1
+upon failure.
+
+This function is similar to @code{mblen()}, except that it operates on a
+Unicode string and that @var{s} must not be NULL.
+@end deftypefun
+
+@deftypefun int u8_mbtouc_unsafe (ucs4_t *@var{puc}, const uint8_t *@var{s}, size_t @var{n})
+@deftypefunx int u16_mbtouc_unsafe (ucs4_t *@var{puc}, const uint16_t *@var{s}, size_t @var{n})
+@deftypefunx int u32_mbtouc_unsafe (ucs4_t *@var{puc}, const uint32_t *@var{s}, size_t @var{n})
+Returns the length (number of units) of the first character in @var{s},
+putting its @code{ucs4_t} representation in @code{*@var{puc}}.  Upon failure,
+@code{*@var{puc}} is set to @code{0xfffd}, and an appropriate number of units
+is returned.
+
+The number of available units, @var{n}, must be > 0.
+
+This function is similar to @code{mbtowc()}, except that it operates on a
+Unicode string, @var{puc} and @var{s} must not be NULL, @var{n} must be > 0,
+and the NUL character is not treated specially.
+@end deftypefun
+
+@deftypefun int u8_mbtouc (ucs4_t *@var{puc}, const uint8_t *@var{s}, size_t @var{n})
+@deftypefunx int u16_mbtouc (ucs4_t *@var{puc}, const uint16_t *@var{s}, size_t @var{n})
+@deftypefunx int u32_mbtouc (ucs4_t *@var{puc}, const uint32_t *@var{s}, size_t @var{n})
+This function is like @code{u8_mbtouc_unsafe}, except that it will detect an
+invalid UTF-8 character, even if the library is compiled without
+@option{--enable-safety}.
+@end deftypefun
+
+@deftypefun int u8_mbtoucr (ucs4_t *@var{puc}, const uint8_t *@var{s}, size_t @var{n})
+@deftypefunx int u16_mbtoucr (ucs4_t *@var{puc}, const uint16_t *@var{s}, size_t @var{n})
+@deftypefunx int u32_mbtoucr (ucs4_t *@var{puc}, const uint32_t *@var{s}, size_t @var{n})
+Returns the length (number of units) of the first character in @var{s},
+putting its @code{ucs4_t} representation in @code{*@var{puc}}.  Upon failure,
+@code{*@var{puc}} is set to @code{0xfffd}, and -1 is returned for an invalid
+sequence of units, -2 is returned for an incomplete sequence of units.
+
+The number of available units, @var{n}, must be > 0.
+
+This function is similar to @code{u8_mbtouc}, except that the return value
+gives more details about the failure, similar to @code{mbrtowc()}.
+@end deftypefun
+
+The following function stores a Unicode character as a Unicode string in
+memory.
+
+@deftypefun int u8_uctomb (uint8_t *@var{s}, ucs4_t @var{uc}, int @var{n})
+@deftypefunx int u16_uctomb (uint16_t *@var{s}, ucs4_t @var{uc}, int @var{n})
+@deftypefunx int u32_uctomb (uint32_t *@var{s}, ucs4_t @var{uc}, int @var{n})
+Puts the multibyte character represented by @var{uc} in @var{s}, returning its
+length.  Returns -1 upon failure, -2 if the number of available units, @var{n},
+is too small.  The latter case cannot occur if @var{n} >= 6/2/1, respectively.
+
+This function is similar to @code{wctomb()}, except that it operates on a
+Unicode strings, @var{s} must not be NULL, and the argument @var{n} must be
+specified.
+@end deftypefun
+
+The following functions copy Unicode strings in memory.
+
+@deftypefun {uint8_t *} u8_cpy (uint8_t *@var{dest}, const uint8_t *@var{src}, size_t @var{n})
+@deftypefunx {uint16_t *} u16_cpy (uint16_t *@var{dest}, const uint16_t *@var{src}, size_t @var{n})
+@deftypefunx {uint32_t *} u32_cpy (uint32_t *@var{dest}, const uint32_t *@var{src}, size_t @var{n})
+Copies @var{n} units from @var{src} to @var{dest}.
+
+This function is similar to @code{memcpy()}, except that it operates on
+Unicode strings.
+@end deftypefun
+
+@deftypefun {uint8_t *} u8_move (uint8_t *@var{dest}, const uint8_t *@var{src}, size_t @var{n})
+@deftypefunx {uint16_t *} u16_move (uint16_t *@var{dest}, const uint16_t *@var{src}, size_t @var{n})
+@deftypefunx {uint32_t *} u32_move (uint32_t *@var{dest}, const uint32_t *@var{src}, size_t @var{n})
+Copies @var{n} units from @var{src} to @var{dest}, guaranteeing correct
+behavior for overlapping memory areas.
+
+This function is similar to @code{memmove()}, except that it operates on
+Unicode strings.
+@end deftypefun
+
+The following function fills a Unicode string.
+
+@deftypefun {uint8_t *} u8_set (uint8_t *@var{s}, ucs4_t @var{uc}, size_t @var{n})
+@deftypefunx {uint16_t *} u16_set (uint16_t *@var{s}, ucs4_t @var{uc}, size_t @var{n})
+@deftypefunx {uint32_t *} u32_set (uint32_t *@var{s}, ucs4_t @var{uc}, size_t @var{n})
+Sets the first @var{n} characters of @var{s} to @var{uc}.  @var{uc} should be
+a character that occupies only 1 unit.
+
+This function is similar to @code{memset()}, except that it operates on
+Unicode strings.
+@end deftypefun
+
+The following function compares two Unicode strings of the same length.
+
+@deftypefun int u8_cmp (const uint8_t *@var{s1}, const uint8_t *@var{s2}, size_t @var{n})
+@deftypefunx int u16_cmp (const uint16_t *@var{s1}, const uint16_t *@var{s2}, size_t @var{n})
+@deftypefunx int u32_cmp (const uint32_t *@var{s1}, const uint32_t *@var{s2}, size_t @var{n})
+Compares @var{s1} and @var{s2}, each of length @var{n}, lexicographically.
+Returns a negative value if @var{s1} compares smaller than @var{s2},
+a positive value if @var{s1} compares larger than @var{s2}, or 0 if
+they compare equal.
+
+This function is similar to @code{memcmp()}, except that it operates on
+Unicode strings.
+@end deftypefun
+
+The following function searches for a given Unicode character.
+
+@deftypefun {uint8_t *} u8_chr (const uint8_t *@var{s}, size_t @var{n}, ucs4_t @var{uc})
+@deftypefunx {uint16_t *} u16_chr (const uint16_t *@var{s}, size_t @var{n}, ucs4_t @var{uc})
+@deftypefunx {uint32_t *} u32_chr (const uint32_t *@var{s}, size_t @var{n}, ucs4_t @var{uc})
+Searches the string at @var{s} for @var{uc}.  Returns a pointer to the first
+occurrence of @var{uc} in @var{s}, or NULL if @var{uc} does not occur in
+@var{s}.
+
+This function is similar to @code{memchr()}, except that it operates on
+Unicode strings.
+@end deftypefun
+
+The following function counts the number of Unicode characters.
+
+@deftypefun size_t u8_mbsnlen (const uint8_t *@var{s}, size_t @var{n})
+@deftypefunx size_t u16_mbsnlen (const uint16_t *@var{s}, size_t @var{n})
+@deftypefunx size_t u32_mbsnlen (const uint32_t *@var{s}, size_t @var{n})
+Counts and returns the number of Unicode characters in the @var{n} units
+from @var{s}.
+
+This function is similar to the gnulib function @code{mbsnlen()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+@node Elementary string functions with memory allocation
+@section Elementary string functions with memory allocation
+
+The following function copies a Unicode string.
+
+@deftypefun {uint8_t *} u8_cpy_alloc (const uint8_t *@var{s}, size_t @var{n})
+@deftypefunx {uint16_t *} u16_cpy_alloc (const uint16_t *@var{s}, size_t @var{n})
+@deftypefunx {uint32_t *} u32_cpy_alloc (const uint32_t *@var{s}, size_t @var{n})
+Makes a freshly allocated copy of @var{s}, of length @var{n}.
+@end deftypefun
+
+@node Elementary string functions on NUL terminated strings
+@section Elementary string functions on NUL terminated strings
+
+The following functions inspect and return details about the first character
+in a Unicode string.
+
+@deftypefun int u8_strmblen (const uint8_t *@var{s})
+@deftypefunx int u16_strmblen (const uint16_t *@var{s})
+@deftypefunx int u32_strmblen (const uint32_t *@var{s})
+Returns the length (number of units) of the first character in @var{s}.
+Returns 0 if it is the NUL character.  Returns -1 upon failure.
+@end deftypefun
+
+@deftypefun int u8_strmbtouc (ucs4_t *@var{puc}, const uint8_t *@var{s})
+@deftypefunx int u16_strmbtouc (ucs4_t *@var{puc}, const uint16_t *@var{s})
+@deftypefunx int u32_strmbtouc (ucs4_t *@var{puc}, const uint32_t *@var{s})
+Returns the length (number of units) of the first character in @var{s},
+putting its @code{ucs4_t} representation in @code{*@var{puc}}.  Returns 0
+if it is the NUL character.  Returns -1 upon failure.
+@end deftypefun
+
+@deftypefun {const uint8_t *} u8_next (ucs4_t *@var{puc}, const uint8_t *@var{s})
+@deftypefunx {const uint16_t *} u16_next (ucs4_t *@var{puc}, const uint16_t *@var{s})
+@deftypefunx {const uint32_t *} u32_next (ucs4_t *@var{puc}, const uint32_t *@var{s})
+Forward iteration step.  Advances the pointer past the next character,
+or returns NULL if the end of the string has been reached.  Puts the
+character's @code{ucs4_t} representation in @code{*@var{puc}}.
+@end deftypefun
+
+The following function inspects and returns details about the previous
+character in a Unicode string.
+
+@deftypefun {const uint8_t *} u8_prev (ucs4_t *@var{puc}, const uint8_t *@var{s}, const uint8_t *@var{start})
+@deftypefunx {const uint16_t *} u16_prev (ucs4_t *@var{puc}, const uint16_t *@var{s}, const uint16_t *@var{start})
+@deftypefunx {const uint32_t *} u32_prev (ucs4_t *@var{puc}, const uint32_t *@var{s}, const uint32_t *@var{start})
+Backward iteration step.  Advances the pointer to point to the previous
+character, or returns NULL if the beginning of the string had been reached.
+Puts the character's @code{ucs4_t} representation in @code{*@var{puc}}.
+@end deftypefun
+
+The following functions determine the length of a Unicode string.
+
+@deftypefun size_t u8_strlen (const uint8_t *@var{s})
+@deftypefunx size_t u16_strlen (const uint16_t *@var{s})
+@deftypefunx size_t u32_strlen (const uint32_t *@var{s})
+Returns the number of units in @var{s}.
+
+This function is similar to @code{strlen()} and @code{wcslen()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+@deftypefun size_t u8_strnlen (const uint8_t *@var{s}, size_t @var{maxlen})
+@deftypefunx size_t u16_strnlen (const uint16_t *@var{s}, size_t @var{maxlen})
+@deftypefunx size_t u32_strnlen (const uint32_t *@var{s}, size_t @var{maxlen})
+Returns the number of units in @var{s}, but at most @var{maxlen}.
+
+This function is similar to @code{strnlen()} and @code{wcsnlen()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+The following functions copy portions of Unicode strings in memory.
+
+@deftypefun {uint8_t *} u8_strcpy (uint8_t *@var{dest}, const uint8_t *@var{src})
+@deftypefunx {uint16_t *} u16_strcpy (uint16_t *@var{dest}, const uint16_t *@var{src})
+@deftypefunx {uint32_t *} u32_strcpy (uint32_t *@var{dest}, const uint32_t *@var{src})
+Copies @var{src} to @var{dest}.
+
+This function is similar to @code{strcpy()} and @code{wcscpy()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+@deftypefun {uint8_t *} u8_stpcpy (uint8_t *@var{dest}, const uint8_t *@var{src})
+@deftypefunx {uint16_t *} u16_stpcpy (uint16_t *@var{dest}, const uint16_t *@var{src})
+@deftypefunx {uint32_t *} u32_stpcpy (uint32_t *@var{dest}, const uint32_t *@var{src})
+Copies @var{src} to @var{dest}, returning the address of the terminating NUL
+in @var{dest}.
+
+This function is similar to @code{stpcpy()}, except that it operates on
+Unicode strings.
+@end deftypefun
+
+@deftypefun {uint8_t *} u8_strncpy (uint8_t *@var{dest}, const uint8_t *@var{src}, size_t @var{n})
+@deftypefunx {uint16_t *} u16_strncpy (uint16_t *@var{dest}, const uint16_t *@var{src}, size_t @var{n})
+@deftypefunx {uint32_t *} u32_strncpy (uint32_t *@var{dest}, const uint32_t *@var{src}, size_t @var{n})
+Copies no more than @var{n} units of @var{src} to @var{dest}.
+
+This function is similar to @code{strncpy()} and @code{wcsncpy()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+@deftypefun {uint8_t *} u8_stpncpy (uint8_t *@var{dest}, const uint8_t *@var{src}, size_t @var{n})
+@deftypefunx {uint16_t *} u16_stpncpy (uint16_t *@var{dest}, const uint16_t *@var{src}, size_t @var{n})
+@deftypefunx {uint32_t *} u32_stpncpy (uint32_t *@var{dest}, const uint32_t *@var{src}, size_t @var{n})
+Copies no more than @var{n} units of @var{src} to @var{dest}, returning the
+address of the last unit written into @var{dest}.
+
+This function is similar to @code{stpncpy()}, except that it operates on
+Unicode strings.
+@end deftypefun
+
+@deftypefun {uint8_t *} u8_strcat (uint8_t *@var{dest}, const uint8_t *@var{src})
+@deftypefunx {uint16_t *} u16_strcat (uint16_t *@var{dest}, const uint16_t *@var{src})
+@deftypefunx {uint32_t *} u32_strcat (uint32_t *@var{dest}, const uint32_t *@var{src})
+Appends @var{src} onto @var{dest}.
+
+This function is similar to @code{strcat()} and @code{wcscat()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+@deftypefun {uint8_t *} u8_strncat (uint8_t *@var{dest}, const uint8_t *@var{src}, size_t @var{n})
+@deftypefunx {uint16_t *} u16_strncat (uint16_t *@var{dest}, const uint16_t *@var{src}, size_t @var{n})
+@deftypefunx {uint32_t *} u32_strncat (uint32_t *@var{dest}, const uint32_t *@var{src}, size_t @var{n})
+Appends no more than @var{n} units of @var{src} onto @var{dest}.
+
+This function is similar to @code{strncat()} and @code{wcsncat()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+The following functions compare two Unicode strings.
+
+@deftypefun int u8_strcmp (const uint8_t *@var{s1}, const uint8_t *@var{s2})
+@deftypefunx int u16_strcmp (const uint16_t *@var{s1}, const uint16_t *@var{s2})
+@deftypefunx int u32_strcmp (const uint32_t *@var{s1}, const uint32_t *@var{s2})
+Compares @var{s1} and @var{s2}, lexicographically.
+Returns a negative value if @var{s1} compares smaller than @var{s2},
+a positive value if @var{s1} compares larger than @var{s2}, or 0 if
+they compare equal.
+
+This function is similar to @code{strcmp()} and @code{wcscmp()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+@deftypefun int u8_strcoll (const uint8_t *@var{s1}, const uint8_t *@var{s2})
+@deftypefunx int u16_strcoll (const uint16_t *@var{s1}, const uint16_t *@var{s2})
+@deftypefunx int u32_strcoll (const uint32_t *@var{s1}, const uint32_t *@var{s2})
+Compares @var{s1} and @var{s2} using the collation rules of the current
+locale.
+Returns -1 if @var{s1} < @var{s2}, 0 if @var{s1} = @var{s2}, 1 if
+@var{s1} > @var{s2}.  Upon failure, sets @code{errno} and returns any value.
+
+This function is similar to @code{strcoll()} and @code{wcscoll()}, except that
+it operates on Unicode strings.
+
+Note that this function may consider different canonical normalizations
+of the same string as having a large distance.  It is therefore better to
+use the function @code{u8_normcoll} instead of this one; see @ref{uninorm.h}.
+@end deftypefun
+
+@deftypefun int u8_strncmp (const uint8_t *@var{s1}, const uint8_t *@var{s2}, size_t @var{n})
+@deftypefunx int u16_strncmp (const uint16_t *@var{s1}, const uint16_t *@var{s2}, size_t @var{n})
+@deftypefunx int u32_strncmp (const uint32_t *@var{s1}, const uint32_t *@var{s2}, size_t @var{n})
+Compares no more than @var{n} units of @var{s1} and @var{s2}.
+
+This function is similar to @code{strncmp()} and @code{wcsncmp()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+The following function allocates a duplicate of a Unicode string.
+
+@deftypefun {uint8_t *} u8_strdup (const uint8_t *@var{s})
+@deftypefunx {uint16_t *} u16_strdup (const uint16_t *@var{s})
+@deftypefunx {uint32_t *} u32_strdup (const uint32_t *@var{s})
+Duplicates @var{s}, returning an identical malloc'd string.
+
+This function is similar to @code{strdup()} and @code{wcsdup()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+The following functions search for a given Unicode character.
+
+@deftypefun {uint8_t *} u8_strchr (const uint8_t *@var{str}, ucs4_t @var{uc})
+@deftypefunx {uint16_t *} u16_strchr (const uint16_t *@var{str}, ucs4_t @var{uc})
+@deftypefunx {uint32_t *} u32_strchr (const uint32_t *@var{str}, ucs4_t @var{uc})
+Finds the first occurrence of @var{uc} in @var{str}.
+
+This function is similar to @code{strchr()} and @code{wcschr()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+@deftypefun {uint8_t *} u8_strrchr (const uint8_t *@var{str}, ucs4_t @var{uc})
+@deftypefunx {uint16_t *} u16_strrchr (const uint16_t *@var{str}, ucs4_t @var{uc})
+@deftypefunx {uint32_t *} u32_strrchr (const uint32_t *@var{str}, ucs4_t @var{uc})
+Finds the last occurrence of @var{uc} in @var{str}.
+
+This function is similar to @code{strrchr()} and @code{wcsrchr()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+The following functions seach for the first occurrence of some Unicode
+character in or outside a given set of Unicode characters.
+
+@deftypefun size_t u8_strcspn (const uint8_t *@var{str}, const uint8_t *@var{reject})
+@deftypefunx size_t u16_strcspn (const uint16_t *@var{str}, const uint16_t *@var{reject})
+@deftypefunx size_t u32_strcspn (const uint32_t *@var{str}, const uint32_t *@var{reject})
+Returns the length of the initial segment of @var{str} which consists entirely
+of Unicode characters not in @var{reject}.
+
+This function is similar to @code{strcspn()} and @code{wcscspn()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+@deftypefun size_t u8_strspn (const uint8_t *@var{str}, const uint8_t *@var{accept})
+@deftypefunx size_t u16_strspn (const uint16_t *@var{str}, const uint16_t *@var{accept})
+@deftypefunx size_t u32_strspn (const uint32_t *@var{str}, const uint32_t *@var{accept})
+Returns the length of the initial segment of @var{str} which consists entirely
+of Unicode characters in @var{accept}.
+
+This function is similar to @code{strspn()} and @code{wcsspn()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+@deftypefun {uint8_t *} u8_strpbrk (const uint8_t *@var{str}, const uint8_t *@var{accept})
+@deftypefunx {uint16_t *} u16_strpbrk (const uint16_t *@var{str}, const uint16_t *@var{accept})
+@deftypefunx {uint32_t *} u32_strpbrk (const uint32_t *@var{str}, const uint32_t *@var{accept})
+Finds the first occurrence in @var{str} of any character in @var{accept}.
+
+This function is similar to @code{strpbrk()} and @code{wcspbrk()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+The following functions search whether a given Unicode string is a substring
+of another Unicode string.
+
+@deftypefun {uint8_t *} u8_strstr (const uint8_t *@var{haystack}, const uint8_t *@var{needle})
+@deftypefunx {uint16_t *} u16_strstr (const uint16_t *@var{haystack}, const uint16_t *@var{needle})
+@deftypefunx {uint32_t *} u32_strstr (const uint32_t *@var{haystack}, const uint32_t *@var{needle})
+Finds the first occurrence of @var{needle} in @var{haystack}.
+
+This function is similar to @code{strstr()} and @code{wcsstr()}, except that
+it operates on Unicode strings.
+@end deftypefun
+
+@deftypefun bool u8_startswith (const uint8_t *@var{str}, const uint8_t *@var{prefix})
+@deftypefunx bool u16_startswith (const uint16_t *@var{str}, const uint16_t *@var{prefix})
+@deftypefunx bool u32_startswith (const uint32_t *@var{str}, const uint32_t *@var{prefix})
+Tests whether @var{str} starts with @var{prefix}.
+@end deftypefun
+
+@deftypefun bool u8_endswith (const uint8_t *@var{str}, const uint8_t *@var{suffix})
+@deftypefunx bool u16_endswith (const uint16_t *@var{str}, const uint16_t *@var{suffix})
+@deftypefunx bool u32_endswith (const uint32_t *@var{str}, const uint32_t *@var{suffix})
+Tests whether @var{str} ends with @var{suffix}.
+@end deftypefun
+
+The following function does one step in tokenizing a Unicode string.
+
+@deftypefun {uint8_t *} u8_strtok (uint8_t *@var{str}, const uint8_t *@var{delim}, uint8_t **@var{ptr})
+@deftypefunx {uint16_t *} u16_strtok (uint16_t *@var{str}, const uint16_t *@var{delim}, uint16_t **@var{ptr})
+@deftypefunx {uint32_t *} u32_strtok (uint32_t *@var{str}, const uint32_t *@var{delim}, uint32_t **@var{ptr})
+Divides @var{str} into tokens separated by characters in @var{delim}.
+
+This function is similar to @code{strtok_r()} and @code{wcstok()}, except that
+it operates on Unicode strings.  Its interface is actually more similar to
+@code{wcstok} than to @code{strtok}.
+@end deftypefun