doc/unicase.texi

   1 @node unicase.h
   2 @chapter Case mappings @code{<unicase.h>}
   3
   4 This include file defines functions for case mapping for Unicode strings and
   5 case insensitive comparison of Unicode strings and C strings.
   6
   7 These string functions fix the problems that were mentioned in
   8 @ref{char * strings}, namely, they handle the Croatian
   9 @sc{LETTER DZ WITH CARON}, the German @sc{LATIN SMALL LETTER SHARP S}, the
  10 Greek sigma and the Lithuanian i correctly.
  11
  12 @menu
  13 * Case mappings of characters::
  14 * Case mappings of strings::
  15 * Case mappings of substrings::
  16 * Case insensitive comparison::
  17 * Case detection::
  18 @end menu
  19
  20 @node Case mappings of characters
  21 @section Case mappings of characters
  22
  23 @cindex Unicode character, case mappings
  24 The following functions implement case mappings on Unicode characters ---
  25 for those cases only where the result of the mapping is a again a single
  26 Unicode character.
  27
  28 These mappings are locale and context independent.
  29
  30 @cartouche
  31 @strong{WARNING!} These functions are not sufficient for languages such as
  32 German, Greek and Lithuanian.  Better use the functions below that treat an
  33 entire string at once and are language aware.
  34 @end cartouche
  35
  36 @deftypefun ucs4_t uc_toupper (ucs4_t @var{uc})
  37 Returns the uppercase mapping of the Unicode character @var{uc}.
  38 @end deftypefun
  39
  40 @deftypefun ucs4_t uc_tolower (ucs4_t @var{uc})
  41 Returns the lowercase mapping of the Unicode character @var{uc}.
  42 @end deftypefun
  43
  44 @deftypefun ucs4_t uc_totitle (ucs4_t @var{uc})
  45 Returns the titlecase mapping of the Unicode character @var{uc}.
  46
  47 The titlecase mapping of a character is to be used when the character should
  48 look like upper case and the following characters are lower cased.
  49
  50 For most characters, this is the same as the uppercase mapping.  There are
  51 only few characters where the title case variant and the uuper case variant
  52 are different.  These characters occur in the Latin writing of the Croatian,
  53 Bosnian, and Serbian languages.
  54
  55 @c Normally we would use .33 space for each column, but this is too much in
  56 @c TeX mode, see
  57 @c <http://lists.gnu.org/archive/html/bug-texinfo/2009-05/msg00016.html>.
  58 @multitable @columnfractions .31 .31 .31
  59 @headitem Lower case @tab Title case @tab Upper case
  60 @item LATIN SMALL LETTER LJ
  61  @tab LATIN CAPITAL LETTER L WITH SMALL LETTER J
  62  @tab LATIN CAPITAL LETTER LJ
  63 @item LATIN SMALL LETTER NJ
  64  @tab LATIN CAPITAL LETTER N WITH SMALL LETTER J
  65  @tab LATIN CAPITAL LETTER NJ
  66 @item LATIN SMALL LETTER DZ
  67  @tab LATIN CAPITAL LETTER D WITH SMALL LETTER Z
  68  @tab LATIN CAPITAL LETTER DZ
  69 @item LATIN SMALL LETTER DZ WITH CARON
  70  @tab LATIN CAPITAL LETTER D WITH SMALL LETTER Z WITH CARON
  71  @tab LATIN CAPITAL LETTER DZ WITH CARON
  72 @end multitable
  73 @end deftypefun
  74
  75 @node Case mappings of strings
  76 @section Case mappings of strings
  77
  78 @cindex case mappings
  79 @cindex uppercasing
  80 @cindex lowercasing
  81 @cindex titlecasing
  82 Case mapping should always be performed on entire strings, not on individual
  83 characters.  The functions in this sections do so.
  84
  85 These functions allow to apply a normalization after the case mapping.  The
  86 reason is that if you want to treat @samp{@"{a}} and @samp{@"{A}} the same,
  87 you most often also want to treat the composed and decomposed forms of such
  88 a character, U+00C4 @sc{LATIN CAPITAL LETTER A WITH DIAERESIS} and
  89 U+0041 @sc{LATIN CAPITAL LETTER A} U+0308 @sc{COMBINING DIAERESIS} the same.
  90 The @var{nf} argument designates the normalization.
  91
  92 @cindex locale language
  93 These functions are locale dependent.  The @var{iso639_language} argument
  94 identifies the language (e.g@. @code{"tr"} for Turkish).  NULL means to use
  95 locale independent case mappings.
  96
  97 @deftypefun {const char *} uc_locale_language ()
  98 Returns the ISO 639 language code of the current locale.
  99 Returns @code{""} if it is unknown, or in the "C" locale.
 100 @end deftypefun
 101
 102 @deftypefun {uint8_t *} u8_toupper (const uint8_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint8_t *@var{resultbuf}, size_t *@var{lengthp})
 103 @deftypefunx {uint16_t *} u16_toupper (const uint16_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint16_t *@var{resultbuf}, size_t *@var{lengthp})
 104 @deftypefunx {uint32_t *} u32_toupper (const uint32_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint32_t *@var{resultbuf}, size_t *@var{lengthp})
 105 Returns the uppercase mapping of a string.
 106
 107 The @var{nf} argument identifies the normalization form to apply after the
 108 case-mapping.  It can also be NULL, for no normalization.
 109 @end deftypefun
 110
 111 @deftypefun {uint8_t *} u8_tolower (const uint8_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint8_t *@var{resultbuf}, size_t *@var{lengthp})
 112 @deftypefunx {uint16_t *} u16_tolower (const uint16_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint16_t *@var{resultbuf}, size_t *@var{lengthp})
 113 @deftypefunx {uint32_t *} u32_tolower (const uint32_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint32_t *@var{resultbuf}, size_t *@var{lengthp})
 114 Returns the lowercase mapping of a string.
 115
 116 The @var{nf} argument identifies the normalization form to apply after the
 117 case-mapping.  It can also be NULL, for no normalization.
 118 @end deftypefun
 119
 120 @deftypefun {uint8_t *} u8_totitle (const uint8_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint8_t *@var{resultbuf}, size_t *@var{lengthp})
 121 @deftypefunx {uint16_t *} u16_totitle (const uint16_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint16_t *@var{resultbuf}, size_t *@var{lengthp})
 122 @deftypefunx {uint32_t *} u32_totitle (const uint32_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint32_t *@var{resultbuf}, size_t *@var{lengthp})
 123 Returns the titlecase mapping of a string.
 124
 125 Mapping to title case means that, in each word, the first cased character
 126 is being mapped to title case and the remaining characters of the word
 127 are being mapped to lower case.
 128
 129 The @var{nf} argument identifies the normalization form to apply after the
 130 case-mapping.  It can also be NULL, for no normalization.
 131 @end deftypefun
 132
 133 @node Case mappings of substrings
 134 @section Case mappings of substrings
 135
 136 Case mapping of a substring cannot simply be performed by extracting the
 137 substring and then applying the case mapping function to it.  This does not
 138 work because case mapping requires some information about the surrounding
 139 characters.  The following functions allow to apply case mappings to
 140 substrings of a given string, while taking into account the characters that
 141 precede it (the ``prefix'') and the characters that follow it (the ``suffix'').
 142
 143 @deftp Type casing_prefix_context_t
 144 This data type denotes the case-mapping context that is given by a prefix
 145 string.  It is an immediate type that can be copied by simple assignment,
 146 without involving memory allocation.  It is not an array type.
 147 @end deftp
 148
 149 @deftypevr Constant casing_prefix_context_t unicase_empty_prefix_context
 150 This constant is the case-mapping context that corresponds to an empty prefix
 151 string.
 152 @end deftypevr
 153
 154 The following functions return @code{casing_prefix_context_t} objects:
 155
 156 @deftypefun casing_prefix_context_t u8_casing_prefix_context (const uint8_t *@var{s}, size_t @var{n})
 157 @deftypefunx casing_prefix_context_t u16_casing_prefix_context (const uint16_t *@var{s}, size_t @var{n})
 158 @deftypefunx casing_prefix_context_t u32_casing_prefix_context (const uint32_t *@var{s}, size_t @var{n})
 159 Returns the case-mapping context of a given prefix string.
 160 @end deftypefun
 161
 162 @deftypefun casing_prefix_context_t u8_casing_prefixes_context (const uint8_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{a_context})
 163 @deftypefunx casing_prefix_context_t u16_casing_prefixes_context (const uint16_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{a_context})
 164 @deftypefunx casing_prefix_context_t u32_casing_prefixes_context (const uint32_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{a_context})
 165 Returns the case-mapping context of the prefix concat(@var{a}, @var{s}),
 166 given the case-mapping context of the prefix @var{a}.
 167 @end deftypefun
 168
 169 @deftp Type casing_suffix_context_t
 170 This data type denotes the case-mapping context that is given by a suffix
 171 string.  It is an immediate type that can be copied by simple assignment,
 172 without involving memory allocation.  It is not an array type.
 173 @end deftp
 174
 175 @deftypevr Constant casing_suffix_context_t unicase_empty_suffix_context
 176 This constant is the case-mapping context that corresponds to an empty suffix
 177 string.
 178 @end deftypevr
 179
 180 The following functions return @code{casing_suffix_context_t} objects:
 181
 182 @deftypefun casing_suffix_context_t u8_casing_suffix_context (const uint8_t *@var{s}, size_t @var{n})
 183 @deftypefunx casing_suffix_context_t u16_casing_suffix_context (const uint16_t *@var{s}, size_t @var{n})
 184 @deftypefunx casing_suffix_context_t u32_casing_suffix_context (const uint32_t *@var{s}, size_t @var{n})
 185 Returns the case-mapping context of a given suffix string.
 186 @end deftypefun
 187
 188 @deftypefun casing_suffix_context_t u8_casing_suffixes_context (const uint8_t *@var{s}, size_t @var{n}, casing_suffix_context_t @var{a_context})
 189 @deftypefunx casing_suffix_context_t u16_casing_suffixes_context (const uint16_t *@var{s}, size_t @var{n}, casing_suffix_context_t @var{a_context})
 190 @deftypefunx casing_suffix_context_t u32_casing_suffixes_context (const uint32_t *@var{s}, size_t @var{n}, casing_suffix_context_t @var{a_context})
 191 Returns the case-mapping context of the suffix concat(@var{s}, @var{a}),
 192 given the case-mapping context of the suffix @var{a}.
 193 @end deftypefun
 194
 195 The following functions perform a case mapping, considering the
 196 prefix context and the suffix context.
 197
 198 @deftypefun {uint8_t *} u8_ct_toupper (const uint8_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{prefix_context}, casing_suffix_context_t @var{suffix_context}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint8_t *@var{resultbuf}, size_t *@var{lengthp})
 199 @deftypefunx {uint16_t *} u16_ct_toupper (const uint16_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{prefix_context}, casing_suffix_context_t @var{suffix_context}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint16_t *@var{resultbuf}, size_t *@var{lengthp})
 200 @deftypefunx {uint32_t *} u32_ct_toupper (const uint32_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{prefix_context}, casing_suffix_context_t @var{suffix_context}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint32_t *@var{resultbuf}, size_t *@var{lengthp})
 201 Returns the uppercase mapping of a string that is surrounded by a prefix
 202 and a suffix.
 203 @end deftypefun
 204
 205 @deftypefun {uint8_t *} u8_ct_tolower (const uint8_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{prefix_context}, casing_suffix_context_t @var{suffix_context}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint8_t *@var{resultbuf}, size_t *@var{lengthp})
 206 @deftypefunx {uint16_t *} u16_ct_tolower (const uint16_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{prefix_context}, casing_suffix_context_t @var{suffix_context}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint16_t *@var{resultbuf}, size_t *@var{lengthp})
 207 @deftypefunx {uint32_t *} u32_ct_tolower (const uint32_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{prefix_context}, casing_suffix_context_t @var{suffix_context}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint32_t *@var{resultbuf}, size_t *@var{lengthp})
 208 Returns the lowercase mapping of a string that is surrounded by a prefix
 209 and a suffix.
 210 @end deftypefun
 211
 212 @deftypefun {uint8_t *} u8_ct_totitle (const uint8_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{prefix_context}, casing_suffix_context_t @var{suffix_context}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint8_t *@var{resultbuf}, size_t *@var{lengthp})
 213 @deftypefunx {uint16_t *} u16_ct_totitle (const uint16_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{prefix_context}, casing_suffix_context_t @var{suffix_context}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint16_t *@var{resultbuf}, size_t *@var{lengthp})
 214 @deftypefunx {uint32_t *} u32_ct_totitle (const uint32_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{prefix_context}, casing_suffix_context_t @var{suffix_context}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint32_t *@var{resultbuf}, size_t *@var{lengthp})
 215 Returns the titlecase mapping of a string that is surrounded by a prefix
 216 and a suffix.
 217 @end deftypefun
 218
 219 For example, to uppercase the UTF-8 substring between @code{s + start_index}
 220 and @code{s + end_index} of a string that extends from @code{s} to
 221 @code{s + u8_strlen (s)}, you can use the statements
 222
 223 @smallexample
 224 size_t result_length;
 225 uint8_t result =
 226   u8_ct_toupper (s + start_index, end_index - start_index,
 227                  u8_casing_prefix_context (s, start_index),
 228                  u8_casing_suffix_context (s + end_index,
 229                                            u8_strlen (s) - end_index),
 230                  iso639_language, NULL, NULL, &result_length);
 231 @end smallexample
 232
 233 @node Case insensitive comparison
 234 @section Case insensitive comparison
 235
 236 @cindex comparing, ignoring case
 237 @cindex comparing, ignoring normalization and case
 238 The following functions implement comparison that ignores differences in case
 239 and normalization.
 240
 241 @deftypefun {uint8_t *} u8_casefold (const uint8_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint8_t *@var{resultbuf}, size_t *@var{lengthp})
 242 @deftypefunx {uint16_t *} u16_casefold (const uint16_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint16_t *@var{resultbuf}, size_t *@var{lengthp})
 243 @deftypefunx {uint32_t *} u32_casefold (const uint32_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint32_t *@var{resultbuf}, size_t *@var{lengthp})
 244 Returns the case folded string.
 245
 246 Comparing @code{u8_casefold (@var{s1})} and @code{u8_casefold (@var{s2})}
 247 with the @code{u8_cmp2} function is equivalent to comparing @var{s1} and
 248 @var{s2} with @code{u8_casecmp}.
 249
 250 The @var{nf} argument identifies the normalization form to apply after the
 251 case-mapping.  It can also be NULL, for no normalization.
 252 @end deftypefun
 253
 254 @deftypefun {uint8_t *} u8_ct_casefold (const uint8_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{prefix_context}, casing_suffix_context_t @var{suffix_context}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint8_t *@var{resultbuf}, size_t *@var{lengthp})
 255 @deftypefunx {uint16_t *} u16_ct_casefold (const uint16_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{prefix_context}, casing_suffix_context_t @var{suffix_context}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint16_t *@var{resultbuf}, size_t *@var{lengthp})
 256 @deftypefunx {uint32_t *} u32_ct_casefold (const uint32_t *@var{s}, size_t @var{n}, casing_prefix_context_t @var{prefix_context}, casing_suffix_context_t @var{suffix_context}, const char *@var{iso639_language}, uninorm_t @var{nf}, uint32_t *@var{resultbuf}, size_t *@var{lengthp})
 257 Returns the case folded string.  The case folding takes into account the
 258 case mapping contexts of the prefix and suffix strings.
 259 @end deftypefun
 260
 261 @deftypefun int u8_casecmp (const uint8_t *@var{s1}, size_t @var{n1}, const uint8_t *@var{s2}, size_t @var{n2}, const char *@var{iso639_language}, uninorm_t @var{nf}, int *@var{resultp})
 262 @deftypefunx int u16_casecmp (const uint16_t *@var{s1}, size_t @var{n1}, const uint16_t *@var{s2}, size_t @var{n2}, const char *@var{iso639_language}, uninorm_t @var{nf}, int *@var{resultp})
 263 @deftypefunx int u32_casecmp (const uint32_t *@var{s1}, size_t @var{n1}, const uint32_t *@var{s2}, size_t @var{n2}, const char *@var{iso639_language}, uninorm_t @var{nf}, int *@var{resultp})
 264 @deftypefunx int ulc_casecmp (const char *@var{s1}, size_t @var{n1}, const char *@var{s2}, size_t @var{n2}, const char *@var{iso639_language}, uninorm_t @var{nf}, int *@var{resultp})
 265 Compares @var{s1} and @var{s2}, ignoring differences in case and normalization.
 266
 267 The @var{nf} argument identifies the normalization form to apply after the
 268 case-mapping.  It can also be NULL, for no normalization.
 269
 270 If successful, sets @code{*@var{resultp}} to -1 if @var{s1} < @var{s2},
 271 0 if @var{s1} = @var{s2}, 1 if @var{s1} > @var{s2}, and returns 0.
 272 Upon failure, returns -1 with @code{errno} set.
 273 @end deftypefun
 274
 275 @cindex comparing, ignoring case, with collation rules
 276 @cindex comparing, with collation rules, ignoring case
 277 @cindex comparing, ignoring normalization and case, with collation rules
 278 @cindex comparing, with collation rules, ignoring normalization and case
 279 The following functions additionally take into account the sorting rules of the
 280 current locale.
 281
 282 @deftypefun {char *} u8_casexfrm (const uint8_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, char *@var{resultbuf}, size_t *@var{lengthp})
 283 @deftypefunx {char *} u16_casexfrm (const uint16_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, char *@var{resultbuf}, size_t *@var{lengthp})
 284 @deftypefunx {char *} u32_casexfrm (const uint32_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, char *@var{resultbuf}, size_t *@var{lengthp})
 285 @deftypefunx {char *} ulc_casexfrm (const char *@var{s}, size_t @var{n}, const char *@var{iso639_language}, uninorm_t @var{nf}, char *@var{resultbuf}, size_t *@var{lengthp})
 286 Converts the string @var{s} of length @var{n} to a NUL-terminated byte
 287 sequence, in such a way that comparing @code{u8_casexfrm (@var{s1})} and
 288 @code{u8_casexfrm (@var{s2})} with the gnulib function @code{memcmp2} is
 289 equivalent to comparing @var{s1} and @var{s2} with @code{u8_casecoll}.
 290
 291 @var{nf} must be either @code{UNINORM_NFC}, @code{UNINORM_NFKC}, or NULL for
 292 no normalization.
 293 @end deftypefun
 294
 295 @deftypefun int u8_casecoll (const uint8_t *@var{s1}, size_t @var{n1}, const uint8_t *@var{s2}, size_t @var{n2}, const char *@var{iso639_language}, uninorm_t @var{nf}, int *@var{resultp})
 296 @deftypefunx int u16_casecoll (const uint16_t *@var{s1}, size_t @var{n1}, const uint16_t *@var{s2}, size_t @var{n2}, const char *@var{iso639_language}, uninorm_t @var{nf}, int *@var{resultp})
 297 @deftypefunx int u32_casecoll (const uint32_t *@var{s1}, size_t @var{n1}, const uint32_t *@var{s2}, size_t @var{n2}, const char *@var{iso639_language}, uninorm_t @var{nf}, int *@var{resultp})
 298 @deftypefunx int ulc_casecoll (const char *@var{s1}, size_t @var{n1}, const char *@var{s2}, size_t @var{n2}, const char *@var{iso639_language}, uninorm_t @var{nf}, int *@var{resultp})
 299 Compares @var{s1} and @var{s2}, ignoring differences in case and normalization,
 300 using the collation rules of the current locale.
 301
 302 The @var{nf} argument identifies the normalization form to apply after the
 303 case-mapping.  It must be either @code{UNINORM_NFC} or @code{UNINORM_NFKC}.
 304 It can also be NULL, for no normalization.
 305
 306 If successful, sets @code{*@var{resultp}} to -1 if @var{s1} < @var{s2},
 307 0 if @var{s1} = @var{s2}, 1 if @var{s1} > @var{s2}, and returns 0.
 308 Upon failure, returns -1 with @code{errno} set.
 309 @end deftypefun
 310
 311 @node Case detection
 312 @section Case detection
 313
 314 @cindex case detection
 315 @cindex detecting case
 316 The following functions determine whether a Unicode string is entirely in
 317 upper case. or entirely in lower case, or entirely in title case, or already
 318 case-folded.
 319
 320 @deftypefun int u8_is_uppercase (const uint8_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 321 @deftypefunx int u16_is_uppercase (const uint16_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 322 @deftypefunx int u32_is_uppercase (const uint32_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 323 Sets @code{*@var{resultp}} to true if mapping NFD(@var{s}) to upper case is
 324 a no-op, or to false otherwise, and returns 0.  Upon failure, returns -1 with
 325 @code{errno} set.
 326 @end deftypefun
 327
 328 @deftypefun int u8_is_lowercase (const uint8_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 329 @deftypefunx int u16_is_lowercase (const uint16_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 330 @deftypefunx int u32_is_lowercase (const uint32_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 331 Sets @code{*@var{resultp}} to true if mapping NFD(@var{s}) to lower case is
 332 a no-op, or to false otherwise, and returns 0.  Upon failure, returns -1 with
 333 @code{errno} set.
 334 @end deftypefun
 335
 336 @deftypefun int u8_is_titlecase (const uint8_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 337 @deftypefunx int u16_is_titlecase (const uint16_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 338 @deftypefunx int u32_is_titlecase (const uint32_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 339 Sets @code{*@var{resultp}} to true if mapping NFD(@var{s}) to title case is
 340 a no-op, or to false otherwise, and returns 0.  Upon failure, returns -1 with
 341 @code{errno} set.
 342 @end deftypefun
 343
 344 @deftypefun int u8_is_casefolded (const uint8_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 345 @deftypefunx int u16_is_casefolded (const uint16_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 346 @deftypefunx int u32_is_casefolded (const uint32_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 347 Sets @code{*@var{resultp}} to true if applying case folding to NFD(@var{S}) is
 348 a no-op, or to false otherwise, and returns 0.  Upon failure, returns -1 with
 349 @code{errno} set.
 350 @end deftypefun
 351
 352 The following functions determine whether case mappings have any effect on a
 353 Unicode string.
 354
 355 @deftypefun int u8_is_cased (const uint8_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 356 @deftypefunx int u16_is_cased (const uint16_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 357 @deftypefunx int u32_is_cased (const uint32_t *@var{s}, size_t @var{n}, const char *@var{iso639_language}, bool *@var{resultp})
 358 Sets @code{*@var{resultp}} to true if case matters for @var{s}, that is, if
 359 mapping NFD(@var{s}) to either upper case or lower case or title case is not
 360 a no-op.  Set @code{*@var{resultp}} to false if NFD(@var{s}) maps to itself
 361 under the upper case mapping, under the lower case mapping, and under the title
 362 case mapping; in other words, when NFD(@var{s}) consists entirely of caseless
 363 characters. Upon failure, returns -1 with @code{errno} set.
 364 @end deftypefun