doc/unigbrk.texi

   1 @node unigbrk.h
   2 @chapter Grapheme cluster breaks in strings @code{<unigbrk.h>}
   3
   4 @cindex grapheme cluster breaks
   5 @cindex grapheme cluster boundaries
   6 @cindex breaks, grapheme cluster
   7 @cindex boundaries, between grapheme clusters
   8 This include file declares functions for determining where in a string
   9 ``grapheme clusters'' start and end.  A ``grapheme cluster'' is an
  10 approximation to a user-perceived character, which sometimes
  11 corresponds to multiple Unicode characters.  Editing operations such as
  12 mouse selection, cursor movement, and backspacing often operate on
  13 grapheme clusters as units, not on individual characters.
  14
  15 Some grapheme clusters are built from a base character and a combining
  16 character.  The letter @samp{@'e},
  17 for example, is most commonly represented in Unicode as a single
  18 character U+00E8 @sc{LATIN SMALL LETTER E WITH ACUTE}.  It is,
  19 however, equally valid to use the pair of characters U+0065 @sc{LATIN
  20 SMALL LETTER E} followed by U+0301 @sc{COMBINING ACUTE ACCENT}.  Since
  21 the user would perceive this pair of characters as a single character,
  22 they would be grouped into a single grapheme cluster.
  23
  24 But there are also grapheme clusters that consist of several base characters.
  25 For example, a Devanagari letter and a Devanagari vowel sign that follows it
  26 may form a grapheme cluster.  Similarly, some pairs of Thai characters and
  27 Hangul syllables (formed by two or three Hangul characters) are grapheme
  28 clusters.
  29
  30 @menu
  31 * Grapheme cluster breaks in a string::
  32 * Grapheme cluster break property::
  33 @end menu
  34
  35 @node Grapheme cluster breaks in a string
  36 @section Grapheme cluster breaks in a string
  37
  38 The following functions find a single boundary between grapheme
  39 clusters in a string.
  40
  41 @deftypefun void u8_grapheme_next (const uint8_t *@var{s}, const uint8_t *@var{end})
  42 @deftypefunx void u16_grapheme_next (const uint16_t *@var{s}, const uint16_t *@var{end})
  43 @deftypefunx void u32_grapheme_next (const uint32_t *@var{s}, const uint32_t *@var{end})
  44 Returns the start of the next grapheme cluster following @var{s},
  45 or @var{end} if no grapheme cluster break is encountered before it.
  46 Returns NULL if and only if @code{@var{s} == @var{end}}.
  47 @end deftypefun
  48
  49 @deftypefun void u8_grapheme_prev (const uint8_t *@var{s}, const uint8_t *@var{start})
  50 @deftypefunx void u16_grapheme_prev (const uint16_t *@var{s}, const uint16_t *@var{start})
  51 @deftypefunx void u32_grapheme_prev (const uint32_t *@var{s}, const uint32_t *@var{start})
  52 Returns the start of the grapheme cluster preceding @var{s}, or
  53 @var{start} if no grapheme cluster break is encountered before it.
  54 Returns NULL if and only if @code{@var{s} == @var{start}}.
  55 @end deftypefun
  56
  57 The following functions determine all of the grapheme cluster
  58 boundaries in a string.
  59
  60 @deftypefun void u8_grapheme_breaks (const uint8_t *@var{s}, size_t @var{n}, char *@var{p})
  61 @deftypefunx void u16_grapheme_breaks (const uint16_t *@var{s}, size_t @var{n}, char *@var{p})
  62 @deftypefunx void u32_grapheme_breaks (const uint32_t *@var{s}, size_t @var{n}, char *@var{p})
  63 @deftypefunx void ulc_grapheme_breaks (const char *@var{s}, size_t @var{n}, char *@var{p})
  64 Determines the grapheme cluster break points in @var{s}, an array of
  65 @var{n} units, and stores the result at @code{@var{p}[0..@var{n}-1]}.
  66 @table @asis
  67 @item @code{@var{p}[i] = 1}
  68 means that there is a grapheme cluster boundary between
  69 @code{@var{s}[i-1]} and @code{@var{s}[i]}.
  70 @item @code{@var{p}[i] = 0}
  71 means that @code{@var{s}[i-1]} and @code{@var{s}[i]} are part of the
  72 same grapheme cluster.
  73 @end table
  74 @code{@var{p}[0]} is always set to 1, because there is always a
  75 grapheme cluster break at start of text.
  76 @end deftypefun
  77
  78 @node Grapheme cluster break property
  79 @section Grapheme cluster break property
  80
  81 This is a more low-level API.  The grapheme cluster break property is a
  82 property defined in Unicode Standard Annex #29, section ``Grapheme Cluster
  83 Boundaries'', see
  84 @url{http://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries}.@texnl{}
  85 It is used for determining the grapheme cluster breaks in a string.
  86
  87 The following are the possible values of the grapheme cluster break
  88 property.  More values may be added in the future.
  89
  90 @deftypevr Constant int GBP_OTHER
  91 @deftypevrx Constant int GBP_CR
  92 @deftypevrx Constant int GBP_LF
  93 @deftypevrx Constant int GBP_CONTROL
  94 @deftypevrx Constant int GBP_EXTEND
  95 @deftypevrx Constant int GBP_PREPEND
  96 @deftypevrx Constant int GBP_SPACINGMARK
  97 @deftypevrx Constant int GBP_L
  98 @deftypevrx Constant int GBP_V
  99 @deftypevrx Constant int GBP_T
 100 @deftypevrx Constant int GBP_LV
 101 @deftypevrx Constant int GBP_LVT
 102 @end deftypevr
 103
 104 The following function looks up the grapheme cluster break property of a
 105 character.
 106
 107 @deftypefun int uc_graphemeclusterbreak_property (ucs4_t @var{uc})
 108 Returns the Grapheme_Cluster_Break property of a Unicode character.
 109 @end deftypefun
 110
 111 The following function determines whether there is a grapheme cluster
 112 break between two Unicode characters.  It is the primitive upon which
 113 the higher-level functions in the previous section are directly based.
 114
 115 @deftypefun bool uc_is_grapheme_break (ucs4_t @var{a}, ucs4_t @var{b})
 116 Returns true if there is an grapheme cluster boundary between Unicode
 117 characters @var{a} and @var{b}.
 118
 119 There is always a grapheme cluster break at the start or end of text.
 120 You can specify zero for @var{a} or @var{b} to indicate start of text or end
 121 of text, respectively.
 122
 123 This implements the extended (not legacy) grapheme cluster rules
 124 described in the Unicode standard, because the standard says that they
 125 are preferred.
 126 @end deftypefun