glib/gunidecomp.c

   1 /* decomp.c - Character decomposition.
   2  *
   3  *  Copyright (C) 1999, 2000 Tom Tromey
   4  *  Copyright 2000 Red Hat, Inc.
   5  *
   6  * SPDX-License-Identifier: LGPL-2.1-or-later
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2.1 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public License
  19  * along with this library; if not, see <http://www.gnu.org/licenses/>.
  20  */
  21
  22 /**
  23  * SECTION:unicode
  24  * @Title: Unicode Manipulation
  25  * @Short_description: functions operating on Unicode characters and
  26  *     UTF-8 strings
  27  * @See_also: g_locale_to_utf8(), g_locale_from_utf8()
  28  *
  29  * This section describes a number of functions for dealing with
  30  * Unicode characters and strings. There are analogues of the
  31  * traditional `ctype.h` character classification and case conversion
  32  * functions, UTF-8 analogues of some string utility functions,
  33  * functions to perform normalization, case conversion and collation
  34  * on UTF-8 strings and finally functions to convert between the UTF-8,
  35  * UTF-16 and UCS-4 encodings of Unicode.
  36  *
  37  * The implementations of the Unicode functions in GLib are based
  38  * on the Unicode Character Data tables, which are available from
  39  * [www.unicode.org](http://www.unicode.org/).
  40  *
  41  *  * Unicode 4.0 was added in GLib 2.8
  42  *  * Unicode 4.1 was added in GLib 2.10
  43  *  * Unicode 5.0 was added in GLib 2.12
  44  *  * Unicode 5.1 was added in GLib 2.16.3
  45  *  * Unicode 6.0 was added in GLib 2.30
  46  *  * Unicode 6.1 was added in GLib 2.32
  47  *  * Unicode 6.2 was added in GLib 2.36
  48  *  * Unicode 6.3 was added in GLib 2.40
  49  *  * Unicode 7.0 was added in GLib 2.42
  50  *  * Unicode 8.0 was added in GLib 2.48
  51  *  * Unicode 9.0 was added in GLib 2.50.1
  52  *  * Unicode 10.0 was added in GLib 2.54
  53  *  * Unicode 11.10 was added in GLib 2.58
  54  *  * Unicode 12.0 was added in GLib 2.62
  55  *  * Unicode 12.1 was added in GLib 2.62
  56  *  * Unicode 13.0 was added in GLib 2.66
  57  */
  58
  59 #include "config.h"
  60
  61 #include <stdlib.h>
  62
  63 #include "gunicode.h"
  64 #include "gunidecomp.h"
  65 #include "gmem.h"
  66 #include "gunicomp.h"
  67 #include "gunicodeprivate.h"
  68
  69
  70 #define CC_PART1(Page, Char) \
  71   ((combining_class_table_part1[Page] >= G_UNICODE_MAX_TABLE_INDEX) \
  72    ? (combining_class_table_part1[Page] - G_UNICODE_MAX_TABLE_INDEX) \
  73    : (cclass_data[combining_class_table_part1[Page]][Char]))
  74
  75 #define CC_PART2(Page, Char) \
  76   ((combining_class_table_part2[Page] >= G_UNICODE_MAX_TABLE_INDEX) \
  77    ? (combining_class_table_part2[Page] - G_UNICODE_MAX_TABLE_INDEX) \
  78    : (cclass_data[combining_class_table_part2[Page]][Char]))
  79
  80 #define COMBINING_CLASS(Char) \
  81   (((Char) <= G_UNICODE_LAST_CHAR_PART1) \
  82    ? CC_PART1 ((Char) >> 8, (Char) & 0xff) \
  83    : (((Char) >= 0xe0000 && (Char) <= G_UNICODE_LAST_CHAR) \
  84       ? CC_PART2 (((Char) - 0xe0000) >> 8, (Char) & 0xff) \
  85       : 0))
  86
  87 /**
  88  * g_unichar_combining_class:
  89  * @uc: a Unicode character
  90  *
  91  * Determines the canonical combining class of a Unicode character.
  92  *
  93  * Returns: the combining class of the character
  94  *
  95  * Since: 2.14
  96  **/
  97 gint
  98 g_unichar_combining_class (gunichar uc)
  99 {
 100   return COMBINING_CLASS (uc);
 101 }
 102
 103 /* constants for hangul syllable [de]composition */
 104 #define SBase 0xAC00
 105 #define LBase 0x1100
 106 #define VBase 0x1161
 107 #define TBase 0x11A7
 108 #define LCount 19
 109 #define VCount 21
 110 #define TCount 28
 111 #define NCount (VCount * TCount)
 112 #define SCount (LCount * NCount)
 113
 114 /**
 115  * g_unicode_canonical_ordering:
 116  * @string: (array length=len) (element-type gunichar): a UCS-4 encoded string.
 117  * @len: the maximum length of @string to use.
 118  *
 119  * Computes the canonical ordering of a string in-place.
 120  * This rearranges decomposed characters in the string
 121  * according to their combining classes.  See the Unicode
 122  * manual for more information.
 123  **/
 124 void
 125 g_unicode_canonical_ordering (gunichar *string,
 126                               gsize     len)
 127 {
 128   gsize i;
 129   int swap = 1;
 130
 131   while (swap)
 132     {
 133       int last;
 134       swap = 0;
 135       last = COMBINING_CLASS (string[0]);
 136       for (i = 0; i < len - 1; ++i)
 137         {
 138           int next = COMBINING_CLASS (string[i + 1]);
 139           if (next != 0 && last > next)
 140             {
 141               gsize j;
 142               /* Percolate item leftward through string.  */
 143               for (j = i + 1; j > 0; --j)
 144                 {
 145                   gunichar t;
 146                   if (COMBINING_CLASS (string[j - 1]) <= next)
 147                     break;
 148                   t = string[j];
 149                   string[j] = string[j - 1];
 150                   string[j - 1] = t;
 151                   swap = 1;
 152                 }
 153               /* We're re-entering the loop looking at the old
 154                  character again.  */
 155               next = last;
 156             }
 157           last = next;
 158         }
 159     }
 160 }
 161
 162 /* http://www.unicode.org/unicode/reports/tr15/#Hangul
 163  * r should be null or have sufficient space. Calling with r == NULL will
 164  * only calculate the result_len; however, a buffer with space for three
 165  * characters will always be big enough. */
 166 static void
 167 decompose_hangul (gunichar s,
 168                   gunichar *r,
 169                   gsize *result_len)
 170 {
 171   gint SIndex = s - SBase;
 172   gint TIndex = SIndex % TCount;
 173
 174   if (r)
 175     {
 176       r[0] = LBase + SIndex / NCount;
 177       r[1] = VBase + (SIndex % NCount) / TCount;
 178     }
 179
 180   if (TIndex)
 181     {
 182       if (r)
 183         r[2] = TBase + TIndex;
 184       *result_len = 3;
 185     }
 186   else
 187     *result_len = 2;
 188 }
 189
 190 /* returns a pointer to a null-terminated UTF-8 string */
 191 static const gchar *
 192 find_decomposition (gunichar ch,
 193                     gboolean compat)
 194 {
 195   int start = 0;
 196   int end = G_N_ELEMENTS (decomp_table);
 197
 198   if (ch >= decomp_table[start].ch &&
 199       ch <= decomp_table[end - 1].ch)
 200     {
 201       while (TRUE)
 202         {
 203           int half = (start + end) / 2;
 204           if (ch == decomp_table[half].ch)
 205             {
 206               int offset;
 207
 208               if (compat)
 209                 {
 210                   offset = decomp_table[half].compat_offset;
 211                   if (offset == G_UNICODE_NOT_PRESENT_OFFSET)
 212                     offset = decomp_table[half].canon_offset;
 213                 }
 214               else
 215                 {
 216                   offset = decomp_table[half].canon_offset;
 217                   if (offset == G_UNICODE_NOT_PRESENT_OFFSET)
 218                     return NULL;
 219                 }
 220
 221               return &(decomp_expansion_string[offset]);
 222             }
 223           else if (half == start)
 224             break;
 225           else if (ch > decomp_table[half].ch)
 226             start = half;
 227           else
 228             end = half;
 229         }
 230     }
 231
 232   return NULL;
 233 }
 234
 235 /**
 236  * g_unicode_canonical_decomposition:
 237  * @ch: a Unicode character.
 238  * @result_len: location to store the length of the return value.
 239  *
 240  * Computes the canonical decomposition of a Unicode character.
 241  *
 242  * Returns: a newly allocated string of Unicode characters.
 243  *   @result_len is set to the resulting length of the string.
 244  *
 245  * Deprecated: 2.30: Use the more flexible g_unichar_fully_decompose()
 246  *   instead.
 247  **/
 248 gunichar *
 249 g_unicode_canonical_decomposition (gunichar ch,
 250                                    gsize   *result_len)
 251 {
 252   const gchar *decomp;
 253   const gchar *p;
 254   gunichar *r;
 255
 256   /* Hangul syllable */
 257   if (ch >= SBase && ch < SBase + SCount)
 258     {
 259       decompose_hangul (ch, NULL, result_len);
 260       r = g_malloc (*result_len * sizeof (gunichar));
 261       decompose_hangul (ch, r, result_len);
 262     }
 263   else if ((decomp = find_decomposition (ch, FALSE)) != NULL)
 264     {
 265       /* Found it.  */
 266       int i;
 267
 268       *result_len = g_utf8_strlen (decomp, -1);
 269       r = g_malloc (*result_len * sizeof (gunichar));
 270
 271       for (p = decomp, i = 0; *p != '\0'; p = g_utf8_next_char (p), i++)
 272         r[i] = g_utf8_get_char (p);
 273     }
 274   else
 275     {
 276       /* Not in our table.  */
 277       r = g_malloc (sizeof (gunichar));
 278       *r = ch;
 279       *result_len = 1;
 280     }
 281
 282   return r;
 283 }
 284
 285 /* L,V => LV and LV,T => LVT  */
 286 static gboolean
 287 combine_hangul (gunichar a,
 288                 gunichar b,
 289                 gunichar *result)
 290 {
 291   gint LIndex = a - LBase;
 292   gint SIndex = a - SBase;
 293
 294   gint VIndex = b - VBase;
 295   gint TIndex = b - TBase;
 296
 297   if (0 <= LIndex && LIndex < LCount
 298       && 0 <= VIndex && VIndex < VCount)
 299     {
 300       *result = SBase + (LIndex * VCount + VIndex) * TCount;
 301       return TRUE;
 302     }
 303   else if (0 <= SIndex && SIndex < SCount && (SIndex % TCount) == 0
 304            && 0 < TIndex && TIndex < TCount)
 305     {
 306       *result = a + TIndex;
 307       return TRUE;
 308     }
 309
 310   return FALSE;
 311 }
 312
 313 #define CI(Page, Char) \
 314   ((compose_table[Page] >= G_UNICODE_MAX_TABLE_INDEX) \
 315    ? (compose_table[Page] - G_UNICODE_MAX_TABLE_INDEX) \
 316    : (compose_data[compose_table[Page]][Char]))
 317
 318 #define COMPOSE_INDEX(Char) \
 319      (((Char >> 8) > (COMPOSE_TABLE_LAST)) ? 0 : CI((Char) >> 8, (Char) & 0xff))
 320
 321 static gboolean
 322 combine (gunichar  a,
 323          gunichar  b,
 324          gunichar *result)
 325 {
 326   gushort index_a, index_b;
 327
 328   if (combine_hangul (a, b, result))
 329     return TRUE;
 330
 331   index_a = COMPOSE_INDEX(a);
 332
 333   if (index_a >= COMPOSE_FIRST_SINGLE_START && index_a < COMPOSE_SECOND_START)
 334     {
 335       if (b == compose_first_single[index_a - COMPOSE_FIRST_SINGLE_START][0])
 336         {
 337           *result = compose_first_single[index_a - COMPOSE_FIRST_SINGLE_START][1];
 338           return TRUE;
 339         }
 340       else
 341         return FALSE;
 342     }
 343
 344   index_b = COMPOSE_INDEX(b);
 345
 346   if (index_b >= COMPOSE_SECOND_SINGLE_START)
 347     {
 348       if (a == compose_second_single[index_b - COMPOSE_SECOND_SINGLE_START][0])
 349         {
 350           *result = compose_second_single[index_b - COMPOSE_SECOND_SINGLE_START][1];
 351           return TRUE;
 352         }
 353       else
 354         return FALSE;
 355     }
 356
 357   if (index_a >= COMPOSE_FIRST_START && index_a < COMPOSE_FIRST_SINGLE_START &&
 358       index_b >= COMPOSE_SECOND_START && index_b < COMPOSE_SECOND_SINGLE_START)
 359     {
 360       gunichar res = compose_array[index_a - COMPOSE_FIRST_START][index_b - COMPOSE_SECOND_START];
 361
 362       if (res)
 363         {
 364           *result = res;
 365           return TRUE;
 366         }
 367     }
 368
 369   return FALSE;
 370 }
 371
 372 gunichar *
 373 _g_utf8_normalize_wc (const gchar    *str,
 374                       gssize          max_len,
 375                       GNormalizeMode  mode)
 376 {
 377   gsize n_wc;
 378   gunichar *wc_buffer;
 379   const char *p;
 380   gsize last_start;
 381   gboolean do_compat = (mode == G_NORMALIZE_NFKC ||
 382                         mode == G_NORMALIZE_NFKD);
 383   gboolean do_compose = (mode == G_NORMALIZE_NFC ||
 384                          mode == G_NORMALIZE_NFKC);
 385
 386   n_wc = 0;
 387   p = str;
 388   while ((max_len < 0 || p < str + max_len) && *p)
 389     {
 390       const gchar *decomp;
 391       const char *next, *between;
 392       gunichar wc;
 393
 394       next = g_utf8_next_char (p);
 395       /* Avoid reading truncated multibyte characters
 396          which run past the end of the buffer */
 397       if (max_len < 0)
 398         {
 399           /* Does the character contain a NUL terminator? */
 400           for (between = &p[1]; between < next; between++)
 401             {
 402               if (G_UNLIKELY (!*between))
 403                 return NULL;
 404             }
 405         }
 406       else
 407         {
 408           if (G_UNLIKELY (next > str + max_len))
 409             return NULL;
 410         }
 411       wc = g_utf8_get_char (p);
 412
 413       if (G_UNLIKELY (wc == (gunichar) -1))
 414         {
 415           return NULL;
 416         }
 417       else if (wc >= SBase && wc < SBase + SCount)
 418         {
 419           gsize result_len;
 420           decompose_hangul (wc, NULL, &result_len);
 421           n_wc += result_len;
 422         }
 423       else
 424         {
 425           decomp = find_decomposition (wc, do_compat);
 426
 427           if (decomp)
 428             n_wc += g_utf8_strlen (decomp, -1);
 429           else
 430             n_wc++;
 431         }
 432
 433       p = next;
 434     }
 435
 436   wc_buffer = g_new (gunichar, n_wc + 1);
 437
 438   last_start = 0;
 439   n_wc = 0;
 440   p = str;
 441   while ((max_len < 0 || p < str + max_len) && *p)
 442     {
 443       gunichar wc = g_utf8_get_char (p);
 444       const gchar *decomp;
 445       int cc;
 446       gsize old_n_wc = n_wc;
 447
 448       if (wc >= SBase && wc < SBase + SCount)
 449         {
 450           gsize result_len;
 451           decompose_hangul (wc, wc_buffer + n_wc, &result_len);
 452           n_wc += result_len;
 453         }
 454       else
 455         {
 456           decomp = find_decomposition (wc, do_compat);
 457
 458           if (decomp)
 459             {
 460               const char *pd;
 461               for (pd = decomp; *pd != '\0'; pd = g_utf8_next_char (pd))
 462                 wc_buffer[n_wc++] = g_utf8_get_char (pd);
 463             }
 464           else
 465             wc_buffer[n_wc++] = wc;
 466         }
 467
 468       if (n_wc > 0)
 469         {
 470           cc = COMBINING_CLASS (wc_buffer[old_n_wc]);
 471
 472           if (cc == 0)
 473             {
 474               g_unicode_canonical_ordering (wc_buffer + last_start, n_wc - last_start);
 475               last_start = old_n_wc;
 476             }
 477         }
 478
 479       p = g_utf8_next_char (p);
 480     }
 481
 482   if (n_wc > 0)
 483     {
 484       g_unicode_canonical_ordering (wc_buffer + last_start, n_wc - last_start);
 485       last_start = n_wc;
 486       (void) last_start;
 487     }
 488
 489   wc_buffer[n_wc] = 0;
 490
 491   /* All decomposed and reordered */
 492
 493   if (do_compose && n_wc > 0)
 494     {
 495       gsize i, j;
 496       int last_cc = 0;
 497       last_start = 0;
 498
 499       for (i = 0; i < n_wc; i++)
 500         {
 501           int cc = COMBINING_CLASS (wc_buffer[i]);
 502
 503           if (i > 0 &&
 504               (last_cc == 0 || last_cc < cc) &&
 505               combine (wc_buffer[last_start], wc_buffer[i],
 506                        &wc_buffer[last_start]))
 507             {
 508               for (j = i + 1; j < n_wc; j++)
 509                 wc_buffer[j-1] = wc_buffer[j];
 510               n_wc--;
 511               i--;
 512
 513               if (i == last_start)
 514                 last_cc = 0;
 515               else
 516                 last_cc = COMBINING_CLASS (wc_buffer[i-1]);
 517
 518               continue;
 519             }
 520
 521           if (cc == 0)
 522             last_start = i;
 523
 524           last_cc = cc;
 525         }
 526     }
 527
 528   wc_buffer[n_wc] = 0;
 529
 530   return wc_buffer;
 531 }
 532
 533 /**
 534  * g_utf8_normalize:
 535  * @str: a UTF-8 encoded string.
 536  * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
 537  * @mode: the type of normalization to perform.
 538  *
 539  * Converts a string into canonical form, standardizing
 540  * such issues as whether a character with an accent
 541  * is represented as a base character and combining
 542  * accent or as a single precomposed character. The
 543  * string has to be valid UTF-8, otherwise %NULL is
 544  * returned. You should generally call g_utf8_normalize()
 545  * before comparing two Unicode strings.
 546  *
 547  * The normalization mode %G_NORMALIZE_DEFAULT only
 548  * standardizes differences that do not affect the
 549  * text content, such as the above-mentioned accent
 550  * representation. %G_NORMALIZE_ALL also standardizes
 551  * the "compatibility" characters in Unicode, such
 552  * as SUPERSCRIPT THREE to the standard forms
 553  * (in this case DIGIT THREE). Formatting information
 554  * may be lost but for most text operations such
 555  * characters should be considered the same.
 556  *
 557  * %G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE
 558  * are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_ALL,
 559  * but returned a result with composed forms rather
 560  * than a maximally decomposed form. This is often
 561  * useful if you intend to convert the string to
 562  * a legacy encoding or pass it to a system with
 563  * less capable Unicode handling.
 564  *
 565  * Returns: (nullable): a newly allocated string, that
 566  *   is the normalized form of @str, or %NULL if @str
 567  *   is not valid UTF-8.
 568  **/
 569 gchar *
 570 g_utf8_normalize (const gchar    *str,
 571                   gssize          len,
 572                   GNormalizeMode  mode)
 573 {
 574   gunichar *result_wc = _g_utf8_normalize_wc (str, len, mode);
 575   gchar *result = NULL;
 576
 577   if (G_LIKELY (result_wc != NULL))
 578     {
 579       result = g_ucs4_to_utf8 (result_wc, -1, NULL, NULL, NULL);
 580       g_free (result_wc);
 581     }
 582
 583   return result;
 584 }
 585
 586 static gboolean
 587 decompose_hangul_step (gunichar  ch,
 588                        gunichar *a,
 589                        gunichar *b)
 590 {
 591   gint SIndex, TIndex;
 592
 593   if (ch < SBase || ch >= SBase + SCount)
 594     return FALSE;  /* not a hangul syllable */
 595
 596   SIndex = ch - SBase;
 597   TIndex = SIndex % TCount;
 598
 599   if (TIndex)
 600     {
 601       /* split LVT -> LV,T */
 602       *a = ch - TIndex;
 603       *b = TBase + TIndex;
 604     }
 605   else
 606     {
 607       /* split LV -> L,V */
 608       *a = LBase + SIndex / NCount;
 609       *b = VBase + (SIndex % NCount) / TCount;
 610     }
 611
 612   return TRUE;
 613 }
 614
 615 /**
 616  * g_unichar_decompose:
 617  * @ch: a Unicode character
 618  * @a: (out) (not optional): return location for the first component of @ch
 619  * @b: (out) (not optional): return location for the second component of @ch
 620  *
 621  * Performs a single decomposition step of the
 622  * Unicode canonical decomposition algorithm.
 623  *
 624  * This function does not include compatibility
 625  * decompositions. It does, however, include algorithmic
 626  * Hangul Jamo decomposition, as well as 'singleton'
 627  * decompositions which replace a character by a single
 628  * other character. In the case of singletons *@b will
 629  * be set to zero.
 630  *
 631  * If @ch is not decomposable, *@a is set to @ch and *@b
 632  * is set to zero.
 633  *
 634  * Note that the way Unicode decomposition pairs are
 635  * defined, it is guaranteed that @b would not decompose
 636  * further, but @a may itself decompose.  To get the full
 637  * canonical decomposition for @ch, one would need to
 638  * recursively call this function on @a.  Or use
 639  * g_unichar_fully_decompose().
 640  *
 641  * See
 642  * [UAX#15](http://unicode.org/reports/tr15/)
 643  * for details.
 644  *
 645  * Returns: %TRUE if the character could be decomposed
 646  *
 647  * Since: 2.30
 648  */
 649 gboolean
 650 g_unichar_decompose (gunichar  ch,
 651                      gunichar *a,
 652                      gunichar *b)
 653 {
 654   gint start = 0;
 655   gint end = G_N_ELEMENTS (decomp_step_table);
 656
 657   if (decompose_hangul_step (ch, a, b))
 658     return TRUE;
 659
 660   /* TODO use bsearch() */
 661   if (ch >= decomp_step_table[start].ch &&
 662       ch <= decomp_step_table[end - 1].ch)
 663     {
 664       while (TRUE)
 665         {
 666           gint half = (start + end) / 2;
 667           const decomposition_step *p = &(decomp_step_table[half]);
 668           if (ch == p->ch)
 669             {
 670               *a = p->a;
 671               *b = p->b;
 672               return TRUE;
 673             }
 674           else if (half == start)
 675             break;
 676           else if (ch > p->ch)
 677             start = half;
 678           else
 679             end = half;
 680         }
 681     }
 682
 683   *a = ch;
 684   *b = 0;
 685
 686   return FALSE;
 687 }
 688
 689 /**
 690  * g_unichar_compose:
 691  * @a: a Unicode character
 692  * @b: a Unicode character
 693  * @ch: (out) (not optional): return location for the composed character
 694  *
 695  * Performs a single composition step of the
 696  * Unicode canonical composition algorithm.
 697  *
 698  * This function includes algorithmic Hangul Jamo composition,
 699  * but it is not exactly the inverse of g_unichar_decompose().
 700  * No composition can have either of @a or @b equal to zero.
 701  * To be precise, this function composes if and only if
 702  * there exists a Primary Composite P which is canonically
 703  * equivalent to the sequence <@a,@b>.  See the Unicode
 704  * Standard for the definition of Primary Composite.
 705  *
 706  * If @a and @b do not compose a new character, @ch is set to zero.
 707  *
 708  * See
 709  * [UAX#15](http://unicode.org/reports/tr15/)
 710  * for details.
 711  *
 712  * Returns: %TRUE if the characters could be composed
 713  *
 714  * Since: 2.30
 715  */
 716 gboolean
 717 g_unichar_compose (gunichar  a,
 718                    gunichar  b,
 719                    gunichar *ch)
 720 {
 721   if (combine (a, b, ch))
 722     return TRUE;
 723
 724   *ch = 0;
 725   return FALSE;
 726 }
 727
 728 /**
 729  * g_unichar_fully_decompose:
 730  * @ch: a Unicode character.
 731  * @compat: whether perform canonical or compatibility decomposition
 732  * @result: (optional) (out caller-allocates): location to store decomposed result, or %NULL
 733  * @result_len: length of @result
 734  *
 735  * Computes the canonical or compatibility decomposition of a
 736  * Unicode character.  For compatibility decomposition,
 737  * pass %TRUE for @compat; for canonical decomposition
 738  * pass %FALSE for @compat.
 739  *
 740  * The decomposed sequence is placed in @result.  Only up to
 741  * @result_len characters are written into @result.  The length
 742  * of the full decomposition (irrespective of @result_len) is
 743  * returned by the function.  For canonical decomposition,
 744  * currently all decompositions are of length at most 4, but
 745  * this may change in the future (very unlikely though).
 746  * At any rate, Unicode does guarantee that a buffer of length
 747  * 18 is always enough for both compatibility and canonical
 748  * decompositions, so that is the size recommended. This is provided
 749  * as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH.
 750  *
 751  * See
 752  * [UAX#15](http://unicode.org/reports/tr15/)
 753  * for details.
 754  *
 755  * Returns: the length of the full decomposition.
 756  *
 757  * Since: 2.30
 758  **/
 759 gsize
 760 g_unichar_fully_decompose (gunichar  ch,
 761                            gboolean  compat,
 762                            gunichar *result,
 763                            gsize     result_len)
 764 {
 765   const gchar *decomp;
 766   const gchar *p;
 767
 768   /* Hangul syllable */
 769   if (ch >= SBase && ch < SBase + SCount)
 770     {
 771       gsize len, i;
 772       gunichar buffer[3];
 773       decompose_hangul (ch, result ? buffer : NULL, &len);
 774       if (result)
 775         for (i = 0; i < len && i < result_len; i++)
 776           result[i] = buffer[i];
 777       return len;
 778     }
 779   else if ((decomp = find_decomposition (ch, compat)) != NULL)
 780     {
 781       /* Found it.  */
 782       gsize len, i;
 783
 784       len = g_utf8_strlen (decomp, -1);
 785
 786       for (p = decomp, i = 0; i < len && i < result_len; p = g_utf8_next_char (p), i++)
 787         result[i] = g_utf8_get_char (p);
 788
 789       return len;
 790     }
 791
 792   /* Does not decompose */
 793   if (result && result_len >= 1)
 794     *result = ch;
 795   return 1;
 796 }