1 /* decomp.c - Character decomposition.
3 * Copyright (C) 1999, 2000 Tom Tromey
4 * Copyright 2000 Red Hat, Inc.
6 * The Gnome Library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public License as
8 * published by the Free Software Foundation; either version 2 of the
9 * License, or (at your option) any later version.
11 * The Gnome Library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with the Gnome Library; see the file COPYING.LIB. If not,
18 * write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
24 * @Title: Unicode Manipulation
25 * @Short_description: functions operating on Unicode characters and
27 * @See_also: g_locale_to_utf8(), g_locale_from_utf8()
29 * This section describes a number of functions for dealing with
30 * Unicode characters and strings. There are analogues of the
31 * traditional <filename>ctype.h</filename> character classification
32 * and case conversion functions, UTF-8 analogues of some string utility
33 * functions, functions to perform normalization, case conversion and
34 * collation on UTF-8 strings and finally functions to convert between
35 * the UTF-8, UTF-16 and UCS-4 encodings of Unicode.
37 * The implementations of the Unicode functions in GLib are based
38 * on the Unicode Character Data tables, which are available from
39 * <ulink url="http://www.unicode.org/">www.unicode.org</ulink>.
40 * GLib 2.8 supports Unicode 4.0, GLib 2.10 supports Unicode 4.1,
41 * GLib 2.12 supports Unicode 5.0, GLib 2.16.3 supports Unicode 5.1,
42 * GLib 2.30 supports Unicode 6.0.
50 #include "gunidecomp.h"
53 #include "gunicodeprivate.h"
56 #define CC_PART1(Page, Char) \
57 ((combining_class_table_part1[Page] >= G_UNICODE_MAX_TABLE_INDEX) \
58 ? (combining_class_table_part1[Page] - G_UNICODE_MAX_TABLE_INDEX) \
59 : (cclass_data[combining_class_table_part1[Page]][Char]))
61 #define CC_PART2(Page, Char) \
62 ((combining_class_table_part2[Page] >= G_UNICODE_MAX_TABLE_INDEX) \
63 ? (combining_class_table_part2[Page] - G_UNICODE_MAX_TABLE_INDEX) \
64 : (cclass_data[combining_class_table_part2[Page]][Char]))
66 #define COMBINING_CLASS(Char) \
67 (((Char) <= G_UNICODE_LAST_CHAR_PART1) \
68 ? CC_PART1 ((Char) >> 8, (Char) & 0xff) \
69 : (((Char) >= 0xe0000 && (Char) <= G_UNICODE_LAST_CHAR) \
70 ? CC_PART2 (((Char) - 0xe0000) >> 8, (Char) & 0xff) \
74 * g_unichar_combining_class:
75 * @uc: a Unicode character
77 * Determines the canonical combining class of a Unicode character.
79 * Return value: the combining class of the character
84 g_unichar_combining_class (gunichar uc
)
86 return COMBINING_CLASS (uc
);
89 /* constants for hangul syllable [de]composition */
97 #define NCount (VCount * TCount)
98 #define SCount (LCount * NCount)
101 * g_unicode_canonical_ordering:
102 * @string: a UCS-4 encoded string.
103 * @len: the maximum length of @string to use.
105 * Computes the canonical ordering of a string in-place.
106 * This rearranges decomposed characters in the string
107 * according to their combining classes. See the Unicode
108 * manual for more information.
111 g_unicode_canonical_ordering (gunichar
*string
,
121 last
= COMBINING_CLASS (string
[0]);
122 for (i
= 0; i
< len
- 1; ++i
)
124 int next
= COMBINING_CLASS (string
[i
+ 1]);
125 if (next
!= 0 && last
> next
)
128 /* Percolate item leftward through string. */
129 for (j
= i
+ 1; j
> 0; --j
)
132 if (COMBINING_CLASS (string
[j
- 1]) <= next
)
135 string
[j
] = string
[j
- 1];
139 /* We're re-entering the loop looking at the old
148 /* http://www.unicode.org/unicode/reports/tr15/#Hangul
149 * r should be null or have sufficient space. Calling with r == NULL will
150 * only calculate the result_len; however, a buffer with space for three
151 * characters will always be big enough. */
153 decompose_hangul (gunichar s
,
157 gint SIndex
= s
- SBase
;
158 gint TIndex
= SIndex
% TCount
;
162 r
[0] = LBase
+ SIndex
/ NCount
;
163 r
[1] = VBase
+ (SIndex
% NCount
) / TCount
;
169 r
[2] = TBase
+ TIndex
;
176 /* returns a pointer to a null-terminated UTF-8 string */
178 find_decomposition (gunichar ch
,
182 int end
= G_N_ELEMENTS (decomp_table
);
184 if (ch
>= decomp_table
[start
].ch
&&
185 ch
<= decomp_table
[end
- 1].ch
)
189 int half
= (start
+ end
) / 2;
190 if (ch
== decomp_table
[half
].ch
)
196 offset
= decomp_table
[half
].compat_offset
;
197 if (offset
== G_UNICODE_NOT_PRESENT_OFFSET
)
198 offset
= decomp_table
[half
].canon_offset
;
202 offset
= decomp_table
[half
].canon_offset
;
203 if (offset
== G_UNICODE_NOT_PRESENT_OFFSET
)
207 return &(decomp_expansion_string
[offset
]);
209 else if (half
== start
)
211 else if (ch
> decomp_table
[half
].ch
)
222 * g_unicode_canonical_decomposition:
223 * @ch: a Unicode character.
224 * @result_len: location to store the length of the return value.
226 * Computes the canonical decomposition of a Unicode character.
228 * Return value: a newly allocated string of Unicode characters.
229 * @result_len is set to the resulting length of the string.
231 * Deprecated: 2.30: Use the more flexible g_unichar_fully_decompose()
235 g_unicode_canonical_decomposition (gunichar ch
,
242 /* Hangul syllable */
243 if (ch
>= SBase
&& ch
< SBase
+ SCount
)
245 decompose_hangul (ch
, NULL
, result_len
);
246 r
= g_malloc (*result_len
* sizeof (gunichar
));
247 decompose_hangul (ch
, r
, result_len
);
249 else if ((decomp
= find_decomposition (ch
, FALSE
)) != NULL
)
254 *result_len
= g_utf8_strlen (decomp
, -1);
255 r
= g_malloc (*result_len
* sizeof (gunichar
));
257 for (p
= decomp
, i
= 0; *p
!= '\0'; p
= g_utf8_next_char (p
), i
++)
258 r
[i
] = g_utf8_get_char (p
);
262 /* Not in our table. */
263 r
= g_malloc (sizeof (gunichar
));
271 /* L,V => LV and LV,T => LVT */
273 combine_hangul (gunichar a
,
277 gint LIndex
= a
- LBase
;
278 gint SIndex
= a
- SBase
;
280 gint VIndex
= b
- VBase
;
281 gint TIndex
= b
- TBase
;
283 if (0 <= LIndex
&& LIndex
< LCount
284 && 0 <= VIndex
&& VIndex
< VCount
)
286 *result
= SBase
+ (LIndex
* VCount
+ VIndex
) * TCount
;
289 else if (0 <= SIndex
&& SIndex
< SCount
&& (SIndex
% TCount
) == 0
290 && 0 < TIndex
&& TIndex
< TCount
)
292 *result
= a
+ TIndex
;
299 #define CI(Page, Char) \
300 ((compose_table[Page] >= G_UNICODE_MAX_TABLE_INDEX) \
301 ? (compose_table[Page] - G_UNICODE_MAX_TABLE_INDEX) \
302 : (compose_data[compose_table[Page]][Char]))
304 #define COMPOSE_INDEX(Char) \
305 (((Char >> 8) > (COMPOSE_TABLE_LAST)) ? 0 : CI((Char) >> 8, (Char) & 0xff))
312 gushort index_a
, index_b
;
314 if (combine_hangul (a
, b
, result
))
317 index_a
= COMPOSE_INDEX(a
);
319 if (index_a
>= COMPOSE_FIRST_SINGLE_START
&& index_a
< COMPOSE_SECOND_START
)
321 if (b
== compose_first_single
[index_a
- COMPOSE_FIRST_SINGLE_START
][0])
323 *result
= compose_first_single
[index_a
- COMPOSE_FIRST_SINGLE_START
][1];
330 index_b
= COMPOSE_INDEX(b
);
332 if (index_b
>= COMPOSE_SECOND_SINGLE_START
)
334 if (a
== compose_second_single
[index_b
- COMPOSE_SECOND_SINGLE_START
][0])
336 *result
= compose_second_single
[index_b
- COMPOSE_SECOND_SINGLE_START
][1];
343 if (index_a
>= COMPOSE_FIRST_START
&& index_a
< COMPOSE_FIRST_SINGLE_START
&&
344 index_b
>= COMPOSE_SECOND_START
&& index_b
< COMPOSE_SECOND_SINGLE_START
)
346 gunichar res
= compose_array
[index_a
- COMPOSE_FIRST_START
][index_b
- COMPOSE_SECOND_START
];
359 _g_utf8_normalize_wc (const gchar
*str
,
367 gboolean do_compat
= (mode
== G_NORMALIZE_NFKC
||
368 mode
== G_NORMALIZE_NFKD
);
369 gboolean do_compose
= (mode
== G_NORMALIZE_NFC
||
370 mode
== G_NORMALIZE_NFKC
);
374 while ((max_len
< 0 || p
< str
+ max_len
) && *p
)
377 gunichar wc
= g_utf8_get_char (p
);
379 if (wc
>= SBase
&& wc
< SBase
+ SCount
)
382 decompose_hangul (wc
, NULL
, &result_len
);
387 decomp
= find_decomposition (wc
, do_compat
);
390 n_wc
+= g_utf8_strlen (decomp
, -1);
395 p
= g_utf8_next_char (p
);
398 wc_buffer
= g_new (gunichar
, n_wc
+ 1);
403 while ((max_len
< 0 || p
< str
+ max_len
) && *p
)
405 gunichar wc
= g_utf8_get_char (p
);
408 gsize old_n_wc
= n_wc
;
410 if (wc
>= SBase
&& wc
< SBase
+ SCount
)
413 decompose_hangul (wc
, wc_buffer
+ n_wc
, &result_len
);
418 decomp
= find_decomposition (wc
, do_compat
);
423 for (pd
= decomp
; *pd
!= '\0'; pd
= g_utf8_next_char (pd
))
424 wc_buffer
[n_wc
++] = g_utf8_get_char (pd
);
427 wc_buffer
[n_wc
++] = wc
;
432 cc
= COMBINING_CLASS (wc_buffer
[old_n_wc
]);
436 g_unicode_canonical_ordering (wc_buffer
+ last_start
, n_wc
- last_start
);
437 last_start
= old_n_wc
;
441 p
= g_utf8_next_char (p
);
446 g_unicode_canonical_ordering (wc_buffer
+ last_start
, n_wc
- last_start
);
452 /* All decomposed and reordered */
454 if (do_compose
&& n_wc
> 0)
460 for (i
= 0; i
< n_wc
; i
++)
462 int cc
= COMBINING_CLASS (wc_buffer
[i
]);
465 (last_cc
== 0 || last_cc
< cc
) &&
466 combine (wc_buffer
[last_start
], wc_buffer
[i
],
467 &wc_buffer
[last_start
]))
469 for (j
= i
+ 1; j
< n_wc
; j
++)
470 wc_buffer
[j
-1] = wc_buffer
[j
];
477 last_cc
= COMBINING_CLASS (wc_buffer
[i
-1]);
496 * @str: a UTF-8 encoded string.
497 * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
498 * @mode: the type of normalization to perform.
500 * Converts a string into canonical form, standardizing
501 * such issues as whether a character with an accent
502 * is represented as a base character and combining
503 * accent or as a single precomposed character. The
504 * string has to be valid UTF-8, otherwise %NULL is
505 * returned. You should generally call g_utf8_normalize()
506 * before comparing two Unicode strings.
508 * The normalization mode %G_NORMALIZE_DEFAULT only
509 * standardizes differences that do not affect the
510 * text content, such as the above-mentioned accent
511 * representation. %G_NORMALIZE_ALL also standardizes
512 * the "compatibility" characters in Unicode, such
513 * as SUPERSCRIPT THREE to the standard forms
514 * (in this case DIGIT THREE). Formatting information
515 * may be lost but for most text operations such
516 * characters should be considered the same.
518 * %G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE
519 * are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_ALL,
520 * but returned a result with composed forms rather
521 * than a maximally decomposed form. This is often
522 * useful if you intend to convert the string to
523 * a legacy encoding or pass it to a system with
524 * less capable Unicode handling.
526 * Return value: a newly allocated string, that is the
527 * normalized form of @str, or %NULL if @str is not
531 g_utf8_normalize (const gchar
*str
,
535 gunichar
*result_wc
= _g_utf8_normalize_wc (str
, len
, mode
);
538 result
= g_ucs4_to_utf8 (result_wc
, -1, NULL
, NULL
, NULL
);
545 decompose_hangul_step (gunichar ch
,
551 if (ch
< SBase
|| ch
>= SBase
+ SCount
)
552 return FALSE
; /* not a hangul syllable */
555 TIndex
= SIndex
% TCount
;
559 /* split LVT -> LV,T */
565 /* split LV -> L,V */
566 *a
= LBase
+ SIndex
/ NCount
;
567 *b
= VBase
+ (SIndex
% NCount
) / TCount
;
574 * g_unichar_decompose:
575 * @ch: a Unicode character
576 * @a: return location for the first component of @ch
577 * @b: return location for the second component of @ch
579 * Performs a single decomposition step of the
580 * Unicode canonical decomposition algorithm.
582 * This function does not include compatibility
583 * decompositions. It does, however, include algorithmic
584 * Hangul Jamo decomposition, as well as 'singleton'
585 * decompositions which replace a character by a single
586 * other character. In the case of singletons *@b will
589 * If @ch is not decomposable, *@a is set to @ch and *@b
592 * Note that the way Unicode decomposition pairs are
593 * defined, it is guaranteed that @b would not decompose
594 * further, but @a may itself decompose. To get the full
595 * canonical decomposition for @ch, one would need to
596 * recursively call this function on @a. Or use
597 * g_unichar_fully_decompose().
599 * See <ulink url="http://unicode.org/reports/tr15/">UAX#15</ulink>
602 * Returns: %TRUE if the character could be decomposed
607 g_unichar_decompose (gunichar ch
,
612 gint end
= G_N_ELEMENTS (decomp_step_table
);
614 if (decompose_hangul_step (ch
, a
, b
))
617 /* TODO use bsearch() */
618 if (ch
>= decomp_step_table
[start
].ch
&&
619 ch
<= decomp_step_table
[end
- 1].ch
)
623 gint half
= (start
+ end
) / 2;
624 const decomposition_step
*p
= &(decomp_step_table
[half
]);
631 else if (half
== start
)
648 * @a: a Unicode character
649 * @b: a Unicode character
650 * @ch: return location for the composed character
652 * Performs a single composition step of the
653 * Unicode canonical composition algorithm.
655 * This function includes algorithmic Hangul Jamo composition,
656 * but it is not exactly the inverse of g_unichar_decompose().
657 * No composition can have either of @a or @b equal to zero.
658 * To be precise, this function composes if and only if
659 * there exists a Primary Composite P which is canonically
660 * equivalent to the sequence <@a,@b>. See the Unicode
661 * Standard for the definition of Primary Composite.
663 * If @a and @b do not compose a new character, @ch is set to zero.
665 * See <ulink url="http://unicode.org/reports/tr15/">UAX#15</ulink>
668 * Returns: %TRUE if the characters could be composed
673 g_unichar_compose (gunichar a
,
677 if (combine (a
, b
, ch
))
685 * g_unichar_fully_decompose:
686 * @ch: a Unicode character.
687 * @compat: whether perform canonical or compatibility decomposition
688 * @result: (allow-none): location to store decomposed result, or %NULL
689 * @result_len: length of @result
691 * Computes the canonical or compatibility decomposition of a
692 * Unicode character. For compatibility decomposition,
693 * pass %TRUE for @compat; for canonical decomposition
694 * pass %FALSE for @compat.
696 * The decomposed sequence is placed in @result. Only up to
697 * @result_len characters are written into @result. The length
698 * of the full decomposition (irrespective of @result_len) is
699 * returned by the function. For canonical decomposition,
700 * currently all decompositions are of length at most 4, but
701 * this may change in the future (very unlikely though).
702 * At any rate, Unicode does guarantee that a buffer of length
703 * 18 is always enough for both compatibility and canonical
704 * decompositions, so that is the size recommended. This is provided
705 * as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH.
707 * See <ulink url="http://unicode.org/reports/tr15/">UAX#15</ulink>
710 * Return value: the length of the full decomposition.
715 g_unichar_fully_decompose (gunichar ch
,
723 /* Hangul syllable */
724 if (ch
>= SBase
&& ch
< SBase
+ SCount
)
728 decompose_hangul (ch
, result
? buffer
: NULL
, &len
);
730 for (i
= 0; i
< len
&& i
< result_len
; i
++)
731 result
[i
] = buffer
[i
];
734 else if ((decomp
= find_decomposition (ch
, compat
)) != NULL
)
739 len
= g_utf8_strlen (decomp
, -1);
741 for (p
= decomp
, i
= 0; i
< len
&& i
< result_len
; p
= g_utf8_next_char (p
), i
++)
742 result
[i
] = g_utf8_get_char (p
);
747 /* Does not decompose */
748 if (result
&& result_len
>= 1)