source/include/unicase.h

0001 /* DO NOT EDIT! GENERATED AUTOMATICALLY! */
0002 /* Unicode character case mappings.
0003    Copyright (C) 2002, 2009-2022 Free Software Foundation, Inc.
0004
0005    This file is free software.
0006    It is dual-licensed under "the GNU LGPLv3+ or the GNU GPLv2+".
0007    You can redistribute it and/or modify it under either
0008      - the terms of the GNU Lesser General Public License as published
0009        by the Free Software Foundation, either version 3, or (at your
0010        option) any later version, or
0011      - the terms of the GNU General Public License as published by the
0012        Free Software Foundation; either version 2, or (at your option)
0013        any later version, or
0014      - the same dual license "the GNU LGPLv3+ or the GNU GPLv2+".
0015
0016    This file is distributed in the hope that it will be useful,
0017    but WITHOUT ANY WARRANTY; without even the implied warranty of
0018    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0019    Lesser General Public License and the GNU General Public License
0020    for more details.
0021
0022    You should have received a copy of the GNU Lesser General Public
0023    License and of the GNU General Public License along with this
0024    program.  If not, see <https://www.gnu.org/licenses/>.  */
0025
0026 #ifndef _UNICASE_H
0027 #define _UNICASE_H
0028
0029 #include "unitypes.h"
0030
0031 /* Get bool.  */
0032 #include <unistring/stdbool.h>
0033
0034 /* Get size_t.  */
0035 #include <stddef.h>
0036
0037 /* Get uninorm_t.  */
0038 #include "uninorm.h"
0039
0040 #ifdef __cplusplus
0041 extern "C" {
0042 #endif
0043
0044 /* ========================================================================= */
0045
0046 /* Character case mappings.
0047    These mappings are locale and context independent.
0048    WARNING! These functions are not sufficient for languages such as German.
0049    Better use the functions below that treat an entire string at once and are
0050    language aware.  */
0051
0052 /* Return the uppercase mapping of a Unicode character.  */
0053 extern ucs4_t
0054        uc_toupper (ucs4_t uc)
0055        _UC_ATTRIBUTE_CONST;
0056
0057 /* Return the lowercase mapping of a Unicode character.  */
0058 extern ucs4_t
0059        uc_tolower (ucs4_t uc)
0060        _UC_ATTRIBUTE_CONST;
0061
0062 /* Return the titlecase mapping of a Unicode character.  */
0063 extern ucs4_t
0064        uc_totitle (ucs4_t uc)
0065        _UC_ATTRIBUTE_CONST;
0066
0067 /* ========================================================================= */
0068
0069 /* String case mappings.  */
0070
0071 /* These functions are locale dependent.  The iso639_language argument
0072    identifies the language (e.g. "tr" for Turkish).  NULL means to use
0073    locale independent case mappings.  */
0074
0075 /* Return the ISO 639 language code of the current locale.
0076    Return "" if it is unknown, or in the "C" locale.  */
0077 extern const char *
0078        uc_locale_language (void)
0079        _UC_ATTRIBUTE_PURE;
0080
0081 /* Conventions:
0082
0083    All functions prefixed with u8_ operate on UTF-8 encoded strings.
0084    Their unit is an uint8_t (1 byte).
0085
0086    All functions prefixed with u16_ operate on UTF-16 encoded strings.
0087    Their unit is an uint16_t (a 2-byte word).
0088
0089    All functions prefixed with u32_ operate on UCS-4 encoded strings.
0090    Their unit is an uint32_t (a 4-byte word).
0091
0092    All argument pairs (s, n) denote a Unicode string s[0..n-1] with exactly
0093    n units.
0094
0095    Functions returning a string result take a (resultbuf, lengthp) argument
0096    pair.  If resultbuf is not NULL and the result fits into *lengthp units,
0097    it is put in resultbuf, and resultbuf is returned.  Otherwise, a freshly
0098    allocated string is returned.  In both cases, *lengthp is set to the
0099    length (number of units) of the returned string.  In case of error,
0100    NULL is returned and errno is set.  */
0101
0102 /* Return the uppercase mapping of a string.
0103    The nf argument identifies the normalization form to apply after the
0104    case-mapping.  It can also be NULL, for no normalization.  */
0105 extern uint8_t *
0106        u8_toupper (const uint8_t *s, size_t n, const char *iso639_language,
0107                    uninorm_t nf,
0108                    uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0109 extern uint16_t *
0110        u16_toupper (const uint16_t *s, size_t n, const char *iso639_language,
0111                     uninorm_t nf,
0112                     uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0113 extern uint32_t *
0114        u32_toupper (const uint32_t *s, size_t n, const char *iso639_language,
0115                     uninorm_t nf,
0116                     uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0117
0118 /* Return the lowercase mapping of a string.
0119    The nf argument identifies the normalization form to apply after the
0120    case-mapping.  It can also be NULL, for no normalization.  */
0121 extern uint8_t *
0122        u8_tolower (const uint8_t *s, size_t n, const char *iso639_language,
0123                    uninorm_t nf,
0124                    uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0125 extern uint16_t *
0126        u16_tolower (const uint16_t *s, size_t n, const char *iso639_language,
0127                     uninorm_t nf,
0128                     uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0129 extern uint32_t *
0130        u32_tolower (const uint32_t *s, size_t n, const char *iso639_language,
0131                     uninorm_t nf,
0132                     uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0133
0134 /* Return the titlecase mapping of a string.
0135    The nf argument identifies the normalization form to apply after the
0136    case-mapping.  It can also be NULL, for no normalization.  */
0137 extern uint8_t *
0138        u8_totitle (const uint8_t *s, size_t n, const char *iso639_language,
0139                    uninorm_t nf,
0140                    uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0141 extern uint16_t *
0142        u16_totitle (const uint16_t *s, size_t n, const char *iso639_language,
0143                     uninorm_t nf,
0144                     uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0145 extern uint32_t *
0146        u32_totitle (const uint32_t *s, size_t n, const char *iso639_language,
0147                     uninorm_t nf,
0148                     uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0149
0150 /* The case-mapping context given by a prefix string.  */
0151 typedef struct casing_prefix_context
0152         {
0153           /* These fields are private, undocumented.  */
0154           uint32_t last_char_except_ignorable;
0155           uint32_t last_char_normal_or_above;
0156         }
0157         casing_prefix_context_t;
0158 /* The case-mapping context of the empty prefix string.  */
0159 extern LIBUNISTRING_DLL_VARIABLE const casing_prefix_context_t unicase_empty_prefix_context;
0160 /* Return the case-mapping context of a given prefix string.  */
0161 extern casing_prefix_context_t
0162        u8_casing_prefix_context (const uint8_t *s, size_t n);
0163 extern casing_prefix_context_t
0164        u16_casing_prefix_context (const uint16_t *s, size_t n);
0165 extern casing_prefix_context_t
0166        u32_casing_prefix_context (const uint32_t *s, size_t n);
0167 /* Return the case-mapping context of the prefix concat(A, S), given the
0168    case-mapping context of the prefix A.  */
0169 extern casing_prefix_context_t
0170        u8_casing_prefixes_context (const uint8_t *s, size_t n,
0171                                    casing_prefix_context_t a_context);
0172 extern casing_prefix_context_t
0173        u16_casing_prefixes_context (const uint16_t *s, size_t n,
0174                                     casing_prefix_context_t a_context);
0175 extern casing_prefix_context_t
0176        u32_casing_prefixes_context (const uint32_t *s, size_t n,
0177                                     casing_prefix_context_t a_context);
0178
0179 /* The case-mapping context given by a suffix string.  */
0180 typedef struct casing_suffix_context
0181         {
0182           /* These fields are private, undocumented.  */
0183           uint32_t first_char_except_ignorable;
0184           uint32_t bits;
0185         }
0186         casing_suffix_context_t;
0187 /* The case-mapping context of the empty suffix string.  */
0188 extern LIBUNISTRING_DLL_VARIABLE const casing_suffix_context_t unicase_empty_suffix_context;
0189 /* Return the case-mapping context of a given suffix string.  */
0190 extern casing_suffix_context_t
0191        u8_casing_suffix_context (const uint8_t *s, size_t n);
0192 extern casing_suffix_context_t
0193        u16_casing_suffix_context (const uint16_t *s, size_t n);
0194 extern casing_suffix_context_t
0195        u32_casing_suffix_context (const uint32_t *s, size_t n);
0196 /* Return the case-mapping context of the suffix concat(S, A), given the
0197    case-mapping context of the suffix A.  */
0198 extern casing_suffix_context_t
0199        u8_casing_suffixes_context (const uint8_t *s, size_t n,
0200                                    casing_suffix_context_t a_context);
0201 extern casing_suffix_context_t
0202        u16_casing_suffixes_context (const uint16_t *s, size_t n,
0203                                     casing_suffix_context_t a_context);
0204 extern casing_suffix_context_t
0205        u32_casing_suffixes_context (const uint32_t *s, size_t n,
0206                                     casing_suffix_context_t a_context);
0207
0208 /* Return the uppercase mapping of a string that is surrounded by a prefix
0209    and a suffix.  */
0210 extern uint8_t *
0211        u8_ct_toupper (const uint8_t *s, size_t n,
0212                       casing_prefix_context_t prefix_context,
0213                       casing_suffix_context_t suffix_context,
0214                       const char *iso639_language,
0215                       uninorm_t nf,
0216                       uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0217 extern uint16_t *
0218        u16_ct_toupper (const uint16_t *s, size_t n,
0219                       casing_prefix_context_t prefix_context,
0220                       casing_suffix_context_t suffix_context,
0221                       const char *iso639_language,
0222                       uninorm_t nf,
0223                       uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0224 extern uint32_t *
0225        u32_ct_toupper (const uint32_t *s, size_t n,
0226                       casing_prefix_context_t prefix_context,
0227                       casing_suffix_context_t suffix_context,
0228                       const char *iso639_language,
0229                       uninorm_t nf,
0230                       uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0231
0232 /* Return the lowercase mapping of a string that is surrounded by a prefix
0233    and a suffix.  */
0234 extern uint8_t *
0235        u8_ct_tolower (const uint8_t *s, size_t n,
0236                       casing_prefix_context_t prefix_context,
0237                       casing_suffix_context_t suffix_context,
0238                       const char *iso639_language,
0239                       uninorm_t nf,
0240                       uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0241 extern uint16_t *
0242        u16_ct_tolower (const uint16_t *s, size_t n,
0243                       casing_prefix_context_t prefix_context,
0244                       casing_suffix_context_t suffix_context,
0245                       const char *iso639_language,
0246                       uninorm_t nf,
0247                       uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0248 extern uint32_t *
0249        u32_ct_tolower (const uint32_t *s, size_t n,
0250                       casing_prefix_context_t prefix_context,
0251                       casing_suffix_context_t suffix_context,
0252                       const char *iso639_language,
0253                       uninorm_t nf,
0254                       uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0255
0256 /* Return the titlecase mapping of a string that is surrounded by a prefix
0257    and a suffix.  */
0258 extern uint8_t *
0259        u8_ct_totitle (const uint8_t *s, size_t n,
0260                       casing_prefix_context_t prefix_context,
0261                       casing_suffix_context_t suffix_context,
0262                       const char *iso639_language,
0263                       uninorm_t nf,
0264                       uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0265 extern uint16_t *
0266        u16_ct_totitle (const uint16_t *s, size_t n,
0267                       casing_prefix_context_t prefix_context,
0268                       casing_suffix_context_t suffix_context,
0269                       const char *iso639_language,
0270                       uninorm_t nf,
0271                       uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0272 extern uint32_t *
0273        u32_ct_totitle (const uint32_t *s, size_t n,
0274                       casing_prefix_context_t prefix_context,
0275                       casing_suffix_context_t suffix_context,
0276                       const char *iso639_language,
0277                       uninorm_t nf,
0278                       uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0279
0280 /* Return the case folded string.
0281    Comparing uN_casefold (S1) and uN_casefold (S2) with uN_cmp2() is equivalent
0282    to comparing S1 and S2 with uN_casecmp().
0283    The nf argument identifies the normalization form to apply after the
0284    case-mapping.  It can also be NULL, for no normalization.  */
0285 extern uint8_t *
0286        u8_casefold (const uint8_t *s, size_t n, const char *iso639_language,
0287                     uninorm_t nf,
0288                     uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0289 extern uint16_t *
0290        u16_casefold (const uint16_t *s, size_t n, const char *iso639_language,
0291                      uninorm_t nf,
0292                      uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0293 extern uint32_t *
0294        u32_casefold (const uint32_t *s, size_t n, const char *iso639_language,
0295                      uninorm_t nf,
0296                      uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0297 /* Likewise, for a string that is surrounded by a prefix and a suffix.  */
0298 extern uint8_t *
0299        u8_ct_casefold (const uint8_t *s, size_t n,
0300                        casing_prefix_context_t prefix_context,
0301                        casing_suffix_context_t suffix_context,
0302                        const char *iso639_language,
0303                        uninorm_t nf,
0304                        uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0305 extern uint16_t *
0306        u16_ct_casefold (const uint16_t *s, size_t n,
0307                         casing_prefix_context_t prefix_context,
0308                         casing_suffix_context_t suffix_context,
0309                         const char *iso639_language,
0310                         uninorm_t nf,
0311                         uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0312 extern uint32_t *
0313        u32_ct_casefold (const uint32_t *s, size_t n,
0314                         casing_prefix_context_t prefix_context,
0315                         casing_suffix_context_t suffix_context,
0316                         const char *iso639_language,
0317                         uninorm_t nf,
0318                         uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp);
0319
0320 /* Compare S1 and S2, ignoring differences in case and normalization.
0321    The nf argument identifies the normalization form to apply after the
0322    case-mapping.  It can also be NULL, for no normalization.
0323    If successful, set *RESULTP to -1 if S1 < S2, 0 if S1 = S2, 1 if S1 > S2, and
0324    return 0.  Upon failure, return -1 with errno set.  */
0325 extern int
0326        u8_casecmp (const uint8_t *s1, size_t n1,
0327                    const uint8_t *s2, size_t n2,
0328                    const char *iso639_language, uninorm_t nf, int *resultp);
0329 extern int
0330        u16_casecmp (const uint16_t *s1, size_t n1,
0331                     const uint16_t *s2, size_t n2,
0332                     const char *iso639_language, uninorm_t nf, int *resultp);
0333 extern int
0334        u32_casecmp (const uint32_t *s1, size_t n1,
0335                     const uint32_t *s2, size_t n2,
0336                     const char *iso639_language, uninorm_t nf, int *resultp);
0337 extern int
0338        ulc_casecmp (const char *s1, size_t n1,
0339                     const char *s2, size_t n2,
0340                     const char *iso639_language, uninorm_t nf, int *resultp);
0341
0342 /* Convert the string S of length N to a NUL-terminated byte sequence, in such
0343    a way that comparing uN_casexfrm (S1) and uN_casexfrm (S2) with the gnulib
0344    function memcmp2() is equivalent to comparing S1 and S2 with uN_casecoll().
0345    NF must be either UNINORM_NFC, UNINORM_NFKC, or NULL for no normalization.  */
0346 extern char *
0347        u8_casexfrm (const uint8_t *s, size_t n, const char *iso639_language,
0348                     uninorm_t nf,
0349                     char *_UC_RESTRICT resultbuf, size_t *lengthp);
0350 extern char *
0351        u16_casexfrm (const uint16_t *s, size_t n, const char *iso639_language,
0352                      uninorm_t nf,
0353                      char *_UC_RESTRICT resultbuf, size_t *lengthp);
0354 extern char *
0355        u32_casexfrm (const uint32_t *s, size_t n, const char *iso639_language,
0356                      uninorm_t nf,
0357                      char *_UC_RESTRICT resultbuf, size_t *lengthp);
0358 extern char *
0359        ulc_casexfrm (const char *s, size_t n, const char *iso639_language,
0360                      uninorm_t nf,
0361                      char *_UC_RESTRICT resultbuf, size_t *lengthp);
0362
0363 /* Compare S1 and S2, ignoring differences in case and normalization, using the
0364    collation rules of the current locale.
0365    The nf argument identifies the normalization form to apply after the
0366    case-mapping.  It must be either UNINORM_NFC or UNINORM_NFKC.  It can also
0367    be NULL, for no normalization.
0368    If successful, set *RESULTP to -1 if S1 < S2, 0 if S1 = S2, 1 if S1 > S2, and
0369    return 0.  Upon failure, return -1 with errno set.  */
0370 extern int
0371        u8_casecoll (const uint8_t *s1, size_t n1,
0372                     const uint8_t *s2, size_t n2,
0373                     const char *iso639_language, uninorm_t nf, int *resultp);
0374 extern int
0375        u16_casecoll (const uint16_t *s1, size_t n1,
0376                      const uint16_t *s2, size_t n2,
0377                      const char *iso639_language, uninorm_t nf, int *resultp);
0378 extern int
0379        u32_casecoll (const uint32_t *s1, size_t n1,
0380                      const uint32_t *s2, size_t n2,
0381                      const char *iso639_language, uninorm_t nf, int *resultp);
0382 extern int
0383        ulc_casecoll (const char *s1, size_t n1,
0384                      const char *s2, size_t n2,
0385                      const char *iso639_language, uninorm_t nf, int *resultp);
0386
0387
0388 /* Set *RESULTP to true if mapping NFD(S) to upper case is a no-op, or to false
0389    otherwise, and return 0.  Upon failure, return -1 with errno set.  */
0390 extern int
0391        u8_is_uppercase (const uint8_t *s, size_t n,
0392                         const char *iso639_language,
0393                         bool *resultp);
0394 extern int
0395        u16_is_uppercase (const uint16_t *s, size_t n,
0396                          const char *iso639_language,
0397                          bool *resultp);
0398 extern int
0399        u32_is_uppercase (const uint32_t *s, size_t n,
0400                          const char *iso639_language,
0401                          bool *resultp);
0402
0403 /* Set *RESULTP to true if mapping NFD(S) to lower case is a no-op, or to false
0404    otherwise, and return 0.  Upon failure, return -1 with errno set.  */
0405 extern int
0406        u8_is_lowercase (const uint8_t *s, size_t n,
0407                         const char *iso639_language,
0408                         bool *resultp);
0409 extern int
0410        u16_is_lowercase (const uint16_t *s, size_t n,
0411                          const char *iso639_language,
0412                          bool *resultp);
0413 extern int
0414        u32_is_lowercase (const uint32_t *s, size_t n,
0415                          const char *iso639_language,
0416                          bool *resultp);
0417
0418 /* Set *RESULTP to true if mapping NFD(S) to title case is a no-op, or to false
0419    otherwise, and return 0.  Upon failure, return -1 with errno set.  */
0420 extern int
0421        u8_is_titlecase (const uint8_t *s, size_t n,
0422                         const char *iso639_language,
0423                         bool *resultp);
0424 extern int
0425        u16_is_titlecase (const uint16_t *s, size_t n,
0426                          const char *iso639_language,
0427                          bool *resultp);
0428 extern int
0429        u32_is_titlecase (const uint32_t *s, size_t n,
0430                          const char *iso639_language,
0431                          bool *resultp);
0432
0433 /* Set *RESULTP to true if applying case folding to NFD(S) is a no-op, or to
0434    false otherwise, and return 0.  Upon failure, return -1 with errno set.  */
0435 extern int
0436        u8_is_casefolded (const uint8_t *s, size_t n,
0437                          const char *iso639_language,
0438                          bool *resultp);
0439 extern int
0440        u16_is_casefolded (const uint16_t *s, size_t n,
0441                           const char *iso639_language,
0442                           bool *resultp);
0443 extern int
0444        u32_is_casefolded (const uint32_t *s, size_t n,
0445                           const char *iso639_language,
0446                           bool *resultp);
0447
0448 /* Set *RESULTP to true if case matters for S, that is, if mapping NFD(S) to
0449    either upper case or lower case or title case is not a no-op.
0450    Set *RESULTP to false if NFD(S) maps to itself under the upper case mapping,
0451    under the lower case mapping, and under the title case mapping; in other
0452    words, when NFD(S) consists entirely of caseless characters.
0453    Upon failure, return -1 with errno set.  */
0454 extern int
0455        u8_is_cased (const uint8_t *s, size_t n,
0456                     const char *iso639_language,
0457                     bool *resultp);
0458 extern int
0459        u16_is_cased (const uint16_t *s, size_t n,
0460                      const char *iso639_language,
0461                      bool *resultp);
0462 extern int
0463        u32_is_cased (const uint32_t *s, size_t n,
0464                      const char *iso639_language,
0465                      bool *resultp);
0466
0467
0468 /* ========================================================================= */
0469
0470 #ifdef __cplusplus
0471 }
0472 #endif
0473
0474 #endif /* _UNICASE_H */