doc/libunistring_10.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
   2 <html>
   3 <!-- Created on September, 1 2014 by texi2html 1.78a -->
   4 <!--
   5 Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
   6             Karl Berry  <karl@freefriends.org>
   7             Olaf Bachmann <obachman@mathematik.uni-kl.de>
   8             and many others.
   9 Maintained by: Many creative people.
  10 Send bugs and suggestions to <texi2html-bug@nongnu.org>
  11
  12 -->
  13 <head>
  14 <title>GNU libunistring: 10. Grapheme cluster breaks in strings &lt;unigbrk.h&gt;</title>
  15
  16 <meta name="description" content="GNU libunistring: 10. Grapheme cluster breaks in strings &lt;unigbrk.h&gt;">
  17 <meta name="keywords" content="GNU libunistring: 10. Grapheme cluster breaks in strings &lt;unigbrk.h&gt;">
  18 <meta name="resource-type" content="document">
  19 <meta name="distribution" content="global">
  20 <meta name="Generator" content="texi2html 1.78a">
  21 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  22 <style type="text/css">
  23 <!--
  24 a.summary-letter {text-decoration: none}
  25 pre.display {font-family: serif}
  26 pre.format {font-family: serif}
  27 pre.menu-comment {font-family: serif}
  28 pre.menu-preformatted {font-family: serif}
  29 pre.smalldisplay {font-family: serif; font-size: smaller}
  30 pre.smallexample {font-size: smaller}
  31 pre.smallformat {font-family: serif; font-size: smaller}
  32 pre.smalllisp {font-size: smaller}
  33 span.roman {font-family:serif; font-weight:normal;}
  34 span.sansserif {font-family:sans-serif; font-weight:normal;}
  35 ul.toc {list-style: none}
  36 -->
  37 </style>
  38
  39
  40 </head>
  41
  42 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  43
  44 <table cellpadding="1" cellspacing="1" border="0">
  45 <tr><td valign="middle" align="left">[<a href="libunistring_9.html#SEC40" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  46 <td valign="middle" align="left">[<a href="libunistring_11.html#SEC44" title="Next chapter"> &gt;&gt; </a>]</td>
  47 <td valign="middle" align="left"> &nbsp; </td>
  48 <td valign="middle" align="left"> &nbsp; </td>
  49 <td valign="middle" align="left"> &nbsp; </td>
  50 <td valign="middle" align="left"> &nbsp; </td>
  51 <td valign="middle" align="left"> &nbsp; </td>
  52 <td valign="middle" align="left">[<a href="libunistring.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
  53 <td valign="middle" align="left">[<a href="libunistring.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  54 <td valign="middle" align="left">[<a href="libunistring_19.html#SEC77" title="Index">Index</a>]</td>
  55 <td valign="middle" align="left">[<a href="libunistring_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  56 </tr></table>
  57
  58 <hr size="2">
  59 <a name="unigbrk_002eh"></a>
  60 <a name="SEC41"></a>
  61 <h1 class="chapter"> <a href="libunistring.html#TOC41">10. Grapheme cluster breaks in strings <code>&lt;unigbrk.h&gt;</code></a> </h1>
  62
  63 <p>This include file declares functions for determining where in a string
  64 &ldquo;grapheme clusters&rdquo; start and end.  A &ldquo;grapheme cluster&rdquo; is an
  65 approximation to a user-perceived character, which sometimes
  66 corresponds to multiple Unicode characters.  Editing operations such as
  67 mouse selection, cursor movement, and backspacing often operate on
  68 grapheme clusters as units, not on individual characters.
  69 </p>
  70 <p>Some grapheme clusters are built from a base character and a combining
  71 character.  The letter &lsquo;<samp>&eacute;</samp>&rsquo;,
  72 for example, is most commonly represented in Unicode as a single
  73 character U+00E8 <small>LATIN SMALL LETTER E WITH ACUTE</small>.  It is,
  74 however, equally valid to use the pair of characters U+0065 <small>LATIN
  75 SMALL LETTER E</small> followed by U+0301 <small>COMBINING ACUTE ACCENT</small>.  Since
  76 the user would perceive this pair of characters as a single character,
  77 they would be grouped into a single grapheme cluster.
  78 </p>
  79 <p>But there are also grapheme clusters that consist of several base characters.
  80 For example, a Devanagari letter and a Devanagari vowel sign that follows it
  81 may form a grapheme cluster.  Similarly, some pairs of Thai characters and
  82 Hangul syllables (formed by two or three Hangul characters) are grapheme
  83 clusters.
  84 </p>
  85
  86 <hr size="6">
  87 <a name="Grapheme-cluster-breaks-in-a-string"></a>
  88 <a name="SEC42"></a>
  89 <h2 class="section"> <a href="libunistring.html#TOC42">10.1 Grapheme cluster breaks in a string</a> </h2>
  90
  91 <p>The following functions find a single boundary between grapheme
  92 clusters in a string.
  93 </p>
  94 <dl>
  95 <dt><u>Function:</u> void <b>u8_grapheme_next</b><i> (const uint8_t *<var>s</var>, const uint8_t *<var>end</var>)</i>
  96 <a name="IDX712"></a>
  97 </dt>
  98 <dt><u>Function:</u> void <b>u16_grapheme_next</b><i> (const uint16_t *<var>s</var>, const uint16_t *<var>end</var>)</i>
  99 <a name="IDX713"></a>
 100 </dt>
 101 <dt><u>Function:</u> void <b>u32_grapheme_next</b><i> (const uint32_t *<var>s</var>, const uint32_t *<var>end</var>)</i>
 102 <a name="IDX714"></a>
 103 </dt>
 104 <dd><p>Returns the start of the next grapheme cluster following <var>s</var>,
 105 or <var>end</var> if no grapheme cluster break is encountered before it.
 106 Returns NULL if and only if <code><var>s</var> == <var>end</var></code>.
 107 </p></dd></dl>
 108
 109 <dl>
 110 <dt><u>Function:</u> void <b>u8_grapheme_prev</b><i> (const uint8_t *<var>s</var>, const uint8_t *<var>start</var>)</i>
 111 <a name="IDX715"></a>
 112 </dt>
 113 <dt><u>Function:</u> void <b>u16_grapheme_prev</b><i> (const uint16_t *<var>s</var>, const uint16_t *<var>start</var>)</i>
 114 <a name="IDX716"></a>
 115 </dt>
 116 <dt><u>Function:</u> void <b>u32_grapheme_prev</b><i> (const uint32_t *<var>s</var>, const uint32_t *<var>start</var>)</i>
 117 <a name="IDX717"></a>
 118 </dt>
 119 <dd><p>Returns the start of the grapheme cluster preceding <var>s</var>, or
 120 <var>start</var> if no grapheme cluster break is encountered before it.
 121 Returns NULL if and only if <code><var>s</var> == <var>start</var></code>.
 122 </p></dd></dl>
 123
 124 <p>The following functions determine all of the grapheme cluster
 125 boundaries in a string.
 126 </p>
 127 <dl>
 128 <dt><u>Function:</u> void <b>u8_grapheme_breaks</b><i> (const uint8_t *<var>s</var>, size_t <var>n</var>, char *<var>p</var>)</i>
 129 <a name="IDX718"></a>
 130 </dt>
 131 <dt><u>Function:</u> void <b>u16_grapheme_breaks</b><i> (const uint16_t *<var>s</var>, size_t <var>n</var>, char *<var>p</var>)</i>
 132 <a name="IDX719"></a>
 133 </dt>
 134 <dt><u>Function:</u> void <b>u32_grapheme_breaks</b><i> (const uint32_t *<var>s</var>, size_t <var>n</var>, char *<var>p</var>)</i>
 135 <a name="IDX720"></a>
 136 </dt>
 137 <dt><u>Function:</u> void <b>ulc_grapheme_breaks</b><i> (const char *<var>s</var>, size_t <var>n</var>, char *<var>p</var>)</i>
 138 <a name="IDX721"></a>
 139 </dt>
 140 <dd><p>Determines the grapheme cluster break points in <var>s</var>, an array of
 141 <var>n</var> units, and stores the result at <code><var>p</var>[0..<var>n</var>-1]</code>.
 142 </p><dl compact="compact">
 143 <dt> <code><var>p</var>[i] = 1</code></dt>
 144 <dd><p>means that there is a grapheme cluster boundary between
 145 <code><var>s</var>[i-1]</code> and <code><var>s</var>[i]</code>.
 146 </p></dd>
 147 <dt> <code><var>p</var>[i] = 0</code></dt>
 148 <dd><p>means that <code><var>s</var>[i-1]</code> and <code><var>s</var>[i]</code> are part of the
 149 same grapheme cluster.
 150 </p></dd>
 151 </dl>
 152 <p><code><var>p</var>[0]</code> is always set to 1, because there is always a
 153 grapheme cluster break at start of text.
 154 </p></dd></dl>
 155
 156 <hr size="6">
 157 <a name="Grapheme-cluster-break-property"></a>
 158 <a name="SEC43"></a>
 159 <h2 class="section"> <a href="libunistring.html#TOC43">10.2 Grapheme cluster break property</a> </h2>
 160
 161 <p>This is a more low-level API.  The grapheme cluster break property is a
 162 property defined in Unicode Standard Annex #29, section &ldquo;Grapheme Cluster
 163 Boundaries&rdquo;, see
 164 <a href="http://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries">http://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries</a>.
 165 It is used for determining the grapheme cluster breaks in a string.
 166 </p>
 167 <p>The following are the possible values of the grapheme cluster break
 168 property.  More values may be added in the future.
 169 </p>
 170 <dl>
 171 <dt><u>Constant:</u> int <b>GBP_OTHER</b>
 172 <a name="IDX722"></a>
 173 </dt>
 174 <dt><u>Constant:</u> int <b>GBP_CR</b>
 175 <a name="IDX723"></a>
 176 </dt>
 177 <dt><u>Constant:</u> int <b>GBP_LF</b>
 178 <a name="IDX724"></a>
 179 </dt>
 180 <dt><u>Constant:</u> int <b>GBP_CONTROL</b>
 181 <a name="IDX725"></a>
 182 </dt>
 183 <dt><u>Constant:</u> int <b>GBP_EXTEND</b>
 184 <a name="IDX726"></a>
 185 </dt>
 186 <dt><u>Constant:</u> int <b>GBP_PREPEND</b>
 187 <a name="IDX727"></a>
 188 </dt>
 189 <dt><u>Constant:</u> int <b>GBP_SPACINGMARK</b>
 190 <a name="IDX728"></a>
 191 </dt>
 192 <dt><u>Constant:</u> int <b>GBP_L</b>
 193 <a name="IDX729"></a>
 194 </dt>
 195 <dt><u>Constant:</u> int <b>GBP_V</b>
 196 <a name="IDX730"></a>
 197 </dt>
 198 <dt><u>Constant:</u> int <b>GBP_T</b>
 199 <a name="IDX731"></a>
 200 </dt>
 201 <dt><u>Constant:</u> int <b>GBP_LV</b>
 202 <a name="IDX732"></a>
 203 </dt>
 204 <dt><u>Constant:</u> int <b>GBP_LVT</b>
 205 <a name="IDX733"></a>
 206 </dt>
 207 </dl>
 208
 209 <p>The following function looks up the grapheme cluster break property of a
 210 character.
 211 </p>
 212 <dl>
 213 <dt><u>Function:</u> int <b>uc_graphemeclusterbreak_property</b><i> (ucs4_t <var>uc</var>)</i>
 214 <a name="IDX734"></a>
 215 </dt>
 216 <dd><p>Returns the Grapheme_Cluster_Break property of a Unicode character.
 217 </p></dd></dl>
 218
 219 <p>The following function determines whether there is a grapheme cluster
 220 break between two Unicode characters.  It is the primitive upon which
 221 the higher-level functions in the previous section are directly based.
 222 </p>
 223 <dl>
 224 <dt><u>Function:</u> bool <b>uc_is_grapheme_break</b><i> (ucs4_t <var>a</var>, ucs4_t <var>b</var>)</i>
 225 <a name="IDX735"></a>
 226 </dt>
 227 <dd><p>Returns true if there is an grapheme cluster boundary between Unicode
 228 characters <var>a</var> and <var>b</var>.
 229 </p>
 230 <p>There is always a grapheme cluster break at the start or end of text.
 231 You can specify zero for <var>a</var> or <var>b</var> to indicate start of text or end
 232 of text, respectively.
 233 </p>
 234 <p>This implements the extended (not legacy) grapheme cluster rules
 235 described in the Unicode standard, because the standard says that they
 236 are preferred.
 237 </p></dd></dl>
 238 <hr size="6">
 239 <table cellpadding="1" cellspacing="1" border="0">
 240 <tr><td valign="middle" align="left">[<a href="#SEC41" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
 241 <td valign="middle" align="left">[<a href="libunistring_11.html#SEC44" title="Next chapter"> &gt;&gt; </a>]</td>
 242 <td valign="middle" align="left"> &nbsp; </td>
 243 <td valign="middle" align="left"> &nbsp; </td>
 244 <td valign="middle" align="left"> &nbsp; </td>
 245 <td valign="middle" align="left"> &nbsp; </td>
 246 <td valign="middle" align="left"> &nbsp; </td>
 247 <td valign="middle" align="left">[<a href="libunistring.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
 248 <td valign="middle" align="left">[<a href="libunistring.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
 249 <td valign="middle" align="left">[<a href="libunistring_19.html#SEC77" title="Index">Index</a>]</td>
 250 <td valign="middle" align="left">[<a href="libunistring_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
 251 </tr></table>
 252 <p>
 253  <font size="-1">
 254   This document was generated by <em>Daiki Ueno</em> on <em>September, 1 2014</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html 1.78a</em></a>.
 255  </font>
 256  <br>
 257
 258 </p>
 259 </body>
 260 </html>