lib/unigbrk.in.h

   1 /* Grapheme cluster breaks in Unicode strings.
   2    Copyright (C) 2010-2024 Free Software Foundation, Inc.
   3    Written by Ben Pfaff <blp@cs.stanford.edu>, 2010.
   4
   5    This file is free software.
   6    It is dual-licensed under "the GNU LGPLv3+ or the GNU GPLv2+".
   7    You can redistribute it and/or modify it under either
   8      - the terms of the GNU Lesser General Public License as published
   9        by the Free Software Foundation, either version 3, or (at your
  10        option) any later version, or
  11      - the terms of the GNU General Public License as published by the
  12        Free Software Foundation; either version 2, or (at your option)
  13        any later version, or
  14      - the same dual license "the GNU LGPLv3+ or the GNU GPLv2+".
  15
  16    This file is distributed in the hope that it will be useful,
  17    but WITHOUT ANY WARRANTY; without even the implied warranty of
  18    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19    Lesser General Public License and the GNU General Public License
  20    for more details.
  21
  22    You should have received a copy of the GNU Lesser General Public
  23    License and of the GNU General Public License along with this
  24    program.  If not, see <https://www.gnu.org/licenses/>.  */
  25
  26 #ifndef _UNIGBRK_H
  27 #define _UNIGBRK_H
  28
  29 /* Get bool.  */
  30 #include <stdbool.h>
  31
  32 /* Get size_t. */
  33 #include <stddef.h>
  34
  35 #include "unitypes.h"
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /* ========================================================================= */
  42
  43 /* Property defined in Unicode Standard Annex #29, section "Grapheme Cluster
  44    Boundaries"
  45    <https://unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries> */
  46
  47 /* Possible values of the Grapheme_Cluster_Break property.
  48    This enumeration may be extended in the future.  */
  49 enum
  50 {
  51   GBP_OTHER        = 0,
  52   GBP_CR           = 1,
  53   GBP_LF           = 2,
  54   GBP_CONTROL      = 3,
  55   GBP_EXTEND       = 4,
  56   GBP_PREPEND      = 5,
  57   GBP_SPACINGMARK  = 6,
  58   GBP_L            = 7,
  59   GBP_V            = 8,
  60   GBP_T            = 9,
  61   GBP_LV           = 10,
  62   GBP_LVT          = 11,
  63   GBP_RI           = 12,
  64   GBP_ZWJ          = 13,
  65   GBP_EB           = 14, /* obsolete */
  66   GBP_EM           = 15, /* obsolete */
  67   GBP_GAZ          = 16, /* obsolete */
  68   GBP_EBG          = 17  /* obsolete */
  69 };
  70
  71 /* Return the Grapheme_Cluster_Break property of a Unicode character. */
  72 extern int
  73        uc_graphemeclusterbreak_property (ucs4_t uc)
  74        _UC_ATTRIBUTE_CONST;
  75
  76 /* ========================================================================= */
  77
  78 /* Grapheme cluster breaks.  */
  79
  80 /* Returns true if there is a grapheme cluster boundary between Unicode code
  81    points A and B.  A "grapheme cluster" is an approximation to a
  82    user-perceived character, which sometimes corresponds to multiple code
  83    points.  For example, an English letter followed by an acute accent can be
  84    expressed as two consecutive Unicode code points, but it is perceived by the
  85    user as only a single character and therefore constitutes a single grapheme
  86    cluster.
  87
  88    Implements extended (not legacy) grapheme cluster rules, because UAX #29
  89    indicates that they are preferred.
  90
  91    Note: This function does not work right with syllables in Indic scripts or
  92    emojis, because it does not look at the characters before A and after B.
  93
  94    Use A == 0 or B == 0 to indicate start of text or end of text,
  95    respectively. */
  96 extern bool
  97        uc_is_grapheme_break (ucs4_t a, ucs4_t b)
  98        _UC_ATTRIBUTE_CONST;
  99
 100 /* Returns the start of the next grapheme cluster following S, or NULL if the
 101    end of the string has been reached.
 102    Note: These functions do not work right with syllables in Indic scripts or
 103    emojis, because they do not consider the characters before S. */
 104 extern const uint8_t *
 105        u8_grapheme_next (const uint8_t *s, const uint8_t *end)
 106        _UC_ATTRIBUTE_PURE;
 107 extern const uint16_t *
 108        u16_grapheme_next (const uint16_t *s, const uint16_t *end)
 109        _UC_ATTRIBUTE_PURE;
 110 extern const uint32_t *
 111        u32_grapheme_next (const uint32_t *s, const uint32_t *end)
 112        _UC_ATTRIBUTE_PURE;
 113
 114 /* Returns the start of the previous grapheme cluster before S, or NULL if the
 115    start of the string has been reached.
 116    Note: These functions do not work right with syllables in Indic scripts or
 117    emojis, because they do not consider the characters at or after S. */
 118 extern const uint8_t *
 119        u8_grapheme_prev (const uint8_t *s, const uint8_t *start)
 120        _UC_ATTRIBUTE_PURE;
 121 extern const uint16_t *
 122        u16_grapheme_prev (const uint16_t *s, const uint16_t *start)
 123        _UC_ATTRIBUTE_PURE;
 124 extern const uint32_t *
 125        u32_grapheme_prev (const uint32_t *s, const uint32_t *start)
 126        _UC_ATTRIBUTE_PURE;
 127
 128 /* Determine the grapheme cluster boundaries in S, and store the result at
 129    p[0..n-1].  p[i] = 1 means that a new grapheme cluster begins at s[i].  p[i]
 130    = 0 means that s[i-1] and s[i] are part of the same grapheme cluster.  p[0]
 131    will always be 1.
 132  */
 133 extern void
 134        u8_grapheme_breaks (const uint8_t *s, size_t n, char *p);
 135 extern void
 136        u16_grapheme_breaks (const uint16_t *s, size_t n, char *p);
 137 extern void
 138        u32_grapheme_breaks (const uint32_t *s, size_t n, char *p);
 139 extern void
 140        ulc_grapheme_breaks (const char *s, size_t n, char *p);
 141 extern void
 142        uc_grapheme_breaks (const ucs4_t *s, size_t n, char *p);
 143
 144 /* ========================================================================= */
 145
 146 #ifdef __cplusplus
 147 }
 148 #endif
 149
 150
 151 #endif /* _UNIGBRK_H */