glib/gutf8.c

   1 /* gutf8.c - Operations on UTF-8 strings.
   2  *
   3  * Copyright (C) 1999 Tom Tromey
   4  * Copyright (C) 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
  19  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  20  */
  21
  22 #include "config.h"
  23
  24 #include <stdlib.h>
  25 #ifdef HAVE_CODESET
  26 #include <langinfo.h>
  27 #endif
  28 #include <string.h>
  29
  30 #ifdef G_PLATFORM_WIN32
  31 #include <stdio.h>
  32 #define STRICT
  33 #include <windows.h>
  34 #undef STRICT
  35 #endif
  36
  37 #include "gconvert.h"
  38 #include "ghash.h"
  39 #include "gstrfuncs.h"
  40 #include "gtestutils.h"
  41 #include "gtypes.h"
  42 #include "gthread.h"
  43 #include "glibintl.h"
  44
  45 #define UTF8_COMPUTE(Char, Mask, Len)                                         \
  46   if (Char < 128)                                                             \
  47     {                                                                         \
  48       Len = 1;                                                                \
  49       Mask = 0x7f;                                                            \
  50     }                                                                         \
  51   else if ((Char & 0xe0) == 0xc0)                                             \
  52     {                                                                         \
  53       Len = 2;                                                                \
  54       Mask = 0x1f;                                                            \
  55     }                                                                         \
  56   else if ((Char & 0xf0) == 0xe0)                                             \
  57     {                                                                         \
  58       Len = 3;                                                                \
  59       Mask = 0x0f;                                                            \
  60     }                                                                         \
  61   else if ((Char & 0xf8) == 0xf0)                                             \
  62     {                                                                         \
  63       Len = 4;                                                                \
  64       Mask = 0x07;                                                            \
  65     }                                                                         \
  66   else if ((Char & 0xfc) == 0xf8)                                             \
  67     {                                                                         \
  68       Len = 5;                                                                \
  69       Mask = 0x03;                                                            \
  70     }                                                                         \
  71   else if ((Char & 0xfe) == 0xfc)                                             \
  72     {                                                                         \
  73       Len = 6;                                                                \
  74       Mask = 0x01;                                                            \
  75     }                                                                         \
  76   else                                                                        \
  77     Len = -1;
  78
  79 #define UTF8_LENGTH(Char)              \
  80   ((Char) < 0x80 ? 1 :                 \
  81    ((Char) < 0x800 ? 2 :               \
  82     ((Char) < 0x10000 ? 3 :            \
  83      ((Char) < 0x200000 ? 4 :          \
  84       ((Char) < 0x4000000 ? 5 : 6)))))
  85
  86
  87 #define UTF8_GET(Result, Chars, Count, Mask, Len)                             \
  88   (Result) = (Chars)[0] & (Mask);                                             \
  89   for ((Count) = 1; (Count) < (Len); ++(Count))                               \
  90     {                                                                         \
  91       if (((Chars)[(Count)] & 0xc0) != 0x80)                                  \
  92         {                                                                     \
  93           (Result) = -1;                                                      \
  94           break;                                                              \
  95         }                                                                     \
  96       (Result) <<= 6;                                                         \
  97       (Result) |= ((Chars)[(Count)] & 0x3f);                                  \
  98     }
  99
 100 /*
 101  * Check whether a Unicode (5.2) char is in a valid range.
 102  *
 103  * The first check comes from the Unicode guarantee to never encode
 104  * a point above 0x0010ffff, since UTF-16 couldn't represent it.
 105  *
 106  * The second check covers surrogate pairs (category Cs).
 107  *
 108  * @param Char the character
 109  */
 110 #define UNICODE_VALID(Char)                   \
 111     ((Char) < 0x110000 &&                     \
 112      (((Char) & 0xFFFFF800) != 0xD800))
 113
 114
 115 static const gchar utf8_skip_data[256] = {
 116   1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
 117   1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
 118   1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
 119   1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
 120   1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
 121   1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
 122   2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
 123   3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,4,4,4,4,4,4,4,4,5,5,5,5,6,6,1,1
 124 };
 125
 126 const gchar * const g_utf8_skip = utf8_skip_data;
 127
 128 /**
 129  * g_utf8_find_prev_char:
 130  * @str: pointer to the beginning of a UTF-8 encoded string
 131  * @p: pointer to some position within @str
 132  *
 133  * Given a position @p with a UTF-8 encoded string @str, find the start
 134  * of the previous UTF-8 character starting before @p. Returns %NULL if no
 135  * UTF-8 characters are present in @str before @p.
 136  *
 137  * @p does not have to be at the beginning of a UTF-8 character. No check
 138  * is made to see if the character found is actually valid other than
 139  * it starts with an appropriate byte.
 140  *
 141  * Returns: (transfer none) (nullable): a pointer to the found character or %NULL.
 142  */
 143 gchar *
 144 g_utf8_find_prev_char (const gchar *str,
 145                        const gchar *p)
 146 {
 147   while (p > str)
 148     {
 149       --p;
 150       if ((*p & 0xc0) != 0x80)
 151         return (gchar *)p;
 152     }
 153   return NULL;
 154 }
 155
 156 /**
 157  * g_utf8_find_next_char:
 158  * @p: a pointer to a position within a UTF-8 encoded string
 159  * @end: (nullable): a pointer to the byte following the end of the string,
 160  *     or %NULL to indicate that the string is nul-terminated
 161  *
 162  * Finds the start of the next UTF-8 character in the string after @p.
 163  *
 164  * @p does not have to be at the beginning of a UTF-8 character. No check
 165  * is made to see if the character found is actually valid other than
 166  * it starts with an appropriate byte.
 167  *
 168  * If @end is %NULL, the return value will never be %NULL: if the end of the
 169  * string is reached, a pointer to the terminating nul byte is returned. If
 170  * @end is non-%NULL, the return value will be %NULL if the end of the string
 171  * is reached.
 172  *
 173  * Returns: (transfer none) (nullable): a pointer to the found character or %NULL if @end is
 174  *    set and is reached
 175  */
 176 gchar *
 177 g_utf8_find_next_char (const gchar *p,
 178                        const gchar *end)
 179 {
 180   if (end)
 181     {
 182       for (++p; p < end && (*p & 0xc0) == 0x80; ++p)
 183         ;
 184       return (p >= end) ? NULL : (gchar *)p;
 185     }
 186   else
 187     {
 188       for (++p; (*p & 0xc0) == 0x80; ++p)
 189         ;
 190       return (gchar *)p;
 191     }
 192 }
 193
 194 /**
 195  * g_utf8_prev_char:
 196  * @p: a pointer to a position within a UTF-8 encoded string
 197  *
 198  * Finds the previous UTF-8 character in the string before @p.
 199  *
 200  * @p does not have to be at the beginning of a UTF-8 character. No check
 201  * is made to see if the character found is actually valid other than
 202  * it starts with an appropriate byte. If @p might be the first
 203  * character of the string, you must use g_utf8_find_prev_char() instead.
 204  *
 205  * Returns: (transfer none) (not nullable): a pointer to the found character
 206  */
 207 gchar *
 208 g_utf8_prev_char (const gchar *p)
 209 {
 210   while (TRUE)
 211     {
 212       p--;
 213       if ((*p & 0xc0) != 0x80)
 214         return (gchar *)p;
 215     }
 216 }
 217
 218 /**
 219  * g_utf8_strlen:
 220  * @p: pointer to the start of a UTF-8 encoded string
 221  * @max: the maximum number of bytes to examine. If @max
 222  *       is less than 0, then the string is assumed to be
 223  *       nul-terminated. If @max is 0, @p will not be examined and
 224  *       may be %NULL. If @max is greater than 0, up to @max
 225  *       bytes are examined
 226  *
 227  * Computes the length of the string in characters, not including
 228  * the terminating nul character. If the @max'th byte falls in the
 229  * middle of a character, the last (partial) character is not counted.
 230  *
 231  * Returns: the length of the string in characters
 232  */
 233 glong
 234 g_utf8_strlen (const gchar *p,
 235                gssize       max)
 236 {
 237   glong len = 0;
 238   const gchar *start = p;
 239   g_return_val_if_fail (p != NULL || max == 0, 0);
 240
 241   if (max < 0)
 242     {
 243       while (*p)
 244         {
 245           p = g_utf8_next_char (p);
 246           ++len;
 247         }
 248     }
 249   else
 250     {
 251       if (max == 0 || !*p)
 252         return 0;
 253
 254       p = g_utf8_next_char (p);
 255
 256       while (p - start < max && *p)
 257         {
 258           ++len;
 259           p = g_utf8_next_char (p);
 260         }
 261
 262       /* only do the last len increment if we got a complete
 263        * char (don't count partial chars)
 264        */
 265       if (p - start <= max)
 266         ++len;
 267     }
 268
 269   return len;
 270 }
 271
 272 /**
 273  * g_utf8_substring:
 274  * @str: a UTF-8 encoded string
 275  * @start_pos: a character offset within @str
 276  * @end_pos: another character offset within @str,
 277  *   or `-1` to indicate the end of the string
 278  *
 279  * Copies a substring out of a UTF-8 encoded string.
 280  * The substring will contain @end_pos - @start_pos characters.
 281  *
 282  * Since GLib 2.72, `-1` can be passed to @end_pos to indicate the
 283  * end of the string.
 284  *
 285  * Returns: (transfer full): a newly allocated copy of the requested
 286  *     substring. Free with g_free() when no longer needed.
 287  *
 288  * Since: 2.30
 289  */
 290 gchar *
 291 g_utf8_substring (const gchar *str,
 292                   glong        start_pos,
 293                   glong        end_pos)
 294 {
 295   gchar *start, *end, *out;
 296
 297   g_return_val_if_fail (end_pos >= start_pos || end_pos == -1, NULL);
 298
 299   start = g_utf8_offset_to_pointer (str, start_pos);
 300
 301   if (end_pos == -1)
 302     {
 303       glong length = g_utf8_strlen (start, -1);
 304       end = g_utf8_offset_to_pointer (start, length);
 305     }
 306   else
 307     {
 308       end = g_utf8_offset_to_pointer (start, end_pos - start_pos);
 309     }
 310
 311   out = g_malloc (end - start + 1);
 312   memcpy (out, start, end - start);
 313   out[end - start] = 0;
 314
 315   return out;
 316 }
 317
 318 /**
 319  * g_utf8_get_char:
 320  * @p: a pointer to Unicode character encoded as UTF-8
 321  *
 322  * Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
 323  *
 324  * If @p does not point to a valid UTF-8 encoded character, results
 325  * are undefined. If you are not sure that the bytes are complete
 326  * valid Unicode characters, you should use g_utf8_get_char_validated()
 327  * instead.
 328  *
 329  * Returns: the resulting character
 330  */
 331 gunichar
 332 g_utf8_get_char (const gchar *p)
 333 {
 334   int i, mask = 0, len;
 335   gunichar result;
 336   unsigned char c = (unsigned char) *p;
 337
 338   UTF8_COMPUTE (c, mask, len);
 339   if (len == -1)
 340     return (gunichar)-1;
 341   UTF8_GET (result, p, i, mask, len);
 342
 343   return result;
 344 }
 345
 346 /**
 347  * g_utf8_offset_to_pointer:
 348  * @str: a UTF-8 encoded string
 349  * @offset: a character offset within @str
 350  *
 351  * Converts from an integer character offset to a pointer to a position
 352  * within the string.
 353  *
 354  * Since 2.10, this function allows to pass a negative @offset to
 355  * step backwards. It is usually worth stepping backwards from the end
 356  * instead of forwards if @offset is in the last fourth of the string,
 357  * since moving forward is about 3 times faster than moving backward.
 358  *
 359  * Note that this function doesn't abort when reaching the end of @str.
 360  * Therefore you should be sure that @offset is within string boundaries
 361  * before calling that function. Call g_utf8_strlen() when unsure.
 362  * This limitation exists as this function is called frequently during
 363  * text rendering and therefore has to be as fast as possible.
 364  *
 365  * Returns: (transfer none): the resulting pointer
 366  */
 367 gchar *
 368 g_utf8_offset_to_pointer  (const gchar *str,
 369                            glong        offset)
 370 {
 371   const gchar *s = str;
 372
 373   if (offset > 0)
 374     while (offset--)
 375       s = g_utf8_next_char (s);
 376   else
 377     {
 378       const char *s1;
 379
 380       /* This nice technique for fast backwards stepping
 381        * through a UTF-8 string was dubbed "stutter stepping"
 382        * by its inventor, Larry Ewing.
 383        */
 384       while (offset)
 385         {
 386           s1 = s;
 387           s += offset;
 388           while ((*s & 0xc0) == 0x80)
 389             s--;
 390
 391           offset += g_utf8_pointer_to_offset (s, s1);
 392         }
 393     }
 394
 395   return (gchar *)s;
 396 }
 397
 398 /**
 399  * g_utf8_pointer_to_offset:
 400  * @str: a UTF-8 encoded string
 401  * @pos: a pointer to a position within @str
 402  *
 403  * Converts from a pointer to position within a string to an integer
 404  * character offset.
 405  *
 406  * Since 2.10, this function allows @pos to be before @str, and returns
 407  * a negative offset in this case.
 408  *
 409  * Returns: the resulting character offset
 410  */
 411 glong
 412 g_utf8_pointer_to_offset (const gchar *str,
 413                           const gchar *pos)
 414 {
 415   const gchar *s = str;
 416   glong offset = 0;
 417
 418   if (pos < str)
 419     offset = - g_utf8_pointer_to_offset (pos, str);
 420   else
 421     while (s < pos)
 422       {
 423         s = g_utf8_next_char (s);
 424         offset++;
 425       }
 426
 427   return offset;
 428 }
 429
 430
 431 /**
 432  * g_utf8_strncpy:
 433  * @dest: (transfer none): buffer to fill with characters from @src
 434  * @src: UTF-8 encoded string
 435  * @n: character count
 436  *
 437  * Like the standard C strncpy() function, but copies a given number
 438  * of characters instead of a given number of bytes. The @src string
 439  * must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
 440  * text before trying to use UTF-8 utility functions with it.)
 441  *
 442  * Note you must ensure @dest is at least 4 * @n + 1 to fit the
 443  * largest possible UTF-8 characters
 444  *
 445  * Returns: (transfer none): @dest
 446  */
 447 gchar *
 448 g_utf8_strncpy (gchar       *dest,
 449                 const gchar *src,
 450                 gsize        n)
 451 {
 452   const gchar *s = src;
 453   while (n && *s)
 454     {
 455       s = g_utf8_next_char(s);
 456       n--;
 457     }
 458   strncpy(dest, src, s - src);
 459   dest[s - src] = 0;
 460   return dest;
 461 }
 462
 463 /* unicode_strchr */
 464
 465 /**
 466  * g_unichar_to_utf8:
 467  * @c: a Unicode character code
 468  * @outbuf: (out caller-allocates) (optional): output buffer, must have at
 469  *       least 6 bytes of space. If %NULL, the length will be computed and
 470  *       returned and nothing will be written to @outbuf.
 471  *
 472  * Converts a single character to UTF-8.
 473  *
 474  * Returns: number of bytes written
 475  */
 476 int
 477 g_unichar_to_utf8 (gunichar c,
 478                    gchar   *outbuf)
 479 {
 480   /* If this gets modified, also update the copy in g_string_insert_unichar() */
 481   guint len = 0;
 482   int first;
 483   int i;
 484
 485   if (c < 0x80)
 486     {
 487       first = 0;
 488       len = 1;
 489     }
 490   else if (c < 0x800)
 491     {
 492       first = 0xc0;
 493       len = 2;
 494     }
 495   else if (c < 0x10000)
 496     {
 497       first = 0xe0;
 498       len = 3;
 499     }
 500    else if (c < 0x200000)
 501     {
 502       first = 0xf0;
 503       len = 4;
 504     }
 505   else if (c < 0x4000000)
 506     {
 507       first = 0xf8;
 508       len = 5;
 509     }
 510   else
 511     {
 512       first = 0xfc;
 513       len = 6;
 514     }
 515
 516   if (outbuf)
 517     {
 518       for (i = len - 1; i > 0; --i)
 519         {
 520           outbuf[i] = (c & 0x3f) | 0x80;
 521           c >>= 6;
 522         }
 523       outbuf[0] = c | first;
 524     }
 525
 526   return len;
 527 }
 528
 529 /**
 530  * g_utf8_strchr:
 531  * @p: a nul-terminated UTF-8 encoded string
 532  * @len: the maximum length of @p
 533  * @c: a Unicode character
 534  *
 535  * Finds the leftmost occurrence of the given Unicode character
 536  * in a UTF-8 encoded string, while limiting the search to @len bytes.
 537  * If @len is -1, allow unbounded search.
 538  *
 539  * Returns: (transfer none) (nullable): %NULL if the string does not contain the character,
 540  *     otherwise, a pointer to the start of the leftmost occurrence
 541  *     of the character in the string.
 542  */
 543 gchar *
 544 g_utf8_strchr (const char *p,
 545                gssize      len,
 546                gunichar    c)
 547 {
 548   gchar ch[10];
 549
 550   gint charlen = g_unichar_to_utf8 (c, ch);
 551   ch[charlen] = '\0';
 552
 553   return g_strstr_len (p, len, ch);
 554 }
 555
 556
 557 /**
 558  * g_utf8_strrchr:
 559  * @p: a nul-terminated UTF-8 encoded string
 560  * @len: the maximum length of @p
 561  * @c: a Unicode character
 562  *
 563  * Find the rightmost occurrence of the given Unicode character
 564  * in a UTF-8 encoded string, while limiting the search to @len bytes.
 565  * If @len is -1, allow unbounded search.
 566  *
 567  * Returns: (transfer none) (nullable): %NULL if the string does not contain the character,
 568  *     otherwise, a pointer to the start of the rightmost occurrence
 569  *     of the character in the string.
 570  */
 571 gchar *
 572 g_utf8_strrchr (const char *p,
 573                 gssize      len,
 574                 gunichar    c)
 575 {
 576   gchar ch[10];
 577
 578   gint charlen = g_unichar_to_utf8 (c, ch);
 579   ch[charlen] = '\0';
 580
 581   return g_strrstr_len (p, len, ch);
 582 }
 583
 584
 585 /* Like g_utf8_get_char, but take a maximum length
 586  * and return (gunichar)-2 on incomplete trailing character;
 587  * also check for malformed or overlong sequences
 588  * and return (gunichar)-1 in this case.
 589  */
 590 static inline gunichar
 591 g_utf8_get_char_extended (const  gchar *p,
 592                           gssize max_len)
 593 {
 594   gsize i, len;
 595   gunichar min_code;
 596   gunichar wc = (guchar) *p;
 597   const gunichar partial_sequence = (gunichar) -2;
 598   const gunichar malformed_sequence = (gunichar) -1;
 599
 600   if (wc < 0x80)
 601     {
 602       return wc;
 603     }
 604   else if (G_UNLIKELY (wc < 0xc0))
 605     {
 606       return malformed_sequence;
 607     }
 608   else if (wc < 0xe0)
 609     {
 610       len = 2;
 611       wc &= 0x1f;
 612       min_code = 1 << 7;
 613     }
 614   else if (wc < 0xf0)
 615     {
 616       len = 3;
 617       wc &= 0x0f;
 618       min_code = 1 << 11;
 619     }
 620   else if (wc < 0xf8)
 621     {
 622       len = 4;
 623       wc &= 0x07;
 624       min_code = 1 << 16;
 625     }
 626   else if (wc < 0xfc)
 627     {
 628       len = 5;
 629       wc &= 0x03;
 630       min_code = 1 << 21;
 631     }
 632   else if (wc < 0xfe)
 633     {
 634       len = 6;
 635       wc &= 0x01;
 636       min_code = 1 << 26;
 637     }
 638   else
 639     {
 640       return malformed_sequence;
 641     }
 642
 643   if (G_UNLIKELY (max_len >= 0 && len > (gsize) max_len))
 644     {
 645       for (i = 1; i < (gsize) max_len; i++)
 646         {
 647           if ((((guchar *)p)[i] & 0xc0) != 0x80)
 648             return malformed_sequence;
 649         }
 650       return partial_sequence;
 651     }
 652
 653   for (i = 1; i < len; ++i)
 654     {
 655       gunichar ch = ((guchar *)p)[i];
 656
 657       if (G_UNLIKELY ((ch & 0xc0) != 0x80))
 658         {
 659           if (ch)
 660             return malformed_sequence;
 661           else
 662             return partial_sequence;
 663         }
 664
 665       wc <<= 6;
 666       wc |= (ch & 0x3f);
 667     }
 668
 669   if (G_UNLIKELY (wc < min_code))
 670     return malformed_sequence;
 671
 672   return wc;
 673 }
 674
 675 /**
 676  * g_utf8_get_char_validated:
 677  * @p: a pointer to Unicode character encoded as UTF-8
 678  * @max_len: the maximum number of bytes to read, or -1 if @p is nul-terminated
 679  *
 680  * Convert a sequence of bytes encoded as UTF-8 to a Unicode character.
 681  * This function checks for incomplete characters, for invalid characters
 682  * such as characters that are out of the range of Unicode, and for
 683  * overlong encodings of valid characters.
 684  *
 685  * Note that g_utf8_get_char_validated() returns (gunichar)-2 if
 686  * @max_len is positive and any of the bytes in the first UTF-8 character
 687  * sequence are nul.
 688  *
 689  * Returns: the resulting character. If @p points to a partial
 690  *     sequence at the end of a string that could begin a valid
 691  *     character (or if @max_len is zero), returns (gunichar)-2;
 692  *     otherwise, if @p does not point to a valid UTF-8 encoded
 693  *     Unicode character, returns (gunichar)-1.
 694  */
 695 gunichar
 696 g_utf8_get_char_validated (const gchar *p,
 697                            gssize       max_len)
 698 {
 699   gunichar result;
 700
 701   if (max_len == 0)
 702     return (gunichar)-2;
 703
 704   result = g_utf8_get_char_extended (p, max_len);
 705
 706   /* Disallow codepoint U+0000 as it’s a nul byte,
 707    * and all string handling in GLib is nul-terminated */
 708   if (result == 0 && max_len > 0)
 709     return (gunichar) -2;
 710
 711   if (result & 0x80000000)
 712     return result;
 713   else if (!UNICODE_VALID (result))
 714     return (gunichar)-1;
 715   else
 716     return result;
 717 }
 718
 719 #define CONT_BYTE_FAST(p) ((guchar)*p++ & 0x3f)
 720
 721 /**
 722  * g_utf8_to_ucs4_fast:
 723  * @str: a UTF-8 encoded string
 724  * @len: the maximum length of @str to use, in bytes. If @len < 0,
 725  *     then the string is nul-terminated.
 726  * @items_written: (out) (optional): location to store the
 727  *     number of characters in the result, or %NULL.
 728  *
 729  * Convert a string from UTF-8 to a 32-bit fixed width
 730  * representation as UCS-4, assuming valid UTF-8 input.
 731  * This function is roughly twice as fast as g_utf8_to_ucs4()
 732  * but does no error checking on the input. A trailing 0 character
 733  * will be added to the string after the converted text.
 734  *
 735  * Returns: (transfer full): a pointer to a newly allocated UCS-4 string.
 736  *     This value must be freed with g_free().
 737  */
 738 gunichar *
 739 g_utf8_to_ucs4_fast (const gchar *str,
 740                      glong        len,
 741                      glong       *items_written)
 742 {
 743   gunichar *result;
 744   gint n_chars, i;
 745   const gchar *p;
 746
 747   g_return_val_if_fail (str != NULL, NULL);
 748
 749   p = str;
 750   n_chars = 0;
 751   if (len < 0)
 752     {
 753       while (*p)
 754         {
 755           p = g_utf8_next_char (p);
 756           ++n_chars;
 757         }
 758     }
 759   else
 760     {
 761       while (p < str + len && *p)
 762         {
 763           p = g_utf8_next_char (p);
 764           ++n_chars;
 765         }
 766     }
 767
 768   result = g_new (gunichar, n_chars + 1);
 769
 770   p = str;
 771   for (i=0; i < n_chars; i++)
 772     {
 773       guchar first = (guchar)*p++;
 774       gunichar wc;
 775
 776       if (first < 0xc0)
 777         {
 778           /* We really hope first < 0x80, but we don't want to test an
 779            * extra branch for invalid input, which this function
 780            * does not care about. Handling unexpected continuation bytes
 781            * here will do the least damage. */
 782           wc = first;
 783         }
 784       else
 785         {
 786           gunichar c1 = CONT_BYTE_FAST(p);
 787           if (first < 0xe0)
 788             {
 789               wc = ((first & 0x1f) << 6) | c1;
 790             }
 791           else
 792             {
 793               gunichar c2 = CONT_BYTE_FAST(p);
 794               if (first < 0xf0)
 795                 {
 796                   wc = ((first & 0x0f) << 12) | (c1 << 6) | c2;
 797                 }
 798               else
 799                 {
 800                   gunichar c3 = CONT_BYTE_FAST(p);
 801                   wc = ((first & 0x07) << 18) | (c1 << 12) | (c2 << 6) | c3;
 802                   if (G_UNLIKELY (first >= 0xf8))
 803                     {
 804                       /* This can't be valid UTF-8, but g_utf8_next_char()
 805                        * and company allow out-of-range sequences */
 806                       gunichar mask = 1 << 20;
 807                       while ((wc & mask) != 0)
 808                         {
 809                           wc <<= 6;
 810                           wc |= CONT_BYTE_FAST(p);
 811                           mask <<= 5;
 812                         }
 813                       wc &= mask - 1;
 814                     }
 815                 }
 816             }
 817         }
 818       result[i] = wc;
 819     }
 820   result[i] = 0;
 821
 822   if (items_written)
 823     *items_written = i;
 824
 825   return result;
 826 }
 827
 828 static gpointer
 829 try_malloc_n (gsize n_blocks, gsize n_block_bytes, GError **error)
 830 {
 831     gpointer ptr = g_try_malloc_n (n_blocks, n_block_bytes);
 832     if (ptr == NULL)
 833       g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_NO_MEMORY,
 834                            _("Failed to allocate memory"));
 835     return ptr;
 836 }
 837
 838 /**
 839  * g_utf8_to_ucs4:
 840  * @str: a UTF-8 encoded string
 841  * @len: the maximum length of @str to use, in bytes. If @len < 0,
 842  *     then the string is nul-terminated.
 843  * @items_read: (out) (optional): location to store number of
 844   *    bytes read, or %NULL.
 845  *     If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
 846  *     returned in case @str contains a trailing partial
 847  *     character. If an error occurs then the index of the
 848  *     invalid input is stored here.
 849  * @items_written: (out) (optional): location to store number
 850  *     of characters written or %NULL. The value here stored does not include
 851  *     the trailing 0 character.
 852  * @error: location to store the error occurring, or %NULL to ignore
 853  *     errors. Any of the errors in #GConvertError other than
 854  *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
 855  *
 856  * Convert a string from UTF-8 to a 32-bit fixed width
 857  * representation as UCS-4. A trailing 0 character will be added to the
 858  * string after the converted text.
 859  *
 860  * Returns: (transfer full): a pointer to a newly allocated UCS-4 string.
 861  *     This value must be freed with g_free(). If an error occurs,
 862  *     %NULL will be returned and @error set.
 863  */
 864 gunichar *
 865 g_utf8_to_ucs4 (const gchar *str,
 866                 glong        len,
 867                 glong       *items_read,
 868                 glong       *items_written,
 869                 GError     **error)
 870 {
 871   gunichar *result = NULL;
 872   gint n_chars, i;
 873   const gchar *in;
 874
 875   in = str;
 876   n_chars = 0;
 877   while ((len < 0 || str + len - in > 0) && *in)
 878     {
 879       gunichar wc = g_utf8_get_char_extended (in, len < 0 ? 6 : str + len - in);
 880       if (wc & 0x80000000)
 881         {
 882           if (wc == (gunichar)-2)
 883             {
 884               if (items_read)
 885                 break;
 886               else
 887                 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_PARTIAL_INPUT,
 888                                      _("Partial character sequence at end of input"));
 889             }
 890           else
 891             g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
 892                                  _("Invalid byte sequence in conversion input"));
 893
 894           goto err_out;
 895         }
 896
 897       n_chars++;
 898
 899       in = g_utf8_next_char (in);
 900     }
 901
 902   result = try_malloc_n (n_chars + 1, sizeof (gunichar), error);
 903   if (result == NULL)
 904       goto err_out;
 905
 906   in = str;
 907   for (i=0; i < n_chars; i++)
 908     {
 909       result[i] = g_utf8_get_char (in);
 910       in = g_utf8_next_char (in);
 911     }
 912   result[i] = 0;
 913
 914   if (items_written)
 915     *items_written = n_chars;
 916
 917  err_out:
 918   if (items_read)
 919     *items_read = in - str;
 920
 921   return result;
 922 }
 923
 924 /**
 925  * g_ucs4_to_utf8:
 926  * @str: a UCS-4 encoded string
 927  * @len: the maximum length (number of characters) of @str to use.
 928  *     If @len < 0, then the string is nul-terminated.
 929  * @items_read: (out) (optional): location to store number of
 930  *     characters read, or %NULL.
 931  * @items_written: (out) (optional): location to store number
 932  *     of bytes written or %NULL. The value here stored does not include the
 933  *     trailing 0 byte.
 934  * @error: location to store the error occurring, or %NULL to ignore
 935  *         errors. Any of the errors in #GConvertError other than
 936  *         %G_CONVERT_ERROR_NO_CONVERSION may occur.
 937  *
 938  * Convert a string from a 32-bit fixed width representation as UCS-4.
 939  * to UTF-8. The result will be terminated with a 0 byte.
 940  *
 941  * Returns: (transfer full): a pointer to a newly allocated UTF-8 string.
 942  *     This value must be freed with g_free(). If an error occurs,
 943  *     %NULL will be returned and @error set. In that case, @items_read
 944  *     will be set to the position of the first invalid input character.
 945  */
 946 gchar *
 947 g_ucs4_to_utf8 (const gunichar *str,
 948                 glong           len,
 949                 glong          *items_read,
 950                 glong          *items_written,
 951                 GError        **error)
 952 {
 953   gint result_length;
 954   gchar *result = NULL;
 955   gchar *p;
 956   gint i;
 957
 958   result_length = 0;
 959   for (i = 0; len < 0 || i < len ; i++)
 960     {
 961       if (!str[i])
 962         break;
 963
 964       if (str[i] >= 0x80000000)
 965         {
 966           g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
 967                                _("Character out of range for UTF-8"));
 968           goto err_out;
 969         }
 970
 971       result_length += UTF8_LENGTH (str[i]);
 972     }
 973
 974   result = try_malloc_n (result_length + 1, 1, error);
 975   if (result == NULL)
 976       goto err_out;
 977
 978   p = result;
 979
 980   i = 0;
 981   while (p < result + result_length)
 982     p += g_unichar_to_utf8 (str[i++], p);
 983
 984   *p = '\0';
 985
 986   if (items_written)
 987     *items_written = p - result;
 988
 989  err_out:
 990   if (items_read)
 991     *items_read = i;
 992
 993   return result;
 994 }
 995
 996 #define SURROGATE_VALUE(h,l) (((h) - 0xd800) * 0x400 + (l) - 0xdc00 + 0x10000)
 997
 998 /**
 999  * g_utf16_to_utf8:
1000  * @str: a UTF-16 encoded string
1001  * @len: the maximum length (number of #gunichar2) of @str to use.
1002  *     If @len < 0, then the string is nul-terminated.
1003  * @items_read: (out) (optional): location to store number of
1004  *     words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
1005  *     be returned in case @str contains a trailing partial character. If
1006  *     an error occurs then the index of the invalid input is stored here.
1007  *     It’s guaranteed to be non-negative.
1008  * @items_written: (out) (optional): location to store number
1009  *     of bytes written, or %NULL. The value stored here does not include the
1010  *     trailing 0 byte. It’s guaranteed to be non-negative.
1011  * @error: location to store the error occurring, or %NULL to ignore
1012  *     errors. Any of the errors in #GConvertError other than
1013  *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
1014  *
1015  * Convert a string from UTF-16 to UTF-8. The result will be
1016  * terminated with a 0 byte.
1017  *
1018  * Note that the input is expected to be already in native endianness,
1019  * an initial byte-order-mark character is not handled specially.
1020  * g_convert() can be used to convert a byte buffer of UTF-16 data of
1021  * ambiguous endianness.
1022  *
1023  * Further note that this function does not validate the result
1024  * string; it may e.g. include embedded NUL characters. The only
1025  * validation done by this function is to ensure that the input can
1026  * be correctly interpreted as UTF-16, i.e. it doesn't contain
1027  * unpaired surrogates or partial character sequences.
1028  *
1029  * Returns: (transfer full): a pointer to a newly allocated UTF-8 string.
1030  *     This value must be freed with g_free(). If an error occurs,
1031  *     %NULL will be returned and @error set.
1032  **/
1033 gchar *
1034 g_utf16_to_utf8 (const gunichar2  *str,
1035                  glong             len,
1036                  glong            *items_read,
1037                  glong            *items_written,
1038                  GError          **error)
1039 {
1040   /* This function and g_utf16_to_ucs4 are almost exactly identical -
1041    * The lines that differ are marked.
1042    */
1043   const gunichar2 *in;
1044   gchar *out;
1045   gchar *result = NULL;
1046   gint n_bytes;
1047   gunichar high_surrogate;
1048
1049   g_return_val_if_fail (str != NULL, NULL);
1050
1051   n_bytes = 0;
1052   in = str;
1053   high_surrogate = 0;
1054   while ((len < 0 || in - str < len) && *in)
1055     {
1056       gunichar2 c = *in;
1057       gunichar wc;
1058
1059       if (c >= 0xdc00 && c < 0xe000) /* low surrogate */
1060         {
1061           if (high_surrogate)
1062             {
1063               wc = SURROGATE_VALUE (high_surrogate, c);
1064               high_surrogate = 0;
1065             }
1066           else
1067             {
1068               g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1069                                    _("Invalid sequence in conversion input"));
1070               goto err_out;
1071             }
1072         }
1073       else
1074         {
1075           if (high_surrogate)
1076             {
1077               g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1078                                    _("Invalid sequence in conversion input"));
1079               goto err_out;
1080             }
1081
1082           if (c >= 0xd800 && c < 0xdc00) /* high surrogate */
1083             {
1084               high_surrogate = c;
1085               goto next1;
1086             }
1087           else
1088             wc = c;
1089         }
1090
1091       /********** DIFFERENT for UTF8/UCS4 **********/
1092       n_bytes += UTF8_LENGTH (wc);
1093
1094     next1:
1095       in++;
1096     }
1097
1098   if (high_surrogate && !items_read)
1099     {
1100       g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_PARTIAL_INPUT,
1101                            _("Partial character sequence at end of input"));
1102       goto err_out;
1103     }
1104
1105   /* At this point, everything is valid, and we just need to convert
1106    */
1107   /********** DIFFERENT for UTF8/UCS4 **********/
1108   result = try_malloc_n (n_bytes + 1, 1, error);
1109   if (result == NULL)
1110       goto err_out;
1111
1112   high_surrogate = 0;
1113   out = result;
1114   in = str;
1115   while (out < result + n_bytes)
1116     {
1117       gunichar2 c = *in;
1118       gunichar wc;
1119
1120       if (c >= 0xdc00 && c < 0xe000) /* low surrogate */
1121         {
1122           wc = SURROGATE_VALUE (high_surrogate, c);
1123           high_surrogate = 0;
1124         }
1125       else if (c >= 0xd800 && c < 0xdc00) /* high surrogate */
1126         {
1127           high_surrogate = c;
1128           goto next2;
1129         }
1130       else
1131         wc = c;
1132
1133       /********** DIFFERENT for UTF8/UCS4 **********/
1134       out += g_unichar_to_utf8 (wc, out);
1135
1136     next2:
1137       in++;
1138     }
1139
1140   /********** DIFFERENT for UTF8/UCS4 **********/
1141   *out = '\0';
1142
1143   if (items_written)
1144     /********** DIFFERENT for UTF8/UCS4 **********/
1145     *items_written = out - result;
1146
1147  err_out:
1148   if (items_read)
1149     *items_read = in - str;
1150
1151   return result;
1152 }
1153
1154 /**
1155  * g_utf16_to_ucs4:
1156  * @str: a UTF-16 encoded string
1157  * @len: the maximum length (number of #gunichar2) of @str to use.
1158  *     If @len < 0, then the string is nul-terminated.
1159  * @items_read: (out) (optional): location to store number of
1160  *     words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
1161  *     be returned in case @str contains a trailing partial character. If
1162  *     an error occurs then the index of the invalid input is stored here.
1163  * @items_written: (out) (optional): location to store number
1164  *     of characters written, or %NULL. The value stored here does not include
1165  *     the trailing 0 character.
1166  * @error: location to store the error occurring, or %NULL to ignore
1167  *     errors. Any of the errors in #GConvertError other than
1168  *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
1169  *
1170  * Convert a string from UTF-16 to UCS-4. The result will be
1171  * nul-terminated.
1172  *
1173  * Returns: (transfer full): a pointer to a newly allocated UCS-4 string.
1174  *     This value must be freed with g_free(). If an error occurs,
1175  *     %NULL will be returned and @error set.
1176  */
1177 gunichar *
1178 g_utf16_to_ucs4 (const gunichar2  *str,
1179                  glong             len,
1180                  glong            *items_read,
1181                  glong            *items_written,
1182                  GError          **error)
1183 {
1184   const gunichar2 *in;
1185   gchar *out;
1186   gchar *result = NULL;
1187   gint n_bytes;
1188   gunichar high_surrogate;
1189
1190   g_return_val_if_fail (str != NULL, NULL);
1191
1192   n_bytes = 0;
1193   in = str;
1194   high_surrogate = 0;
1195   while ((len < 0 || in - str < len) && *in)
1196     {
1197       gunichar2 c = *in;
1198
1199       if (c >= 0xdc00 && c < 0xe000) /* low surrogate */
1200         {
1201           if (high_surrogate)
1202             {
1203               high_surrogate = 0;
1204             }
1205           else
1206             {
1207               g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1208                                    _("Invalid sequence in conversion input"));
1209               goto err_out;
1210             }
1211         }
1212       else
1213         {
1214           if (high_surrogate)
1215             {
1216               g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1217                                    _("Invalid sequence in conversion input"));
1218               goto err_out;
1219             }
1220
1221           if (c >= 0xd800 && c < 0xdc00) /* high surrogate */
1222             {
1223               high_surrogate = c;
1224               goto next1;
1225             }
1226         }
1227
1228       /********** DIFFERENT for UTF8/UCS4 **********/
1229       n_bytes += sizeof (gunichar);
1230
1231     next1:
1232       in++;
1233     }
1234
1235   if (high_surrogate && !items_read)
1236     {
1237       g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_PARTIAL_INPUT,
1238                            _("Partial character sequence at end of input"));
1239       goto err_out;
1240     }
1241
1242   /* At this point, everything is valid, and we just need to convert
1243    */
1244   /********** DIFFERENT for UTF8/UCS4 **********/
1245   result = try_malloc_n (n_bytes + 4, 1, error);
1246   if (result == NULL)
1247       goto err_out;
1248
1249   high_surrogate = 0;
1250   out = result;
1251   in = str;
1252   while (out < result + n_bytes)
1253     {
1254       gunichar2 c = *in;
1255       gunichar wc;
1256
1257       if (c >= 0xdc00 && c < 0xe000) /* low surrogate */
1258         {
1259           wc = SURROGATE_VALUE (high_surrogate, c);
1260           high_surrogate = 0;
1261         }
1262       else if (c >= 0xd800 && c < 0xdc00) /* high surrogate */
1263         {
1264           high_surrogate = c;
1265           goto next2;
1266         }
1267       else
1268         wc = c;
1269
1270       /********** DIFFERENT for UTF8/UCS4 **********/
1271       *(gunichar *)out = wc;
1272       out += sizeof (gunichar);
1273
1274     next2:
1275       in++;
1276     }
1277
1278   /********** DIFFERENT for UTF8/UCS4 **********/
1279   *(gunichar *)out = 0;
1280
1281   if (items_written)
1282     /********** DIFFERENT for UTF8/UCS4 **********/
1283     *items_written = (out - result) / sizeof (gunichar);
1284
1285  err_out:
1286   if (items_read)
1287     *items_read = in - str;
1288
1289   return (gunichar *)result;
1290 }
1291
1292 /**
1293  * g_utf8_to_utf16:
1294  * @str: a UTF-8 encoded string
1295  * @len: the maximum length (number of bytes) of @str to use.
1296  *     If @len < 0, then the string is nul-terminated.
1297  * @items_read: (out) (optional): location to store number of
1298  *     bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
1299  *     be returned in case @str contains a trailing partial character. If
1300  *     an error occurs then the index of the invalid input is stored here.
1301  * @items_written: (out) (optional): location to store number
1302  *     of #gunichar2 written, or %NULL. The value stored here does not include
1303  *     the trailing 0.
1304  * @error: location to store the error occurring, or %NULL to ignore
1305  *     errors. Any of the errors in #GConvertError other than
1306  *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
1307  *
1308  * Convert a string from UTF-8 to UTF-16. A 0 character will be
1309  * added to the result after the converted text.
1310  *
1311  * Returns: (transfer full): a pointer to a newly allocated UTF-16 string.
1312  *     This value must be freed with g_free(). If an error occurs,
1313  *     %NULL will be returned and @error set.
1314  */
1315 gunichar2 *
1316 g_utf8_to_utf16 (const gchar *str,
1317                  glong        len,
1318                  glong       *items_read,
1319                  glong       *items_written,
1320                  GError     **error)
1321 {
1322   gunichar2 *result = NULL;
1323   gint n16;
1324   const gchar *in;
1325   gint i;
1326
1327   g_return_val_if_fail (str != NULL, NULL);
1328
1329   in = str;
1330   n16 = 0;
1331   while ((len < 0 || str + len - in > 0) && *in)
1332     {
1333       gunichar wc = g_utf8_get_char_extended (in, len < 0 ? 6 : str + len - in);
1334       if (wc & 0x80000000)
1335         {
1336           if (wc == (gunichar)-2)
1337             {
1338               if (items_read)
1339                 break;
1340               else
1341                 g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_PARTIAL_INPUT,
1342                                      _("Partial character sequence at end of input"));
1343             }
1344           else
1345             g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1346                                  _("Invalid byte sequence in conversion input"));
1347
1348           goto err_out;
1349         }
1350
1351       if (wc < 0xd800)
1352         n16 += 1;
1353       else if (wc < 0xe000)
1354         {
1355           g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1356                                _("Invalid sequence in conversion input"));
1357
1358           goto err_out;
1359         }
1360       else if (wc < 0x10000)
1361         n16 += 1;
1362       else if (wc < 0x110000)
1363         n16 += 2;
1364       else
1365         {
1366           g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1367                                _("Character out of range for UTF-16"));
1368
1369           goto err_out;
1370         }
1371
1372       in = g_utf8_next_char (in);
1373     }
1374
1375   result = try_malloc_n (n16 + 1, sizeof (gunichar2), error);
1376   if (result == NULL)
1377       goto err_out;
1378
1379   in = str;
1380   for (i = 0; i < n16;)
1381     {
1382       gunichar wc = g_utf8_get_char (in);
1383
1384       if (wc < 0x10000)
1385         {
1386           result[i++] = wc;
1387         }
1388       else
1389         {
1390           result[i++] = (wc - 0x10000) / 0x400 + 0xd800;
1391           result[i++] = (wc - 0x10000) % 0x400 + 0xdc00;
1392         }
1393
1394       in = g_utf8_next_char (in);
1395     }
1396
1397   result[i] = 0;
1398
1399   if (items_written)
1400     *items_written = n16;
1401
1402  err_out:
1403   if (items_read)
1404     *items_read = in - str;
1405
1406   return result;
1407 }
1408
1409 /**
1410  * g_ucs4_to_utf16:
1411  * @str: a UCS-4 encoded string
1412  * @len: the maximum length (number of characters) of @str to use.
1413  *     If @len < 0, then the string is nul-terminated.
1414  * @items_read: (out) (optional): location to store number of
1415  *     bytes read, or %NULL. If an error occurs then the index of the invalid
1416  *     input is stored here.
1417  * @items_written: (out) (optional): location to store number
1418  *     of #gunichar2  written, or %NULL. The value stored here does not include
1419  *     the trailing 0.
1420  * @error: location to store the error occurring, or %NULL to ignore
1421  *     errors. Any of the errors in #GConvertError other than
1422  *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
1423  *
1424  * Convert a string from UCS-4 to UTF-16. A 0 character will be
1425  * added to the result after the converted text.
1426  *
1427  * Returns: (transfer full): a pointer to a newly allocated UTF-16 string.
1428  *     This value must be freed with g_free(). If an error occurs,
1429  *     %NULL will be returned and @error set.
1430  */
1431 gunichar2 *
1432 g_ucs4_to_utf16 (const gunichar  *str,
1433                  glong            len,
1434                  glong           *items_read,
1435                  glong           *items_written,
1436                  GError         **error)
1437 {
1438   gunichar2 *result = NULL;
1439   gint n16;
1440   gint i, j;
1441
1442   n16 = 0;
1443   i = 0;
1444   while ((len < 0 || i < len) && str[i])
1445     {
1446       gunichar wc = str[i];
1447
1448       if (wc < 0xd800)
1449         n16 += 1;
1450       else if (wc < 0xe000)
1451         {
1452           g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1453                                _("Invalid sequence in conversion input"));
1454
1455           goto err_out;
1456         }
1457       else if (wc < 0x10000)
1458         n16 += 1;
1459       else if (wc < 0x110000)
1460         n16 += 2;
1461       else
1462         {
1463           g_set_error_literal (error, G_CONVERT_ERROR, G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
1464                                _("Character out of range for UTF-16"));
1465
1466           goto err_out;
1467         }
1468
1469       i++;
1470     }
1471
1472   result = try_malloc_n (n16 + 1, sizeof (gunichar2), error);
1473   if (result == NULL)
1474       goto err_out;
1475
1476   for (i = 0, j = 0; j < n16; i++)
1477     {
1478       gunichar wc = str[i];
1479
1480       if (wc < 0x10000)
1481         {
1482           result[j++] = wc;
1483         }
1484       else
1485         {
1486           result[j++] = (wc - 0x10000) / 0x400 + 0xd800;
1487           result[j++] = (wc - 0x10000) % 0x400 + 0xdc00;
1488         }
1489     }
1490   result[j] = 0;
1491
1492   if (items_written)
1493     *items_written = n16;
1494
1495  err_out:
1496   if (items_read)
1497     *items_read = i;
1498
1499   return result;
1500 }
1501
1502 #define VALIDATE_BYTE(mask, expect)                      \
1503   G_STMT_START {                                         \
1504     if (G_UNLIKELY((*(guchar *)p & (mask)) != (expect))) \
1505       goto error;                                        \
1506   } G_STMT_END
1507
1508 /* see IETF RFC 3629 Section 4 */
1509
1510 static const gchar *
1511 fast_validate (const char *str)
1512
1513 {
1514   const gchar *p;
1515
1516   for (p = str; *p; p++)
1517     {
1518       if (*(guchar *)p < 128)
1519         /* done */;
1520       else
1521         {
1522           const gchar *last;
1523
1524           last = p;
1525           if (*(guchar *)p < 0xe0) /* 110xxxxx */
1526             {
1527               if (G_UNLIKELY (*(guchar *)p < 0xc2))
1528                 goto error;
1529             }
1530           else
1531             {
1532               if (*(guchar *)p < 0xf0) /* 1110xxxx */
1533                 {
1534                   switch (*(guchar *)p++ & 0x0f)
1535                     {
1536                     case 0:
1537                       VALIDATE_BYTE(0xe0, 0xa0); /* 0xa0 ... 0xbf */
1538                       break;
1539                     case 0x0d:
1540                       VALIDATE_BYTE(0xe0, 0x80); /* 0x80 ... 0x9f */
1541                       break;
1542                     default:
1543                       VALIDATE_BYTE(0xc0, 0x80); /* 10xxxxxx */
1544                     }
1545                 }
1546               else if (*(guchar *)p < 0xf5) /* 11110xxx excluding out-of-range */
1547                 {
1548                   switch (*(guchar *)p++ & 0x07)
1549                     {
1550                     case 0:
1551                       VALIDATE_BYTE(0xc0, 0x80); /* 10xxxxxx */
1552                       if (G_UNLIKELY((*(guchar *)p & 0x30) == 0))
1553                         goto error;
1554                       break;
1555                     case 4:
1556                       VALIDATE_BYTE(0xf0, 0x80); /* 0x80 ... 0x8f */
1557                       break;
1558                     default:
1559                       VALIDATE_BYTE(0xc0, 0x80); /* 10xxxxxx */
1560                     }
1561                   p++;
1562                   VALIDATE_BYTE(0xc0, 0x80); /* 10xxxxxx */
1563                 }
1564               else
1565                 goto error;
1566             }
1567
1568           p++;
1569           VALIDATE_BYTE(0xc0, 0x80); /* 10xxxxxx */
1570
1571           continue;
1572
1573         error:
1574           return last;
1575         }
1576     }
1577
1578   return p;
1579 }
1580
1581 static const gchar *
1582 fast_validate_len (const char *str,
1583                    gssize      max_len)
1584
1585 {
1586   const gchar *p;
1587
1588   g_assert (max_len >= 0);
1589
1590   for (p = str; ((p - str) < max_len) && *p; p++)
1591     {
1592       if (*(guchar *)p < 128)
1593         /* done */;
1594       else
1595         {
1596           const gchar *last;
1597
1598           last = p;
1599           if (*(guchar *)p < 0xe0) /* 110xxxxx */
1600             {
1601               if (G_UNLIKELY (max_len - (p - str) < 2))
1602                 goto error;
1603
1604               if (G_UNLIKELY (*(guchar *)p < 0xc2))
1605                 goto error;
1606             }
1607           else
1608             {
1609               if (*(guchar *)p < 0xf0) /* 1110xxxx */
1610                 {
1611                   if (G_UNLIKELY (max_len - (p - str) < 3))
1612                     goto error;
1613
1614                   switch (*(guchar *)p++ & 0x0f)
1615                     {
1616                     case 0:
1617                       VALIDATE_BYTE(0xe0, 0xa0); /* 0xa0 ... 0xbf */
1618                       break;
1619                     case 0x0d:
1620                       VALIDATE_BYTE(0xe0, 0x80); /* 0x80 ... 0x9f */
1621                       break;
1622                     default:
1623                       VALIDATE_BYTE(0xc0, 0x80); /* 10xxxxxx */
1624                     }
1625                 }
1626               else if (*(guchar *)p < 0xf5) /* 11110xxx excluding out-of-range */
1627                 {
1628                   if (G_UNLIKELY (max_len - (p - str) < 4))
1629                     goto error;
1630
1631                   switch (*(guchar *)p++ & 0x07)
1632                     {
1633                     case 0:
1634                       VALIDATE_BYTE(0xc0, 0x80); /* 10xxxxxx */
1635                       if (G_UNLIKELY((*(guchar *)p & 0x30) == 0))
1636                         goto error;
1637                       break;
1638                     case 4:
1639                       VALIDATE_BYTE(0xf0, 0x80); /* 0x80 ... 0x8f */
1640                       break;
1641                     default:
1642                       VALIDATE_BYTE(0xc0, 0x80); /* 10xxxxxx */
1643                     }
1644                   p++;
1645                   VALIDATE_BYTE(0xc0, 0x80); /* 10xxxxxx */
1646                 }
1647               else
1648                 goto error;
1649             }
1650
1651           p++;
1652           VALIDATE_BYTE(0xc0, 0x80); /* 10xxxxxx */
1653
1654           continue;
1655
1656         error:
1657           return last;
1658         }
1659     }
1660
1661   return p;
1662 }
1663
1664 /**
1665  * g_utf8_validate:
1666  * @str: (array length=max_len) (element-type guint8): a pointer to character data
1667  * @max_len: max bytes to validate, or -1 to go until NUL
1668  * @end: (out) (optional) (transfer none): return location for end of valid data
1669  *
1670  * Validates UTF-8 encoded text. @str is the text to validate;
1671  * if @str is nul-terminated, then @max_len can be -1, otherwise
1672  * @max_len should be the number of bytes to validate.
1673  * If @end is non-%NULL, then the end of the valid range
1674  * will be stored there (i.e. the start of the first invalid
1675  * character if some bytes were invalid, or the end of the text
1676  * being validated otherwise).
1677  *
1678  * Note that g_utf8_validate() returns %FALSE if @max_len is
1679  * positive and any of the @max_len bytes are nul.
1680  *
1681  * Returns %TRUE if all of @str was valid. Many GLib and GTK+
1682  * routines require valid UTF-8 as input; so data read from a file
1683  * or the network should be checked with g_utf8_validate() before
1684  * doing anything else with it.
1685  *
1686  * Returns: %TRUE if the text was valid UTF-8
1687  */
1688 gboolean
1689 g_utf8_validate (const char   *str,
1690                  gssize        max_len,
1691                  const gchar **end)
1692
1693 {
1694   const gchar *p;
1695
1696   if (max_len >= 0)
1697     return g_utf8_validate_len (str, max_len, end);
1698
1699   p = fast_validate (str);
1700
1701   if (end)
1702     *end = p;
1703
1704   if (*p != '\0')
1705     return FALSE;
1706   else
1707     return TRUE;
1708 }
1709
1710 /**
1711  * g_utf8_validate_len:
1712  * @str: (array length=max_len) (element-type guint8): a pointer to character data
1713  * @max_len: max bytes to validate
1714  * @end: (out) (optional) (transfer none): return location for end of valid data
1715  *
1716  * Validates UTF-8 encoded text.
1717  *
1718  * As with g_utf8_validate(), but @max_len must be set, and hence this function
1719  * will always return %FALSE if any of the bytes of @str are nul.
1720  *
1721  * Returns: %TRUE if the text was valid UTF-8
1722  * Since: 2.60
1723  */
1724 gboolean
1725 g_utf8_validate_len (const char   *str,
1726                      gsize         max_len,
1727                      const gchar **end)
1728
1729 {
1730   const gchar *p;
1731
1732   p = fast_validate_len (str, max_len);
1733
1734   if (end)
1735     *end = p;
1736
1737   if (p != str + max_len)
1738     return FALSE;
1739   else
1740     return TRUE;
1741 }
1742
1743 /**
1744  * g_unichar_validate:
1745  * @ch: a Unicode character
1746  *
1747  * Checks whether @ch is a valid Unicode character. Some possible
1748  * integer values of @ch will not be valid. 0 is considered a valid
1749  * character, though it's normally a string terminator.
1750  *
1751  * Returns: %TRUE if @ch is a valid Unicode character
1752  **/
1753 gboolean
1754 g_unichar_validate (gunichar ch)
1755 {
1756   return UNICODE_VALID (ch);
1757 }
1758
1759 /**
1760  * g_utf8_strreverse:
1761  * @str: a UTF-8 encoded string
1762  * @len: the maximum length of @str to use, in bytes. If @len < 0,
1763  *     then the string is nul-terminated.
1764  *
1765  * Reverses a UTF-8 string. @str must be valid UTF-8 encoded text.
1766  * (Use g_utf8_validate() on all text before trying to use UTF-8
1767  * utility functions with it.)
1768  *
1769  * This function is intended for programmatic uses of reversed strings.
1770  * It pays no attention to decomposed characters, combining marks, byte
1771  * order marks, directional indicators (LRM, LRO, etc) and similar
1772  * characters which might need special handling when reversing a string
1773  * for display purposes.
1774  *
1775  * Note that unlike g_strreverse(), this function returns
1776  * newly-allocated memory, which should be freed with g_free() when
1777  * no longer needed.
1778  *
1779  * Returns: (transfer full): a newly-allocated string which is the reverse of @str
1780  *
1781  * Since: 2.2
1782  */
1783 gchar *
1784 g_utf8_strreverse (const gchar *str,
1785                    gssize       len)
1786 {
1787   gchar *r, *result;
1788   const gchar *p;
1789
1790   if (len < 0)
1791     len = strlen (str);
1792
1793   result = g_new (gchar, len + 1);
1794   r = result + len;
1795   p = str;
1796   while (r > result)
1797     {
1798       gchar *m, skip = g_utf8_skip[*(guchar*) p];
1799       r -= skip;
1800       g_assert (r >= result);
1801       for (m = r; skip; skip--)
1802         *m++ = *p++;
1803     }
1804   result[len] = 0;
1805
1806   return result;
1807 }
1808
1809 /**
1810  * g_utf8_make_valid:
1811  * @str: string to coerce into UTF-8
1812  * @len: the maximum length of @str to use, in bytes. If @len < 0,
1813  *     then the string is nul-terminated.
1814  *
1815  * If the provided string is valid UTF-8, return a copy of it. If not,
1816  * return a copy in which bytes that could not be interpreted as valid Unicode
1817  * are replaced with the Unicode replacement character (U+FFFD).
1818  *
1819  * For example, this is an appropriate function to use if you have received
1820  * a string that was incorrectly declared to be UTF-8, and you need a valid
1821  * UTF-8 version of it that can be logged or displayed to the user, with the
1822  * assumption that it is close enough to ASCII or UTF-8 to be mostly
1823  * readable as-is.
1824  *
1825  * Returns: (transfer full): a valid UTF-8 string whose content resembles @str
1826  *
1827  * Since: 2.52
1828  */
1829 gchar *
1830 g_utf8_make_valid (const gchar *str,
1831                    gssize       len)
1832 {
1833   GString *string;
1834   const gchar *remainder, *invalid;
1835   gsize remaining_bytes, valid_bytes;
1836
1837   g_return_val_if_fail (str != NULL, NULL);
1838
1839   if (len < 0)
1840     len = strlen (str);
1841
1842   string = NULL;
1843   remainder = str;
1844   remaining_bytes = len;
1845
1846   while (remaining_bytes != 0)
1847     {
1848       if (g_utf8_validate (remainder, remaining_bytes, &invalid))
1849         break;
1850       valid_bytes = invalid - remainder;
1851
1852       if (string == NULL)
1853         string = g_string_sized_new (remaining_bytes);
1854
1855       g_string_append_len (string, remainder, valid_bytes);
1856       /* append U+FFFD REPLACEMENT CHARACTER */
1857       g_string_append (string, "\357\277\275");
1858
1859       remaining_bytes -= valid_bytes + 1;
1860       remainder = invalid + 1;
1861     }
1862
1863   if (string == NULL)
1864     return g_strndup (str, len);
1865
1866   g_string_append_len (string, remainder, remaining_bytes);
1867   g_string_append_c (string, '\0');
1868
1869   g_assert (g_utf8_validate (string->str, -1, NULL));
1870
1871   return g_string_free (string, FALSE);
1872 }