1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 functions operating on Unicode characters and UTF-8 strings
7 <!-- ##### SECTION Long_Description ##### -->
9 This section describes a number of functions for dealing with
10 Unicode characters and strings. There are analogues of the
11 traditional <filename>ctype.h</filename> character classification
12 and case conversion functions, UTF-8 analogues of some string utility
13 functions, functions to perform normalization, case conversion and
14 collation on UTF-8 strings and finally functions to convert between
15 the UTF-8, UTF-16 and UCS-4 encodings of Unicode.
19 The implementations of the Unicode functions in GLib are based
20 on the Unicode Character Data tables, which are available from
21 <ulink url="http://www.unicode.org/">www.unicode.org</ulink>.
22 GLib 2.8 supports Unicode 4.0, GLib 2.10 supports Unicode 4.1,
23 GLib 2.12 supports Unicode 5.0, GLib 2.16.3 supports Unicode 5.1.
26 <!-- ##### SECTION See_Also ##### -->
31 <term>g_locale_to_utf8(), g_locale_from_utf8()</term>
33 Convenience functions for converting between UTF-8 and the locale encoding.
40 <!-- ##### SECTION Stability_Level ##### -->
43 <!-- ##### TYPEDEF gunichar ##### -->
45 A type which can hold any UTF-32 or UCS-4 character code, also known
46 as a Unicode code point.
49 If you want to produce the UTF-8 representation of a #gunichar,
50 use g_ucs4_to_utf8(). See also g_utf8_to_ucs4() for the reverse process.
53 To print/scan values of this type as integer, use
54 %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
57 The notation to express a Unicode code point in running text is as a
58 hexadecimal number with four to six digits and uppercase letters, prefixed
59 by the string "U+". Leading zeros are omitted, unless the code point would
60 have fewer than four hexadecimal digits.
61 For example, "U+0041 LATIN CAPITAL LETTER A".
62 To print a code point in the U+-notation, use the format string
63 "U+%04"G_GINT32_FORMAT"X".
64 To scan, use the format string "U+%06"G_GINT32_FORMAT"X".
68 sscanf ("U+0041", "U+%06"G_GINT32_FORMAT"X", &c)
69 g_print ("Read U+%04"G_GINT32_FORMAT"X", c);
75 <!-- ##### TYPEDEF gunichar2 ##### -->
77 A type which can hold any UTF-16 code
78 point<footnote id="utf16_surrogate_pairs">UTF-16 also has so called
79 <firstterm>surrogate pairs</firstterm> to encode characters beyond the
80 BMP as pairs of 16bit numbers. Surrogate pairs cannot be stored in a
81 single gunichar2 field, but all GLib functions accepting gunichar2 arrays
82 will correctly interpret surrogate pairs.</footnote>.
85 To print/scan values of this type to/from text you need to convert
86 to/from UTF-8, using g_utf16_to_utf8()/g_utf8_to_utf16().
89 To print/scan values of this type as integer, use
90 %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
94 <!-- ##### FUNCTION g_unichar_validate ##### -->
103 <!-- ##### FUNCTION g_unichar_isalnum ##### -->
112 <!-- ##### FUNCTION g_unichar_isalpha ##### -->
121 <!-- ##### FUNCTION g_unichar_iscntrl ##### -->
130 <!-- ##### FUNCTION g_unichar_isdefined ##### -->
139 <!-- ##### FUNCTION g_unichar_isdigit ##### -->
148 <!-- ##### FUNCTION g_unichar_isgraph ##### -->
157 <!-- ##### FUNCTION g_unichar_islower ##### -->
166 <!-- ##### FUNCTION g_unichar_ismark ##### -->
175 <!-- ##### FUNCTION g_unichar_isprint ##### -->
184 <!-- ##### FUNCTION g_unichar_ispunct ##### -->
193 <!-- ##### FUNCTION g_unichar_isspace ##### -->
202 <!-- ##### FUNCTION g_unichar_istitle ##### -->
211 <!-- ##### FUNCTION g_unichar_isupper ##### -->
220 <!-- ##### FUNCTION g_unichar_isxdigit ##### -->
229 <!-- ##### FUNCTION g_unichar_iswide ##### -->
238 <!-- ##### FUNCTION g_unichar_iswide_cjk ##### -->
247 <!-- ##### FUNCTION g_unichar_iszerowidth ##### -->
256 <!-- ##### FUNCTION g_unichar_toupper ##### -->
265 <!-- ##### FUNCTION g_unichar_tolower ##### -->
274 <!-- ##### FUNCTION g_unichar_totitle ##### -->
283 <!-- ##### FUNCTION g_unichar_digit_value ##### -->
292 <!-- ##### FUNCTION g_unichar_xdigit_value ##### -->
301 <!-- ##### ENUM GUnicodeType ##### -->
303 These are the possible character classifications from the
304 Unicode specification.
305 See <ulink url="http://www.unicode.org/Public/UNIDATA/UnicodeData.html"
306 >http://www.unicode.org/Public/UNIDATA/UnicodeData.html</ulink>.
309 @G_UNICODE_CONTROL: General category "Other, Control" (Cc)
310 @G_UNICODE_FORMAT: General category "Other, Format" (Cf)
311 @G_UNICODE_UNASSIGNED: General category "Other, Not Assigned" (Cn)
312 @G_UNICODE_PRIVATE_USE: General category "Other, Private Use" (Co)
313 @G_UNICODE_SURROGATE: General category "Other, Surrogate" (Cs)
314 @G_UNICODE_LOWERCASE_LETTER: General category "Letter, Lowercase" (Ll)
315 @G_UNICODE_MODIFIER_LETTER: General category "Letter, Modifier" (Lm)
316 @G_UNICODE_OTHER_LETTER: General category "Letter, Other" (Lo)
317 @G_UNICODE_TITLECASE_LETTER: General category "Letter, Titlecase" (Lt)
318 @G_UNICODE_UPPERCASE_LETTER: General category "Letter, Uppercase" (Lu)
319 @G_UNICODE_COMBINING_MARK: General category "Mark, Spacing Combining" (Mc)
320 @G_UNICODE_ENCLOSING_MARK: General category "Mark, Enclosing" (Me)
321 @G_UNICODE_NON_SPACING_MARK: General category "Mark, Nonspacing" (Mn)
322 @G_UNICODE_DECIMAL_NUMBER: General category "Number, Decimal Digit" (Nd)
323 @G_UNICODE_LETTER_NUMBER: General category "Number, Letter" (Nl)
324 @G_UNICODE_OTHER_NUMBER: General category "Number, Other" (No)
325 @G_UNICODE_CONNECT_PUNCTUATION: General category "Punctuation, Connector" (Pc)
326 @G_UNICODE_DASH_PUNCTUATION: General category "Punctuation, Dash" (Pd)
327 @G_UNICODE_CLOSE_PUNCTUATION: General category "Punctuation, Close" (Pe)
328 @G_UNICODE_FINAL_PUNCTUATION: General category "Punctuation, Final quote" (Pf)
329 @G_UNICODE_INITIAL_PUNCTUATION: General category "Punctuation, Initial quote" (Pi)
330 @G_UNICODE_OTHER_PUNCTUATION: General category "Punctuation, Other" (Po)
331 @G_UNICODE_OPEN_PUNCTUATION: General category "Punctuation, Open" (Ps)
332 @G_UNICODE_CURRENCY_SYMBOL: General category "Symbol, Currency" (Sc)
333 @G_UNICODE_MODIFIER_SYMBOL: General category "Symbol, Modifier" (Sk)
334 @G_UNICODE_MATH_SYMBOL: General category "Symbol, Math" (Sm)
335 @G_UNICODE_OTHER_SYMBOL: General category "Symbol, Other" (So)
336 @G_UNICODE_LINE_SEPARATOR: General category "Separator, Line" (Zl)
337 @G_UNICODE_PARAGRAPH_SEPARATOR: General category "Separator, Paragraph" (Zp)
338 @G_UNICODE_SPACE_SEPARATOR: General category "Separator, Space" (Zs)
340 <!-- ##### FUNCTION g_unichar_type ##### -->
349 <!-- ##### ENUM GUnicodeBreakType ##### -->
351 These are the possible line break classifications.
352 The five Hangul types were added in Unicode 4.1, so, has been
353 introduced in GLib 2.10. Note that new types may be added in the future.
354 Applications should be ready to handle unknown values.
355 They may be regarded as %G_UNICODE_BREAK_UNKNOWN.
356 See <ulink url="http://www.unicode.org/unicode/reports/tr14/"
357 >http://www.unicode.org/unicode/reports/tr14/</ulink>.
360 @G_UNICODE_BREAK_MANDATORY: Mandatory Break (BK)
361 @G_UNICODE_BREAK_CARRIAGE_RETURN: Carriage Return (CR)
362 @G_UNICODE_BREAK_LINE_FEED: Line Feed (LF)
363 @G_UNICODE_BREAK_COMBINING_MARK: Attached Characters and Combining Marks (CM)
364 @G_UNICODE_BREAK_SURROGATE: Surrogates (SG)
365 @G_UNICODE_BREAK_ZERO_WIDTH_SPACE: Zero Width Space (ZW)
366 @G_UNICODE_BREAK_INSEPARABLE: Inseparable (IN)
367 @G_UNICODE_BREAK_NON_BREAKING_GLUE: Non-breaking ("Glue") (GL)
368 @G_UNICODE_BREAK_CONTINGENT: Contingent Break Opportunity (CB)
369 @G_UNICODE_BREAK_SPACE: Space (SP)
370 @G_UNICODE_BREAK_AFTER: Break Opportunity After (BA)
371 @G_UNICODE_BREAK_BEFORE: Break Opportunity Before (BB)
372 @G_UNICODE_BREAK_BEFORE_AND_AFTER: Break Opportunity Before and After (B2)
373 @G_UNICODE_BREAK_HYPHEN: Hyphen (HY)
374 @G_UNICODE_BREAK_NON_STARTER: Nonstarter (NS)
375 @G_UNICODE_BREAK_OPEN_PUNCTUATION: Opening Punctuation (OP)
376 @G_UNICODE_BREAK_CLOSE_PUNCTUATION: Closing Punctuation (CL)
377 @G_UNICODE_BREAK_QUOTATION: Ambiguous Quotation (QU)
378 @G_UNICODE_BREAK_EXCLAMATION: Exclamation/Interrogation (EX)
379 @G_UNICODE_BREAK_IDEOGRAPHIC: Ideographic (ID)
380 @G_UNICODE_BREAK_NUMERIC: Numeric (NU)
381 @G_UNICODE_BREAK_INFIX_SEPARATOR: Infix Separator (Numeric) (IS)
382 @G_UNICODE_BREAK_SYMBOL: Symbols Allowing Break After (SY)
383 @G_UNICODE_BREAK_ALPHABETIC: Ordinary Alphabetic and Symbol Characters (AL)
384 @G_UNICODE_BREAK_PREFIX: Prefix (Numeric) (PR)
385 @G_UNICODE_BREAK_POSTFIX: Postfix (Numeric) (PO)
386 @G_UNICODE_BREAK_COMPLEX_CONTEXT: Complex Content Dependent (South East Asian) (SA)
387 @G_UNICODE_BREAK_AMBIGUOUS: Ambiguous (Alphabetic or Ideographic) (AI)
388 @G_UNICODE_BREAK_UNKNOWN: Unknown (XX)
389 @G_UNICODE_BREAK_NEXT_LINE: Next Line (NL)
390 @G_UNICODE_BREAK_WORD_JOINER: Word Joiner (WJ)
391 @G_UNICODE_BREAK_HANGUL_L_JAMO: Hangul L Jamo (JL)
392 @G_UNICODE_BREAK_HANGUL_V_JAMO: Hangul V Jamo (JV)
393 @G_UNICODE_BREAK_HANGUL_T_JAMO: Hangul T Jamo (JT)
394 @G_UNICODE_BREAK_HANGUL_LV_SYLLABLE: Hangul LV Syllable (H2)
395 @G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE: Hangul LVT Syllable (H3)
397 <!-- ##### FUNCTION g_unichar_break_type ##### -->
406 <!-- ##### FUNCTION g_unichar_combining_class ##### -->
415 <!-- ##### FUNCTION g_unicode_canonical_ordering ##### -->
424 <!-- ##### FUNCTION g_unicode_canonical_decomposition ##### -->
434 <!-- ##### FUNCTION g_unichar_get_mirror_char ##### -->
444 <!-- ##### ENUM GUnicodeScript ##### -->
446 The #GUnicodeScript enumeration identifies different writing
447 systems. The values correspond to the names as defined in the
448 Unicode standard. The enumeration has been added in GLib 2.14,
449 and is interchangeable with #PangoScript.
450 Note that new types may be added in the future. Applications
451 should be ready to handle unknown values.
453 url="http://www.unicode.org/reports/tr24/">Unicode Standard Annex
454 #24: Script names</ulink>.
457 @G_UNICODE_SCRIPT_INVALID_CODE: a value never returned from g_unichar_get_script()
458 @G_UNICODE_SCRIPT_COMMON: a character used by multiple different scripts
459 @G_UNICODE_SCRIPT_INHERITED: a mark glyph that takes its script from the
460 base glyph to which it is attached
461 @G_UNICODE_SCRIPT_ARABIC: Arabic
462 @G_UNICODE_SCRIPT_ARMENIAN: Armenian
463 @G_UNICODE_SCRIPT_BENGALI: Bengali
464 @G_UNICODE_SCRIPT_BOPOMOFO: Bopomofo
465 @G_UNICODE_SCRIPT_CHEROKEE: Cherokee
466 @G_UNICODE_SCRIPT_COPTIC: Coptic
467 @G_UNICODE_SCRIPT_CYRILLIC: Cyrillic
468 @G_UNICODE_SCRIPT_DESERET: Deseret
469 @G_UNICODE_SCRIPT_DEVANAGARI: Devanagari
470 @G_UNICODE_SCRIPT_ETHIOPIC: Ethiopic
471 @G_UNICODE_SCRIPT_GEORGIAN: Georgian
472 @G_UNICODE_SCRIPT_GOTHIC: Gothic
473 @G_UNICODE_SCRIPT_GREEK: Greek
474 @G_UNICODE_SCRIPT_GUJARATI: Gujarati
475 @G_UNICODE_SCRIPT_GURMUKHI: Gurmukhi
476 @G_UNICODE_SCRIPT_HAN: Han
477 @G_UNICODE_SCRIPT_HANGUL: Hangul
478 @G_UNICODE_SCRIPT_HEBREW: Hebrew
479 @G_UNICODE_SCRIPT_HIRAGANA: Hiragana
480 @G_UNICODE_SCRIPT_KANNADA: Kannada
481 @G_UNICODE_SCRIPT_KATAKANA: Katakana
482 @G_UNICODE_SCRIPT_KHMER: Khmer
483 @G_UNICODE_SCRIPT_LAO: Lao
484 @G_UNICODE_SCRIPT_LATIN: Latin
485 @G_UNICODE_SCRIPT_MALAYALAM: Malayalam
486 @G_UNICODE_SCRIPT_MONGOLIAN: Mongolian
487 @G_UNICODE_SCRIPT_MYANMAR: Myanmar
488 @G_UNICODE_SCRIPT_OGHAM: Ogham
489 @G_UNICODE_SCRIPT_OLD_ITALIC: Old Italic
490 @G_UNICODE_SCRIPT_ORIYA: Oriya
491 @G_UNICODE_SCRIPT_RUNIC: Runic
492 @G_UNICODE_SCRIPT_SINHALA: Sinhala
493 @G_UNICODE_SCRIPT_SYRIAC: Syriac
494 @G_UNICODE_SCRIPT_TAMIL: Tamil
495 @G_UNICODE_SCRIPT_TELUGU: Telugu
496 @G_UNICODE_SCRIPT_THAANA: Thaana
497 @G_UNICODE_SCRIPT_THAI: Thai
498 @G_UNICODE_SCRIPT_TIBETAN: Tibetan
499 @G_UNICODE_SCRIPT_CANADIAN_ABORIGINAL:
501 @G_UNICODE_SCRIPT_YI: Yi
502 @G_UNICODE_SCRIPT_TAGALOG: Tagalog
503 @G_UNICODE_SCRIPT_HANUNOO: Hanunoo
504 @G_UNICODE_SCRIPT_BUHID: Buhid
505 @G_UNICODE_SCRIPT_TAGBANWA: Tagbanwa
506 @G_UNICODE_SCRIPT_BRAILLE: Braille
507 @G_UNICODE_SCRIPT_CYPRIOT: Cypriot
508 @G_UNICODE_SCRIPT_LIMBU: Limbu
509 @G_UNICODE_SCRIPT_OSMANYA: Osmanya
510 @G_UNICODE_SCRIPT_SHAVIAN: Shavian
511 @G_UNICODE_SCRIPT_LINEAR_B: Linear B
512 @G_UNICODE_SCRIPT_TAI_LE: Tai Le
513 @G_UNICODE_SCRIPT_UGARITIC: Ugaritic
514 @G_UNICODE_SCRIPT_NEW_TAI_LUE: New Tai Lue
515 @G_UNICODE_SCRIPT_BUGINESE: Buginese
516 @G_UNICODE_SCRIPT_GLAGOLITIC: Glagolitic
517 @G_UNICODE_SCRIPT_TIFINAGH: Tifinagh
518 @G_UNICODE_SCRIPT_SYLOTI_NAGRI: Syloti Nagri
519 @G_UNICODE_SCRIPT_OLD_PERSIAN: Old Persian
520 @G_UNICODE_SCRIPT_KHAROSHTHI: Kharoshthi
521 @G_UNICODE_SCRIPT_UNKNOWN: an unassigned code point
522 @G_UNICODE_SCRIPT_BALINESE: Balinese
523 @G_UNICODE_SCRIPT_CUNEIFORM: Cuneiform
524 @G_UNICODE_SCRIPT_PHOENICIAN: Phoenician
525 @G_UNICODE_SCRIPT_PHAGS_PA: Phags-pa
526 @G_UNICODE_SCRIPT_NKO: N'Ko
527 @G_UNICODE_SCRIPT_KAYAH_LI: Kayah Li. Since 2.16.3
528 @G_UNICODE_SCRIPT_LEPCHA: Lepcha. Since 2.16.3
529 @G_UNICODE_SCRIPT_REJANG: Rejang. Since 2.16.3
530 @G_UNICODE_SCRIPT_SUNDANESE: Sundanese. Since 2.16.3
531 @G_UNICODE_SCRIPT_SAURASHTRA: Saurashtra. Since 2.16.3
532 @G_UNICODE_SCRIPT_CHAM: Cham. Since 2.16.3
533 @G_UNICODE_SCRIPT_OL_CHIKI: Ol Chiki. Since 2.16.3
534 @G_UNICODE_SCRIPT_VAI: Vai. Since 2.16.3
535 @G_UNICODE_SCRIPT_CARIAN: Carian. Since 2.16.3
536 @G_UNICODE_SCRIPT_LYCIAN: Lycian. Since 2.16.3
537 @G_UNICODE_SCRIPT_LYDIAN: Lydian. Since 2.16.3
539 <!-- ##### FUNCTION g_unichar_get_script ##### -->
548 <!-- ##### MACRO g_utf8_next_char ##### -->
550 Skips to the next character in a UTF-8 string. The string must be
551 valid; this macro is as fast as possible, and has no error-checking.
552 You would use this macro to iterate over a string character by
553 character. The macro returns the start of the next UTF-8 character.
554 Before using this macro, use g_utf8_validate() to validate strings
555 that may contain invalid UTF-8.
558 @p: Pointer to the start of a valid UTF-8 character.
561 <!-- ##### FUNCTION g_utf8_get_char ##### -->
570 <!-- ##### FUNCTION g_utf8_get_char_validated ##### -->
580 <!-- ##### FUNCTION g_utf8_offset_to_pointer ##### -->
590 <!-- ##### FUNCTION g_utf8_pointer_to_offset ##### -->
600 <!-- ##### FUNCTION g_utf8_prev_char ##### -->
609 <!-- ##### FUNCTION g_utf8_find_next_char ##### -->
619 <!-- ##### FUNCTION g_utf8_find_prev_char ##### -->
629 <!-- ##### FUNCTION g_utf8_strlen ##### -->
639 <!-- ##### FUNCTION g_utf8_strncpy ##### -->
650 <!-- ##### FUNCTION g_utf8_strchr ##### -->
661 <!-- ##### FUNCTION g_utf8_strrchr ##### -->
672 <!-- ##### FUNCTION g_utf8_strreverse ##### -->
682 <!-- ##### FUNCTION g_utf8_validate ##### -->
693 <!-- ##### FUNCTION g_utf8_strup ##### -->
703 <!-- ##### FUNCTION g_utf8_strdown ##### -->
713 <!-- ##### FUNCTION g_utf8_casefold ##### -->
723 <!-- ##### FUNCTION g_utf8_normalize ##### -->
734 <!-- ##### ENUM GNormalizeMode ##### -->
736 Defines how a Unicode string is transformed in a canonical
737 form, standardizing such issues as whether a character with an accent is
738 represented as a base character and combining accent or as a single precomposed
739 character. Unicode strings should generally be normalized before comparing them.
742 @G_NORMALIZE_DEFAULT: standardize differences that do not affect the
743 text content, such as the above-mentioned accent representation.
744 @G_NORMALIZE_NFD: another name for %G_NORMALIZE_DEFAULT.
745 @G_NORMALIZE_DEFAULT_COMPOSE: like %G_NORMALIZE_DEFAULT, but with composed
746 forms rather than a maximally decomposed form.
747 @G_NORMALIZE_NFC: another name for %G_NORMALIZE_DEFAULT_COMPOSE.
748 @G_NORMALIZE_ALL: beyond %G_NORMALIZE_DEFAULT also standardize the
749 "compatibility" characters in Unicode, such as SUPERSCRIPT THREE to the
750 standard forms (in this case DIGIT THREE). Formatting information may be
751 lost but for most text operations such characters should be considered the
753 @G_NORMALIZE_NFKD: another name for %G_NORMALIZE_ALL.
754 @G_NORMALIZE_ALL_COMPOSE: like %G_NORMALIZE_ALL, but with composed
755 forms rather than a maximally decomposed form.
756 @G_NORMALIZE_NFKC: another name for %G_NORMALIZE_ALL_COMPOSE.
758 <!-- ##### FUNCTION g_utf8_collate ##### -->
768 <!-- ##### FUNCTION g_utf8_collate_key ##### -->
778 <!-- ##### FUNCTION g_utf8_collate_key_for_filename ##### -->
788 <!-- ##### FUNCTION g_utf8_to_utf16 ##### -->
801 <!-- ##### FUNCTION g_utf8_to_ucs4 ##### -->
814 <!-- ##### FUNCTION g_utf8_to_ucs4_fast ##### -->
825 <!-- ##### FUNCTION g_utf16_to_ucs4 ##### -->
838 <!-- ##### FUNCTION g_utf16_to_utf8 ##### -->
851 <!-- ##### FUNCTION g_ucs4_to_utf16 ##### -->
864 <!-- ##### FUNCTION g_ucs4_to_utf8 ##### -->
877 <!-- ##### FUNCTION g_unichar_to_utf8 ##### -->