glib/gunicode.h

   1 /* gunicode.h - Unicode manipulation functions
   2  *
   3  *  Copyright (C) 1999, 2000 Tom Tromey
   4  *  Copyright 2000, 2005 Red Hat, Inc.
   5  *
   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.
  10  *
  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.
  15  *
  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.
  20  */
  21
  22 #ifndef __G_UNICODE_H__
  23 #define __G_UNICODE_H__
  24
  25 #include <glib/gerror.h>
  26 #include <glib/gtypes.h>
  27
  28 G_BEGIN_DECLS
  29
  30 typedef guint32 gunichar;
  31 typedef guint16 gunichar2;
  32
  33 /* These are the possible character classifications.
  34  * See http://www.unicode.org/Public/UNIDATA/UCD.html#General_Category_Values
  35  */
  36 typedef enum
  37 {
  38   G_UNICODE_CONTROL,
  39   G_UNICODE_FORMAT,
  40   G_UNICODE_UNASSIGNED,
  41   G_UNICODE_PRIVATE_USE,
  42   G_UNICODE_SURROGATE,
  43   G_UNICODE_LOWERCASE_LETTER,
  44   G_UNICODE_MODIFIER_LETTER,
  45   G_UNICODE_OTHER_LETTER,
  46   G_UNICODE_TITLECASE_LETTER,
  47   G_UNICODE_UPPERCASE_LETTER,
  48   G_UNICODE_COMBINING_MARK,
  49   G_UNICODE_ENCLOSING_MARK,
  50   G_UNICODE_NON_SPACING_MARK,
  51   G_UNICODE_DECIMAL_NUMBER,
  52   G_UNICODE_LETTER_NUMBER,
  53   G_UNICODE_OTHER_NUMBER,
  54   G_UNICODE_CONNECT_PUNCTUATION,
  55   G_UNICODE_DASH_PUNCTUATION,
  56   G_UNICODE_CLOSE_PUNCTUATION,
  57   G_UNICODE_FINAL_PUNCTUATION,
  58   G_UNICODE_INITIAL_PUNCTUATION,
  59   G_UNICODE_OTHER_PUNCTUATION,
  60   G_UNICODE_OPEN_PUNCTUATION,
  61   G_UNICODE_CURRENCY_SYMBOL,
  62   G_UNICODE_MODIFIER_SYMBOL,
  63   G_UNICODE_MATH_SYMBOL,
  64   G_UNICODE_OTHER_SYMBOL,
  65   G_UNICODE_LINE_SEPARATOR,
  66   G_UNICODE_PARAGRAPH_SEPARATOR,
  67   G_UNICODE_SPACE_SEPARATOR
  68 } GUnicodeType;
  69
  70 /* These are the possible line break classifications.
  71  * Note that new types may be added in the future.
  72  * Implementations may regard unknown values like G_UNICODE_BREAK_UNKNOWN
  73  * See http://www.unicode.org/unicode/reports/tr14/
  74  */
  75 typedef enum
  76 {
  77   G_UNICODE_BREAK_MANDATORY,
  78   G_UNICODE_BREAK_CARRIAGE_RETURN,
  79   G_UNICODE_BREAK_LINE_FEED,
  80   G_UNICODE_BREAK_COMBINING_MARK,
  81   G_UNICODE_BREAK_SURROGATE,
  82   G_UNICODE_BREAK_ZERO_WIDTH_SPACE,
  83   G_UNICODE_BREAK_INSEPARABLE,
  84   G_UNICODE_BREAK_NON_BREAKING_GLUE,
  85   G_UNICODE_BREAK_CONTINGENT,
  86   G_UNICODE_BREAK_SPACE,
  87   G_UNICODE_BREAK_AFTER,
  88   G_UNICODE_BREAK_BEFORE,
  89   G_UNICODE_BREAK_BEFORE_AND_AFTER,
  90   G_UNICODE_BREAK_HYPHEN,
  91   G_UNICODE_BREAK_NON_STARTER,
  92   G_UNICODE_BREAK_OPEN_PUNCTUATION,
  93   G_UNICODE_BREAK_CLOSE_PUNCTUATION,
  94   G_UNICODE_BREAK_QUOTATION,
  95   G_UNICODE_BREAK_EXCLAMATION,
  96   G_UNICODE_BREAK_IDEOGRAPHIC,
  97   G_UNICODE_BREAK_NUMERIC,
  98   G_UNICODE_BREAK_INFIX_SEPARATOR,
  99   G_UNICODE_BREAK_SYMBOL,
 100   G_UNICODE_BREAK_ALPHABETIC,
 101   G_UNICODE_BREAK_PREFIX,
 102   G_UNICODE_BREAK_POSTFIX,
 103   G_UNICODE_BREAK_COMPLEX_CONTEXT,
 104   G_UNICODE_BREAK_AMBIGUOUS,
 105   G_UNICODE_BREAK_UNKNOWN,
 106   G_UNICODE_BREAK_NEXT_LINE,
 107   G_UNICODE_BREAK_WORD_JOINER,
 108   G_UNICODE_BREAK_HANGUL_L_JAMO,
 109   G_UNICODE_BREAK_HANGUL_V_JAMO,
 110   G_UNICODE_BREAK_HANGUL_T_JAMO,
 111   G_UNICODE_BREAK_HANGUL_LV_SYLLABLE,
 112   G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE
 113 } GUnicodeBreakType;
 114
 115 /* Returns TRUE if current locale uses UTF-8 charset.  If CHARSET is
 116  * not null, sets *CHARSET to the name of the current locale's
 117  * charset.  This value is statically allocated, and should be copied
 118  * in case the locale's charset will be changed later using setlocale()
 119  * or in some other way.
 120  */
 121 gboolean g_get_charset (G_CONST_RETURN char **charset);
 122
 123 /* These are all analogs of the <ctype.h> functions.
 124  */
 125 gboolean g_unichar_isalnum   (gunichar c) G_GNUC_CONST;
 126 gboolean g_unichar_isalpha   (gunichar c) G_GNUC_CONST;
 127 gboolean g_unichar_iscntrl   (gunichar c) G_GNUC_CONST;
 128 gboolean g_unichar_isdigit   (gunichar c) G_GNUC_CONST;
 129 gboolean g_unichar_isgraph   (gunichar c) G_GNUC_CONST;
 130 gboolean g_unichar_islower   (gunichar c) G_GNUC_CONST;
 131 gboolean g_unichar_isprint   (gunichar c) G_GNUC_CONST;
 132 gboolean g_unichar_ispunct   (gunichar c) G_GNUC_CONST;
 133 gboolean g_unichar_isspace   (gunichar c) G_GNUC_CONST;
 134 gboolean g_unichar_isupper   (gunichar c) G_GNUC_CONST;
 135 gboolean g_unichar_isxdigit  (gunichar c) G_GNUC_CONST;
 136 gboolean g_unichar_istitle   (gunichar c) G_GNUC_CONST;
 137 gboolean g_unichar_isdefined (gunichar c) G_GNUC_CONST;
 138 gboolean g_unichar_iswide    (gunichar c) G_GNUC_CONST;
 139 gboolean g_unichar_iswide_cjk(gunichar c) G_GNUC_CONST;
 140
 141 /* More <ctype.h> functions.  These convert between the three cases.
 142  * See the Unicode book to understand title case.  */
 143 gunichar g_unichar_toupper (gunichar c) G_GNUC_CONST;
 144 gunichar g_unichar_tolower (gunichar c) G_GNUC_CONST;
 145 gunichar g_unichar_totitle (gunichar c) G_GNUC_CONST;
 146
 147 /* If C is a digit (according to `g_unichar_isdigit'), then return its
 148    numeric value.  Otherwise return -1.  */
 149 gint g_unichar_digit_value (gunichar c) G_GNUC_CONST;
 150
 151 gint g_unichar_xdigit_value (gunichar c) G_GNUC_CONST;
 152
 153 /* Return the Unicode character type of a given character.  */
 154 GUnicodeType g_unichar_type (gunichar c) G_GNUC_CONST;
 155
 156 /* Return the line break property for a given character */
 157 GUnicodeBreakType g_unichar_break_type (gunichar c) G_GNUC_CONST;
 158
 159
 160 /* Compute canonical ordering of a string in-place.  This rearranges
 161    decomposed characters in the string according to their combining
 162    classes.  See the Unicode manual for more information.  */
 163 void g_unicode_canonical_ordering (gunichar *string,
 164                                    gsize     len);
 165
 166 /* Compute canonical decomposition of a character.  Returns g_malloc()d
 167    string of Unicode characters.  RESULT_LEN is set to the resulting
 168    length of the string.  */
 169 gunichar *g_unicode_canonical_decomposition (gunichar  ch,
 170                                              gsize    *result_len) G_GNUC_MALLOC;
 171
 172 /* Array of skip-bytes-per-initial character.
 173  */
 174 GLIB_VAR const gchar * const g_utf8_skip;
 175
 176 #define g_utf8_next_char(p) (char *)((p) + g_utf8_skip[*(guchar *)(p)])
 177
 178 gunichar g_utf8_get_char           (const gchar  *p);
 179 gunichar g_utf8_get_char_validated (const  gchar *p,
 180                                     gssize        max_len);
 181
 182 gchar*   g_utf8_offset_to_pointer (const gchar *str,
 183                                    glong        offset);
 184 glong    g_utf8_pointer_to_offset (const gchar *str,
 185                                    const gchar *pos);
 186 gchar*   g_utf8_prev_char         (const gchar *p);
 187 gchar*   g_utf8_find_next_char    (const gchar *p,
 188                                    const gchar *end);
 189 gchar*   g_utf8_find_prev_char    (const gchar *str,
 190                                    const gchar *p);
 191
 192 glong g_utf8_strlen (const gchar *p,
 193                      gssize       max);
 194
 195 /* Copies n characters from src to dest */
 196 gchar* g_utf8_strncpy (gchar       *dest,
 197                        const gchar *src,
 198                        gsize        n);
 199
 200 /* Find the UTF-8 character corresponding to ch, in string p. These
 201    functions are equivalants to strchr and strrchr */
 202 gchar* g_utf8_strchr  (const gchar *p,
 203                        gssize       len,
 204                        gunichar     c);
 205 gchar* g_utf8_strrchr (const gchar *p,
 206                        gssize       len,
 207                        gunichar     c);
 208 gchar* g_utf8_strreverse (const gchar *str,
 209                           gssize len);
 210
 211 gunichar2 *g_utf8_to_utf16     (const gchar      *str,
 212                                 glong             len,
 213                                 glong            *items_read,
 214                                 glong            *items_written,
 215                                 GError          **error) G_GNUC_MALLOC;
 216 gunichar * g_utf8_to_ucs4      (const gchar      *str,
 217                                 glong             len,
 218                                 glong            *items_read,
 219                                 glong            *items_written,
 220                                 GError          **error) G_GNUC_MALLOC;
 221 gunichar * g_utf8_to_ucs4_fast (const gchar      *str,
 222                                 glong             len,
 223                                 glong            *items_written) G_GNUC_MALLOC;
 224 gunichar * g_utf16_to_ucs4     (const gunichar2  *str,
 225                                 glong             len,
 226                                 glong            *items_read,
 227                                 glong            *items_written,
 228                                 GError          **error) G_GNUC_MALLOC;
 229 gchar*     g_utf16_to_utf8     (const gunichar2  *str,
 230                                 glong             len,
 231                                 glong            *items_read,
 232                                 glong            *items_written,
 233                                 GError          **error) G_GNUC_MALLOC;
 234 gunichar2 *g_ucs4_to_utf16     (const gunichar   *str,
 235                                 glong             len,
 236                                 glong            *items_read,
 237                                 glong            *items_written,
 238                                 GError          **error) G_GNUC_MALLOC;
 239 gchar*     g_ucs4_to_utf8      (const gunichar   *str,
 240                                 glong             len,
 241                                 glong            *items_read,
 242                                 glong            *items_written,
 243                                 GError          **error) G_GNUC_MALLOC;
 244
 245 /* Convert a single character into UTF-8. outbuf must have at
 246  * least 6 bytes of space. Returns the number of bytes in the
 247  * result.
 248  */
 249 gint      g_unichar_to_utf8 (gunichar    c,
 250                              gchar      *outbuf);
 251
 252 /* Validate a UTF8 string, return TRUE if valid, put pointer to
 253  * first invalid char in **end
 254  */
 255
 256 gboolean g_utf8_validate (const gchar  *str,
 257                           gssize        max_len,
 258                           const gchar **end);
 259
 260 /* Validate a Unicode character */
 261 gboolean g_unichar_validate (gunichar ch);
 262
 263 gchar *g_utf8_strup   (const gchar *str,
 264                        gssize       len) G_GNUC_MALLOC;
 265 gchar *g_utf8_strdown (const gchar *str,
 266                        gssize       len) G_GNUC_MALLOC;
 267 gchar *g_utf8_casefold (const gchar *str,
 268                         gssize       len) G_GNUC_MALLOC;
 269
 270 typedef enum {
 271   G_NORMALIZE_DEFAULT,
 272   G_NORMALIZE_NFD = G_NORMALIZE_DEFAULT,
 273   G_NORMALIZE_DEFAULT_COMPOSE,
 274   G_NORMALIZE_NFC = G_NORMALIZE_DEFAULT_COMPOSE,
 275   G_NORMALIZE_ALL,
 276   G_NORMALIZE_NFKD = G_NORMALIZE_ALL,
 277   G_NORMALIZE_ALL_COMPOSE,
 278   G_NORMALIZE_NFKC = G_NORMALIZE_ALL_COMPOSE
 279 } GNormalizeMode;
 280
 281 gchar *g_utf8_normalize (const gchar   *str,
 282                          gssize         len,
 283                          GNormalizeMode mode) G_GNUC_MALLOC;
 284
 285 gint   g_utf8_collate     (const gchar *str1,
 286                            const gchar *str2);
 287 gchar *g_utf8_collate_key (const gchar *str,
 288                            gssize       len) G_GNUC_MALLOC;
 289 gchar *g_utf8_collate_key_for_filename (const gchar *str,
 290                                         gssize       len) G_GNUC_MALLOC;
 291
 292 gboolean g_unichar_get_mirror_char (gunichar ch,
 293                                     gunichar *mirrored_ch);
 294
 295 /* private */
 296
 297 gchar *_g_utf8_make_valid (const gchar *name);
 298
 299
 300 G_END_DECLS
 301
 302 #endif /* __G_UNICODE_H__ */