1 /* Unicode character case mappings.
2 Copyright (C) 2002, 2009-2023 Free Software Foundation, Inc.
3
4 This file is free software: you can redistribute it and/or modify
5 it under the terms of the GNU Lesser General Public License as
6 published by the Free Software Foundation; either version 2.1 of the
7 License, or (at your option) any later version.
8
9 This file is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU Lesser General Public License for more details.
13
14 You should have received a copy of the GNU Lesser General Public License
15 along with this program. If not, see <https://www.gnu.org/licenses/>. */
16
17 #ifndef _UNICASE_H
18 #define _UNICASE_H
19
20 #include "unitypes.h"
21
22 /* Get bool. */
23 #include <stdbool.h>
24
25 /* Get size_t. */
26 #include <stddef.h>
27
28 /* Get uninorm_t. */
29 #include "uninorm.h"
30
31 #if @HAVE_UNISTRING_WOE32DLL_H@
32 # include <unistring/woe32dll.h>
33 #else
34 # define LIBUNISTRING_DLL_VARIABLE
35 #endif
36
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40
41 /* ========================================================================= */
42
43 /* Character case mappings.
44 These mappings are locale and context independent.
45 WARNING! These functions are not sufficient for languages such as German.
46 Better use the functions below that treat an entire string at once and are
47 language aware. */
48
49 /* Return the uppercase mapping of a Unicode character. */
50 extern ucs4_t
51 uc_toupper (ucs4_t uc)
52 _UC_ATTRIBUTE_CONST;
53
54 /* Return the lowercase mapping of a Unicode character. */
55 extern ucs4_t
56 uc_tolower (ucs4_t uc)
57 _UC_ATTRIBUTE_CONST;
58
59 /* Return the titlecase mapping of a Unicode character. */
60 extern ucs4_t
61 uc_totitle (ucs4_t uc)
62 _UC_ATTRIBUTE_CONST;
63
64 /* ========================================================================= */
65
66 /* String case mappings. */
67
68 /* These functions are locale dependent. The iso639_language argument
69 identifies the language (e.g. "tr" for Turkish). NULL means to use
70 locale independent case mappings. */
71
72 /* Return the ISO 639 language code of the current locale.
73 Return "" if it is unknown, or in the "C" locale. */
74 extern const char *
75 uc_locale_language (void)
76 _UC_ATTRIBUTE_PURE;
77
78 /* Conventions:
79
80 All functions prefixed with u8_ operate on UTF-8 encoded strings.
81 Their unit is an uint8_t (1 byte).
82
83 All functions prefixed with u16_ operate on UTF-16 encoded strings.
84 Their unit is an uint16_t (a 2-byte word).
85
86 All functions prefixed with u32_ operate on UCS-4 encoded strings.
87 Their unit is an uint32_t (a 4-byte word).
88
89 All argument pairs (s, n) denote a Unicode string s[0..n-1] with exactly
90 n units.
91
92 Functions returning a string result take a (resultbuf, lengthp) argument
93 pair. If resultbuf is not NULL and the result fits into *lengthp units,
94 it is put in resultbuf, and resultbuf is returned. Otherwise, a freshly
95 allocated string is returned. In both cases, *lengthp is set to the
96 length (number of units) of the returned string. In case of error,
97 NULL is returned and errno is set. */
98
99 /* Return the uppercase mapping of a string.
100 The nf argument identifies the normalization form to apply after the
101 case-mapping. It can also be NULL, for no normalization. */
102 extern uint8_t *
103 u8_toupper (const uint8_t *s, size_t n, const char *iso639_language,
104 uninorm_t nf,
105 uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
106 extern uint16_t *
107 u16_toupper (const uint16_t *s, size_t n, const char *iso639_language,
108 uninorm_t nf,
109 uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
110 extern uint32_t *
111 u32_toupper (const uint32_t *s, size_t n, const char *iso639_language,
112 uninorm_t nf,
113 uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
114
115 /* Return the lowercase mapping of a string.
116 The nf argument identifies the normalization form to apply after the
117 case-mapping. It can also be NULL, for no normalization. */
118 extern uint8_t *
119 u8_tolower (const uint8_t *s, size_t n, const char *iso639_language,
120 uninorm_t nf,
121 uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
122 extern uint16_t *
123 u16_tolower (const uint16_t *s, size_t n, const char *iso639_language,
124 uninorm_t nf,
125 uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
126 extern uint32_t *
127 u32_tolower (const uint32_t *s, size_t n, const char *iso639_language,
128 uninorm_t nf,
129 uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
130
131 /* Return the titlecase mapping of a string.
132 The nf argument identifies the normalization form to apply after the
133 case-mapping. It can also be NULL, for no normalization. */
134 extern uint8_t *
135 u8_totitle (const uint8_t *s, size_t n, const char *iso639_language,
136 uninorm_t nf,
137 uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
138 extern uint16_t *
139 u16_totitle (const uint16_t *s, size_t n, const char *iso639_language,
140 uninorm_t nf,
141 uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
142 extern uint32_t *
143 u32_totitle (const uint32_t *s, size_t n, const char *iso639_language,
144 uninorm_t nf,
145 uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
146
147 /* The case-mapping context given by a prefix string. */
148 typedef struct casing_prefix_context
149 {
150 /* These fields are private, undocumented. */
151 uint32_t last_char_except_ignorable;
152 uint32_t last_char_normal_or_above;
153 }
154 casing_prefix_context_t;
155 /* The case-mapping context of the empty prefix string. */
156 extern @GNULIB_UNICASE_EMPTY_PREFIX_CONTEXT_DLL_VARIABLE@ const casing_prefix_context_t unicase_empty_prefix_context;
157 /* Return the case-mapping context of a given prefix string. */
158 extern casing_prefix_context_t
159 u8_casing_prefix_context (const uint8_t *s, size_t n);
160 extern casing_prefix_context_t
161 u16_casing_prefix_context (const uint16_t *s, size_t n);
162 extern casing_prefix_context_t
163 u32_casing_prefix_context (const uint32_t *s, size_t n);
164 /* Return the case-mapping context of the prefix concat(A, S), given the
165 case-mapping context of the prefix A. */
166 extern casing_prefix_context_t
167 u8_casing_prefixes_context (const uint8_t *s, size_t n,
168 casing_prefix_context_t a_context);
169 extern casing_prefix_context_t
170 u16_casing_prefixes_context (const uint16_t *s, size_t n,
171 casing_prefix_context_t a_context);
172 extern casing_prefix_context_t
173 u32_casing_prefixes_context (const uint32_t *s, size_t n,
174 casing_prefix_context_t a_context);
175
176 /* The case-mapping context given by a suffix string. */
177 typedef struct casing_suffix_context
178 {
179 /* These fields are private, undocumented. */
180 uint32_t first_char_except_ignorable;
181 uint32_t bits;
182 }
183 casing_suffix_context_t;
184 /* The case-mapping context of the empty suffix string. */
185 extern @GNULIB_UNICASE_EMPTY_SUFFIX_CONTEXT_DLL_VARIABLE@ const casing_suffix_context_t unicase_empty_suffix_context;
186 /* Return the case-mapping context of a given suffix string. */
187 extern casing_suffix_context_t
188 u8_casing_suffix_context (const uint8_t *s, size_t n);
189 extern casing_suffix_context_t
190 u16_casing_suffix_context (const uint16_t *s, size_t n);
191 extern casing_suffix_context_t
192 u32_casing_suffix_context (const uint32_t *s, size_t n);
193 /* Return the case-mapping context of the suffix concat(S, A), given the
194 case-mapping context of the suffix A. */
195 extern casing_suffix_context_t
196 u8_casing_suffixes_context (const uint8_t *s, size_t n,
197 casing_suffix_context_t a_context);
198 extern casing_suffix_context_t
199 u16_casing_suffixes_context (const uint16_t *s, size_t n,
200 casing_suffix_context_t a_context);
201 extern casing_suffix_context_t
202 u32_casing_suffixes_context (const uint32_t *s, size_t n,
203 casing_suffix_context_t a_context);
204
205 /* Return the uppercase mapping of a string that is surrounded by a prefix
206 and a suffix. */
207 extern uint8_t *
208 u8_ct_toupper (const uint8_t *s, size_t n,
209 casing_prefix_context_t prefix_context,
210 casing_suffix_context_t suffix_context,
211 const char *iso639_language,
212 uninorm_t nf,
213 uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
214 extern uint16_t *
215 u16_ct_toupper (const uint16_t *s, size_t n,
216 casing_prefix_context_t prefix_context,
217 casing_suffix_context_t suffix_context,
218 const char *iso639_language,
219 uninorm_t nf,
220 uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
221 extern uint32_t *
222 u32_ct_toupper (const uint32_t *s, size_t n,
223 casing_prefix_context_t prefix_context,
224 casing_suffix_context_t suffix_context,
225 const char *iso639_language,
226 uninorm_t nf,
227 uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
228
229 /* Return the lowercase mapping of a string that is surrounded by a prefix
230 and a suffix. */
231 extern uint8_t *
232 u8_ct_tolower (const uint8_t *s, size_t n,
233 casing_prefix_context_t prefix_context,
234 casing_suffix_context_t suffix_context,
235 const char *iso639_language,
236 uninorm_t nf,
237 uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
238 extern uint16_t *
239 u16_ct_tolower (const uint16_t *s, size_t n,
240 casing_prefix_context_t prefix_context,
241 casing_suffix_context_t suffix_context,
242 const char *iso639_language,
243 uninorm_t nf,
244 uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
245 extern uint32_t *
246 u32_ct_tolower (const uint32_t *s, size_t n,
247 casing_prefix_context_t prefix_context,
248 casing_suffix_context_t suffix_context,
249 const char *iso639_language,
250 uninorm_t nf,
251 uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
252
253 /* Return the titlecase mapping of a string that is surrounded by a prefix
254 and a suffix. */
255 extern uint8_t *
256 u8_ct_totitle (const uint8_t *s, size_t n,
257 casing_prefix_context_t prefix_context,
258 casing_suffix_context_t suffix_context,
259 const char *iso639_language,
260 uninorm_t nf,
261 uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
262 extern uint16_t *
263 u16_ct_totitle (const uint16_t *s, size_t n,
264 casing_prefix_context_t prefix_context,
265 casing_suffix_context_t suffix_context,
266 const char *iso639_language,
267 uninorm_t nf,
268 uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
269 extern uint32_t *
270 u32_ct_totitle (const uint32_t *s, size_t n,
271 casing_prefix_context_t prefix_context,
272 casing_suffix_context_t suffix_context,
273 const char *iso639_language,
274 uninorm_t nf,
275 uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
276
277 /* Return the case folded string.
278 Comparing uN_casefold (S1) and uN_casefold (S2) with uN_cmp2() is equivalent
279 to comparing S1 and S2 with uN_casecmp().
280 The nf argument identifies the normalization form to apply after the
281 case-mapping. It can also be NULL, for no normalization. */
282 extern uint8_t *
283 u8_casefold (const uint8_t *s, size_t n, const char *iso639_language,
284 uninorm_t nf,
285 uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
286 extern uint16_t *
287 u16_casefold (const uint16_t *s, size_t n, const char *iso639_language,
288 uninorm_t nf,
289 uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
290 extern uint32_t *
291 u32_casefold (const uint32_t *s, size_t n, const char *iso639_language,
292 uninorm_t nf,
293 uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
294 /* Likewise, for a string that is surrounded by a prefix and a suffix. */
295 extern uint8_t *
296 u8_ct_casefold (const uint8_t *s, size_t n,
297 casing_prefix_context_t prefix_context,
298 casing_suffix_context_t suffix_context,
299 const char *iso639_language,
300 uninorm_t nf,
301 uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
302 extern uint16_t *
303 u16_ct_casefold (const uint16_t *s, size_t n,
304 casing_prefix_context_t prefix_context,
305 casing_suffix_context_t suffix_context,
306 const char *iso639_language,
307 uninorm_t nf,
308 uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
309 extern uint32_t *
310 u32_ct_casefold (const uint32_t *s, size_t n,
311 casing_prefix_context_t prefix_context,
312 casing_suffix_context_t suffix_context,
313 const char *iso639_language,
314 uninorm_t nf,
315 uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
316
317 /* Compare S1 and S2, ignoring differences in case and normalization.
318 The nf argument identifies the normalization form to apply after the
319 case-mapping. It can also be NULL, for no normalization.
320 If successful, set *RESULTP to -1 if S1 < S2, 0 if S1 = S2, 1 if S1 > S2, and
321 return 0. Upon failure, return -1 with errno set. */
322 extern int
323 u8_casecmp (const uint8_t *s1, size_t n1,
324 const uint8_t *s2, size_t n2,
325 const char *iso639_language, uninorm_t nf, int *resultp);
326 extern int
327 u16_casecmp (const uint16_t *s1, size_t n1,
328 const uint16_t *s2, size_t n2,
329 const char *iso639_language, uninorm_t nf, int *resultp);
330 extern int
331 u32_casecmp (const uint32_t *s1, size_t n1,
332 const uint32_t *s2, size_t n2,
333 const char *iso639_language, uninorm_t nf, int *resultp);
334 extern int
335 ulc_casecmp (const char *s1, size_t n1,
336 const char *s2, size_t n2,
337 const char *iso639_language, uninorm_t nf, int *resultp);
338
339 /* Convert the string S of length N to a NUL-terminated byte sequence, in such
340 a way that comparing uN_casexfrm (S1) and uN_casexfrm (S2) with the gnulib
341 function memcmp2() is equivalent to comparing S1 and S2 with uN_casecoll().
342 NF must be either UNINORM_NFC, UNINORM_NFKC, or NULL for no normalization. */
343 extern char *
344 u8_casexfrm (const uint8_t *s, size_t n, const char *iso639_language,
345 uninorm_t nf,
346 char *_UC_RESTRICT resultbuf, size_t *lengthp);
347 extern char *
348 u16_casexfrm (const uint16_t *s, size_t n, const char *iso639_language,
349 uninorm_t nf,
350 char *_UC_RESTRICT resultbuf, size_t *lengthp);
351 extern char *
352 u32_casexfrm (const uint32_t *s, size_t n, const char *iso639_language,
353 uninorm_t nf,
354 char *_UC_RESTRICT resultbuf, size_t *lengthp);
355 extern char *
356 ulc_casexfrm (const char *s, size_t n, const char *iso639_language,
357 uninorm_t nf,
358 char *_UC_RESTRICT resultbuf, size_t *lengthp);
359
360 /* Compare S1 and S2, ignoring differences in case and normalization, using the
361 collation rules of the current locale.
362 The nf argument identifies the normalization form to apply after the
363 case-mapping. It must be either UNINORM_NFC or UNINORM_NFKC. It can also
364 be NULL, for no normalization.
365 If successful, set *RESULTP to -1 if S1 < S2, 0 if S1 = S2, 1 if S1 > S2, and
366 return 0. Upon failure, return -1 with errno set. */
367 extern int
368 u8_casecoll (const uint8_t *s1, size_t n1,
369 const uint8_t *s2, size_t n2,
370 const char *iso639_language, uninorm_t nf, int *resultp);
371 extern int
372 u16_casecoll (const uint16_t *s1, size_t n1,
373 const uint16_t *s2, size_t n2,
374 const char *iso639_language, uninorm_t nf, int *resultp);
375 extern int
376 u32_casecoll (const uint32_t *s1, size_t n1,
377 const uint32_t *s2, size_t n2,
378 const char *iso639_language, uninorm_t nf, int *resultp);
379 extern int
380 ulc_casecoll (const char *s1, size_t n1,
381 const char *s2, size_t n2,
382 const char *iso639_language, uninorm_t nf, int *resultp);
383
384
385 /* Set *RESULTP to true if mapping NFD(S) to upper case is a no-op, or to false
386 otherwise, and return 0. Upon failure, return -1 with errno set. */
387 extern int
388 u8_is_uppercase (const uint8_t *s, size_t n,
389 const char *iso639_language,
390 bool *resultp);
391 extern int
392 u16_is_uppercase (const uint16_t *s, size_t n,
393 const char *iso639_language,
394 bool *resultp);
395 extern int
396 u32_is_uppercase (const uint32_t *s, size_t n,
397 const char *iso639_language,
398 bool *resultp);
399
400 /* Set *RESULTP to true if mapping NFD(S) to lower case is a no-op, or to false
401 otherwise, and return 0. Upon failure, return -1 with errno set. */
402 extern int
403 u8_is_lowercase (const uint8_t *s, size_t n,
404 const char *iso639_language,
405 bool *resultp);
406 extern int
407 u16_is_lowercase (const uint16_t *s, size_t n,
408 const char *iso639_language,
409 bool *resultp);
410 extern int
411 u32_is_lowercase (const uint32_t *s, size_t n,
412 const char *iso639_language,
413 bool *resultp);
414
415 /* Set *RESULTP to true if mapping NFD(S) to title case is a no-op, or to false
416 otherwise, and return 0. Upon failure, return -1 with errno set. */
417 extern int
418 u8_is_titlecase (const uint8_t *s, size_t n,
419 const char *iso639_language,
420 bool *resultp);
421 extern int
422 u16_is_titlecase (const uint16_t *s, size_t n,
423 const char *iso639_language,
424 bool *resultp);
425 extern int
426 u32_is_titlecase (const uint32_t *s, size_t n,
427 const char *iso639_language,
428 bool *resultp);
429
430 /* Set *RESULTP to true if applying case folding to NFD(S) is a no-op, or to
431 false otherwise, and return 0. Upon failure, return -1 with errno set. */
432 extern int
433 u8_is_casefolded (const uint8_t *s, size_t n,
434 const char *iso639_language,
435 bool *resultp);
436 extern int
437 u16_is_casefolded (const uint16_t *s, size_t n,
438 const char *iso639_language,
439 bool *resultp);
440 extern int
441 u32_is_casefolded (const uint32_t *s, size_t n,
442 const char *iso639_language,
443 bool *resultp);
444
445 /* Set *RESULTP to true if case matters for S, that is, if mapping NFD(S) to
446 either upper case or lower case or title case is not a no-op.
447 Set *RESULTP to false if NFD(S) maps to itself under the upper case mapping,
448 under the lower case mapping, and under the title case mapping; in other
449 words, when NFD(S) consists entirely of caseless characters.
450 Upon failure, return -1 with errno set. */
451 extern int
452 u8_is_cased (const uint8_t *s, size_t n,
453 const char *iso639_language,
454 bool *resultp);
455 extern int
456 u16_is_cased (const uint16_t *s, size_t n,
457 const char *iso639_language,
458 bool *resultp);
459 extern int
460 u32_is_cased (const uint32_t *s, size_t n,
461 const char *iso639_language,
462 bool *resultp);
463
464
465 /* ========================================================================= */
466
467 #ifdef __cplusplus
468 }
469 #endif
470
471 #endif /* _UNICASE_H */