glib/gstring.c

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /*
  19  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
  20  * file for a list of people on the GLib Team.  See the ChangeLog
  21  * files for a list of changes.  These files are distributed with
  22  * GLib at ftp://ftp.gtk.org/pub/gtk/.
  23  */
  24
  25 /*
  26  * MT safe
  27  */
  28
  29 #include "config.h"
  30
  31 #include <stdarg.h>
  32 #include <stdlib.h>
  33 #include <stdio.h>
  34 #include <string.h>
  35 #include <ctype.h>
  36
  37 #include "gstring.h"
  38
  39 #include "gprintf.h"
  40
  41
  42 /**
  43  * SECTION:strings
  44  * @title: Strings
  45  * @short_description: text buffers which grow automatically
  46  *     as text is added
  47  *
  48  * A #GString is an object that handles the memory management of a C
  49  * string for you.  The emphasis of #GString is on text, typically
  50  * UTF-8.  Crucially, the "str" member of a #GString is guaranteed to
  51  * have a trailing nul character, and it is therefore always safe to
  52  * call functions such as strchr() or g_strdup() on it.
  53  *
  54  * However, a #GString can also hold arbitrary binary data, because it
  55  * has a "len" member, which includes any possible embedded nul
  56  * characters in the data.  Conceptually then, #GString is like a
  57  * #GByteArray with the addition of many convenience methods for text,
  58  * and a guaranteed nul terminator.
  59  */
  60
  61 /**
  62  * GString:
  63  * @str: points to the character data. It may move as text is added.
  64  *   The @str field is null-terminated and so
  65  *   can be used as an ordinary C string.
  66  * @len: contains the length of the string, not including the
  67  *   terminating nul byte.
  68  * @allocated_len: the number of bytes that can be stored in the
  69  *   string before it needs to be reallocated. May be larger than @len.
  70  *
  71  * The GString struct contains the public fields of a GString.
  72  */
  73
  74
  75 #define MY_MAXSIZE ((gsize)-1)
  76
  77 static inline gsize
  78 nearest_power (gsize base, gsize num)
  79 {
  80   if (num > MY_MAXSIZE / 2)
  81     {
  82       return MY_MAXSIZE;
  83     }
  84   else
  85     {
  86       gsize n = base;
  87
  88       while (n < num)
  89         n <<= 1;
  90
  91       return n;
  92     }
  93 }
  94
  95 static void
  96 g_string_maybe_expand (GString *string,
  97                        gsize    len)
  98 {
  99   if (string->len + len >= string->allocated_len)
 100     {
 101       string->allocated_len = nearest_power (1, string->len + len + 1);
 102       string->str = g_realloc (string->str, string->allocated_len);
 103     }
 104 }
 105
 106 /**
 107  * g_string_sized_new:
 108  * @dfl_size: the default size of the space allocated to
 109  *     hold the string
 110  *
 111  * Creates a new #GString, with enough space for @dfl_size
 112  * bytes. This is useful if you are going to add a lot of
 113  * text to the string and don't want it to be reallocated
 114  * too often.
 115  *
 116  * Returns: the new #GString
 117  */
 118 GString *
 119 g_string_sized_new (gsize dfl_size)
 120 {
 121   GString *string = g_slice_new (GString);
 122
 123   string->allocated_len = 0;
 124   string->len   = 0;
 125   string->str   = NULL;
 126
 127   g_string_maybe_expand (string, MAX (dfl_size, 2));
 128   string->str[0] = 0;
 129
 130   return string;
 131 }
 132
 133 /**
 134  * g_string_new:
 135  * @init: (allow-none): the initial text to copy into the string, or %NULL to
 136  * start with an empty string.
 137  *
 138  * Creates a new #GString, initialized with the given string.
 139  *
 140  * Returns: the new #GString
 141  */
 142 GString *
 143 g_string_new (const gchar *init)
 144 {
 145   GString *string;
 146
 147   if (init == NULL || *init == '\0')
 148     string = g_string_sized_new (2);
 149   else
 150     {
 151       gint len;
 152
 153       len = strlen (init);
 154       string = g_string_sized_new (len + 2);
 155
 156       g_string_append_len (string, init, len);
 157     }
 158
 159   return string;
 160 }
 161
 162 /**
 163  * g_string_new_len:
 164  * @init: initial contents of the string
 165  * @len: length of @init to use
 166  *
 167  * Creates a new #GString with @len bytes of the @init buffer.
 168  * Because a length is provided, @init need not be nul-terminated,
 169  * and can contain embedded nul bytes.
 170  *
 171  * Since this function does not stop at nul bytes, it is the caller's
 172  * responsibility to ensure that @init has at least @len addressable
 173  * bytes.
 174  *
 175  * Returns: a new #GString
 176  */
 177 GString *
 178 g_string_new_len (const gchar *init,
 179                   gssize       len)
 180 {
 181   GString *string;
 182
 183   if (len < 0)
 184     return g_string_new (init);
 185   else
 186     {
 187       string = g_string_sized_new (len);
 188
 189       if (init)
 190         g_string_append_len (string, init, len);
 191
 192       return string;
 193     }
 194 }
 195
 196 /**
 197  * g_string_free:
 198  * @string: a #GString
 199  * @free_segment: if %TRUE, the actual character data is freed as well
 200  *
 201  * Frees the memory allocated for the #GString.
 202  * If @free_segment is %TRUE it also frees the character data.  If
 203  * it's %FALSE, the caller gains ownership of the buffer and must
 204  * free it after use with g_free().
 205  *
 206  * Returns: (nullable): the character data of @string
 207  *          (i.e. %NULL if @free_segment is %TRUE)
 208  */
 209 gchar *
 210 g_string_free (GString  *string,
 211                gboolean  free_segment)
 212 {
 213   gchar *segment;
 214
 215   g_return_val_if_fail (string != NULL, NULL);
 216
 217   if (free_segment)
 218     {
 219       g_free (string->str);
 220       segment = NULL;
 221     }
 222   else
 223     segment = string->str;
 224
 225   g_slice_free (GString, string);
 226
 227   return segment;
 228 }
 229
 230 /**
 231  * g_string_free_to_bytes:
 232  * @string: (transfer full): a #GString
 233  *
 234  * Transfers ownership of the contents of @string to a newly allocated
 235  * #GBytes.  The #GString structure itself is deallocated, and it is
 236  * therefore invalid to use @string after invoking this function.
 237  *
 238  * Note that while #GString ensures that its buffer always has a
 239  * trailing nul character (not reflected in its "len"), the returned
 240  * #GBytes does not include this extra nul; i.e. it has length exactly
 241  * equal to the "len" member.
 242  *
 243  * Returns: A newly allocated #GBytes containing contents of @string; @string itself is freed
 244  * Since: 2.34
 245  */
 246 GBytes*
 247 g_string_free_to_bytes (GString *string)
 248 {
 249   gsize len;
 250   gchar *buf;
 251
 252   g_return_val_if_fail (string != NULL, NULL);
 253
 254   len = string->len;
 255
 256   buf = g_string_free (string, FALSE);
 257
 258   return g_bytes_new_take (buf, len);
 259 }
 260
 261 /**
 262  * g_string_equal:
 263  * @v: a #GString
 264  * @v2: another #GString
 265  *
 266  * Compares two strings for equality, returning %TRUE if they are equal.
 267  * For use with #GHashTable.
 268  *
 269  * Returns: %TRUE if the strings are the same length and contain the
 270  *     same bytes
 271  */
 272 gboolean
 273 g_string_equal (const GString *v,
 274                 const GString *v2)
 275 {
 276   gchar *p, *q;
 277   GString *string1 = (GString *) v;
 278   GString *string2 = (GString *) v2;
 279   gsize i = string1->len;
 280
 281   if (i != string2->len)
 282     return FALSE;
 283
 284   p = string1->str;
 285   q = string2->str;
 286   while (i)
 287     {
 288       if (*p != *q)
 289         return FALSE;
 290       p++;
 291       q++;
 292       i--;
 293     }
 294   return TRUE;
 295 }
 296
 297 /**
 298  * g_string_hash:
 299  * @str: a string to hash
 300  *
 301  * Creates a hash code for @str; for use with #GHashTable.
 302  *
 303  * Returns: hash code for @str
 304  */
 305 guint
 306 g_string_hash (const GString *str)
 307 {
 308   const gchar *p = str->str;
 309   gsize n = str->len;
 310   guint h = 0;
 311
 312   /* 31 bit hash function */
 313   while (n--)
 314     {
 315       h = (h << 5) - h + *p;
 316       p++;
 317     }
 318
 319   return h;
 320 }
 321
 322 /**
 323  * g_string_assign:
 324  * @string: the destination #GString. Its current contents
 325  *          are destroyed.
 326  * @rval: the string to copy into @string
 327  *
 328  * Copies the bytes from a string into a #GString,
 329  * destroying any previous contents. It is rather like
 330  * the standard strcpy() function, except that you do not
 331  * have to worry about having enough space to copy the string.
 332  *
 333  * Returns: @string
 334  */
 335 GString *
 336 g_string_assign (GString     *string,
 337                  const gchar *rval)
 338 {
 339   g_return_val_if_fail (string != NULL, NULL);
 340   g_return_val_if_fail (rval != NULL, string);
 341
 342   /* Make sure assigning to itself doesn't corrupt the string. */
 343   if (string->str != rval)
 344     {
 345       /* Assigning from substring should be ok, since
 346        * g_string_truncate() does not reallocate.
 347        */
 348       g_string_truncate (string, 0);
 349       g_string_append (string, rval);
 350     }
 351
 352   return string;
 353 }
 354
 355 /**
 356  * g_string_truncate:
 357  * @string: a #GString
 358  * @len: the new size of @string
 359  *
 360  * Cuts off the end of the GString, leaving the first @len bytes.
 361  *
 362  * Returns: @string
 363  */
 364 GString *
 365 g_string_truncate (GString *string,
 366                    gsize    len)
 367 {
 368   g_return_val_if_fail (string != NULL, NULL);
 369
 370   string->len = MIN (len, string->len);
 371   string->str[string->len] = 0;
 372
 373   return string;
 374 }
 375
 376 /**
 377  * g_string_set_size:
 378  * @string: a #GString
 379  * @len: the new length
 380  *
 381  * Sets the length of a #GString. If the length is less than
 382  * the current length, the string will be truncated. If the
 383  * length is greater than the current length, the contents
 384  * of the newly added area are undefined. (However, as
 385  * always, string->str[string->len] will be a nul byte.)
 386  *
 387  * Returns: @string
 388  */
 389 GString *
 390 g_string_set_size (GString *string,
 391                    gsize    len)
 392 {
 393   g_return_val_if_fail (string != NULL, NULL);
 394
 395   if (len >= string->allocated_len)
 396     g_string_maybe_expand (string, len - string->len);
 397
 398   string->len = len;
 399   string->str[len] = 0;
 400
 401   return string;
 402 }
 403
 404 /**
 405  * g_string_insert_len:
 406  * @string: a #GString
 407  * @pos: position in @string where insertion should
 408  *       happen, or -1 for at the end
 409  * @val: bytes to insert
 410  * @len: number of bytes of @val to insert
 411  *
 412  * Inserts @len bytes of @val into @string at @pos.
 413  * Because @len is provided, @val may contain embedded
 414  * nuls and need not be nul-terminated. If @pos is -1,
 415  * bytes are inserted at the end of the string.
 416  *
 417  * Since this function does not stop at nul bytes, it is
 418  * the caller's responsibility to ensure that @val has at
 419  * least @len addressable bytes.
 420  *
 421  * Returns: @string
 422  */
 423 GString *
 424 g_string_insert_len (GString     *string,
 425                      gssize       pos,
 426                      const gchar *val,
 427                      gssize       len)
 428 {
 429   g_return_val_if_fail (string != NULL, NULL);
 430   g_return_val_if_fail (len == 0 || val != NULL, string);
 431
 432   if (len == 0)
 433     return string;
 434
 435   if (len < 0)
 436     len = strlen (val);
 437
 438   if (pos < 0)
 439     pos = string->len;
 440   else
 441     g_return_val_if_fail (pos <= string->len, string);
 442
 443   /* Check whether val represents a substring of string.
 444    * This test probably violates chapter and verse of the C standards,
 445    * since ">=" and "<=" are only valid when val really is a substring.
 446    * In practice, it will work on modern archs.
 447    */
 448   if (val >= string->str && val <= string->str + string->len)
 449     {
 450       gsize offset = val - string->str;
 451       gsize precount = 0;
 452
 453       g_string_maybe_expand (string, len);
 454       val = string->str + offset;
 455       /* At this point, val is valid again.  */
 456
 457       /* Open up space where we are going to insert.  */
 458       if (pos < string->len)
 459         memmove (string->str + pos + len, string->str + pos, string->len - pos);
 460
 461       /* Move the source part before the gap, if any.  */
 462       if (offset < pos)
 463         {
 464           precount = MIN (len, pos - offset);
 465           memcpy (string->str + pos, val, precount);
 466         }
 467
 468       /* Move the source part after the gap, if any.  */
 469       if (len > precount)
 470         memcpy (string->str + pos + precount,
 471                 val + /* Already moved: */ precount + /* Space opened up: */ len,
 472                 len - precount);
 473     }
 474   else
 475     {
 476       g_string_maybe_expand (string, len);
 477
 478       /* If we aren't appending at the end, move a hunk
 479        * of the old string to the end, opening up space
 480        */
 481       if (pos < string->len)
 482         memmove (string->str + pos + len, string->str + pos, string->len - pos);
 483
 484       /* insert the new string */
 485       if (len == 1)
 486         string->str[pos] = *val;
 487       else
 488         memcpy (string->str + pos, val, len);
 489     }
 490
 491   string->len += len;
 492
 493   string->str[string->len] = 0;
 494
 495   return string;
 496 }
 497
 498 #define SUB_DELIM_CHARS  "!$&'()*+,;="
 499
 500 static gboolean
 501 is_valid (char        c,
 502           const char *reserved_chars_allowed)
 503 {
 504   if (g_ascii_isalnum (c) ||
 505       c == '-' ||
 506       c == '.' ||
 507       c == '_' ||
 508       c == '~')
 509     return TRUE;
 510
 511   if (reserved_chars_allowed &&
 512       strchr (reserved_chars_allowed, c) != NULL)
 513     return TRUE;
 514
 515   return FALSE;
 516 }
 517
 518 static gboolean
 519 gunichar_ok (gunichar c)
 520 {
 521   return
 522     (c != (gunichar) -2) &&
 523     (c != (gunichar) -1);
 524 }
 525
 526 /**
 527  * g_string_append_uri_escaped:
 528  * @string: a #GString
 529  * @unescaped: a string
 530  * @reserved_chars_allowed: a string of reserved characters allowed
 531  *     to be used, or %NULL
 532  * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters
 533  *
 534  * Appends @unescaped to @string, escaped any characters that
 535  * are reserved in URIs using URI-style escape sequences.
 536  *
 537  * Returns: @string
 538  *
 539  * Since: 2.16
 540  */
 541 GString *
 542 g_string_append_uri_escaped (GString     *string,
 543                              const gchar *unescaped,
 544                              const gchar *reserved_chars_allowed,
 545                              gboolean     allow_utf8)
 546 {
 547   unsigned char c;
 548   const gchar *end;
 549   static const gchar hex[16] = "0123456789ABCDEF";
 550
 551   g_return_val_if_fail (string != NULL, NULL);
 552   g_return_val_if_fail (unescaped != NULL, NULL);
 553
 554   end = unescaped + strlen (unescaped);
 555
 556   while ((c = *unescaped) != 0)
 557     {
 558       if (c >= 0x80 && allow_utf8 &&
 559           gunichar_ok (g_utf8_get_char_validated (unescaped, end - unescaped)))
 560         {
 561           int len = g_utf8_skip [c];
 562           g_string_append_len (string, unescaped, len);
 563           unescaped += len;
 564         }
 565       else if (is_valid (c, reserved_chars_allowed))
 566         {
 567           g_string_append_c (string, c);
 568           unescaped++;
 569         }
 570       else
 571         {
 572           g_string_append_c (string, '%');
 573           g_string_append_c (string, hex[((guchar)c) >> 4]);
 574           g_string_append_c (string, hex[((guchar)c) & 0xf]);
 575           unescaped++;
 576         }
 577     }
 578
 579   return string;
 580 }
 581
 582 /**
 583  * g_string_append:
 584  * @string: a #GString
 585  * @val: the string to append onto the end of @string
 586  *
 587  * Adds a string onto the end of a #GString, expanding
 588  * it if necessary.
 589  *
 590  * Returns: @string
 591  */
 592 GString *
 593 g_string_append (GString     *string,
 594                  const gchar *val)
 595 {
 596   g_return_val_if_fail (string != NULL, NULL);
 597   g_return_val_if_fail (val != NULL, string);
 598
 599   return g_string_insert_len (string, -1, val, -1);
 600 }
 601
 602 /**
 603  * g_string_append_len:
 604  * @string: a #GString
 605  * @val: bytes to append
 606  * @len: number of bytes of @val to use
 607  *
 608  * Appends @len bytes of @val to @string. Because @len is
 609  * provided, @val may contain embedded nuls and need not
 610  * be nul-terminated.
 611  *
 612  * Since this function does not stop at nul bytes, it is
 613  * the caller's responsibility to ensure that @val has at
 614  * least @len addressable bytes.
 615  *
 616  * Returns: @string
 617  */
 618 GString *
 619 g_string_append_len (GString     *string,
 620                      const gchar *val,
 621                      gssize       len)
 622 {
 623   g_return_val_if_fail (string != NULL, NULL);
 624   g_return_val_if_fail (len == 0 || val != NULL, string);
 625
 626   return g_string_insert_len (string, -1, val, len);
 627 }
 628
 629 /**
 630  * g_string_append_c:
 631  * @string: a #GString
 632  * @c: the byte to append onto the end of @string
 633  *
 634  * Adds a byte onto the end of a #GString, expanding
 635  * it if necessary.
 636  *
 637  * Returns: @string
 638  */
 639 #undef g_string_append_c
 640 GString *
 641 g_string_append_c (GString *string,
 642                    gchar    c)
 643 {
 644   g_return_val_if_fail (string != NULL, NULL);
 645
 646   return g_string_insert_c (string, -1, c);
 647 }
 648
 649 /**
 650  * g_string_append_unichar:
 651  * @string: a #GString
 652  * @wc: a Unicode character
 653  *
 654  * Converts a Unicode character into UTF-8, and appends it
 655  * to the string.
 656  *
 657  * Returns: @string
 658  */
 659 GString *
 660 g_string_append_unichar (GString  *string,
 661                          gunichar  wc)
 662 {
 663   g_return_val_if_fail (string != NULL, NULL);
 664
 665   return g_string_insert_unichar (string, -1, wc);
 666 }
 667
 668 /**
 669  * g_string_prepend:
 670  * @string: a #GString
 671  * @val: the string to prepend on the start of @string
 672  *
 673  * Adds a string on to the start of a #GString,
 674  * expanding it if necessary.
 675  *
 676  * Returns: @string
 677  */
 678 GString *
 679 g_string_prepend (GString     *string,
 680                   const gchar *val)
 681 {
 682   g_return_val_if_fail (string != NULL, NULL);
 683   g_return_val_if_fail (val != NULL, string);
 684
 685   return g_string_insert_len (string, 0, val, -1);
 686 }
 687
 688 /**
 689  * g_string_prepend_len:
 690  * @string: a #GString
 691  * @val: bytes to prepend
 692  * @len: number of bytes in @val to prepend
 693  *
 694  * Prepends @len bytes of @val to @string.
 695  * Because @len is provided, @val may contain
 696  * embedded nuls and need not be nul-terminated.
 697  *
 698  * Since this function does not stop at nul bytes,
 699  * it is the caller's responsibility to ensure that
 700  * @val has at least @len addressable bytes.
 701  *
 702  * Returns: @string
 703  */
 704 GString *
 705 g_string_prepend_len (GString     *string,
 706                       const gchar *val,
 707                       gssize       len)
 708 {
 709   g_return_val_if_fail (string != NULL, NULL);
 710   g_return_val_if_fail (val != NULL, string);
 711
 712   return g_string_insert_len (string, 0, val, len);
 713 }
 714
 715 /**
 716  * g_string_prepend_c:
 717  * @string: a #GString
 718  * @c: the byte to prepend on the start of the #GString
 719  *
 720  * Adds a byte onto the start of a #GString,
 721  * expanding it if necessary.
 722  *
 723  * Returns: @string
 724  */
 725 GString *
 726 g_string_prepend_c (GString *string,
 727                     gchar    c)
 728 {
 729   g_return_val_if_fail (string != NULL, NULL);
 730
 731   return g_string_insert_c (string, 0, c);
 732 }
 733
 734 /**
 735  * g_string_prepend_unichar:
 736  * @string: a #GString
 737  * @wc: a Unicode character
 738  *
 739  * Converts a Unicode character into UTF-8, and prepends it
 740  * to the string.
 741  *
 742  * Returns: @string
 743  */
 744 GString *
 745 g_string_prepend_unichar (GString  *string,
 746                           gunichar  wc)
 747 {
 748   g_return_val_if_fail (string != NULL, NULL);
 749
 750   return g_string_insert_unichar (string, 0, wc);
 751 }
 752
 753 /**
 754  * g_string_insert:
 755  * @string: a #GString
 756  * @pos: the position to insert the copy of the string
 757  * @val: the string to insert
 758  *
 759  * Inserts a copy of a string into a #GString,
 760  * expanding it if necessary.
 761  *
 762  * Returns: @string
 763  */
 764 GString *
 765 g_string_insert (GString     *string,
 766                  gssize       pos,
 767                  const gchar *val)
 768 {
 769   g_return_val_if_fail (string != NULL, NULL);
 770   g_return_val_if_fail (val != NULL, string);
 771
 772   if (pos >= 0)
 773     g_return_val_if_fail (pos <= string->len, string);
 774
 775   return g_string_insert_len (string, pos, val, -1);
 776 }
 777
 778 /**
 779  * g_string_insert_c:
 780  * @string: a #GString
 781  * @pos: the position to insert the byte
 782  * @c: the byte to insert
 783  *
 784  * Inserts a byte into a #GString, expanding it if necessary.
 785  *
 786  * Returns: @string
 787  */
 788 GString *
 789 g_string_insert_c (GString *string,
 790                    gssize   pos,
 791                    gchar    c)
 792 {
 793   g_return_val_if_fail (string != NULL, NULL);
 794
 795   g_string_maybe_expand (string, 1);
 796
 797   if (pos < 0)
 798     pos = string->len;
 799   else
 800     g_return_val_if_fail (pos <= string->len, string);
 801
 802   /* If not just an append, move the old stuff */
 803   if (pos < string->len)
 804     memmove (string->str + pos + 1, string->str + pos, string->len - pos);
 805
 806   string->str[pos] = c;
 807
 808   string->len += 1;
 809
 810   string->str[string->len] = 0;
 811
 812   return string;
 813 }
 814
 815 /**
 816  * g_string_insert_unichar:
 817  * @string: a #GString
 818  * @pos: the position at which to insert character, or -1
 819  *     to append at the end of the string
 820  * @wc: a Unicode character
 821  *
 822  * Converts a Unicode character into UTF-8, and insert it
 823  * into the string at the given position.
 824  *
 825  * Returns: @string
 826  */
 827 GString *
 828 g_string_insert_unichar (GString  *string,
 829                          gssize    pos,
 830                          gunichar  wc)
 831 {
 832   gint charlen, first, i;
 833   gchar *dest;
 834
 835   g_return_val_if_fail (string != NULL, NULL);
 836
 837   /* Code copied from g_unichar_to_utf() */
 838   if (wc < 0x80)
 839     {
 840       first = 0;
 841       charlen = 1;
 842     }
 843   else if (wc < 0x800)
 844     {
 845       first = 0xc0;
 846       charlen = 2;
 847     }
 848   else if (wc < 0x10000)
 849     {
 850       first = 0xe0;
 851       charlen = 3;
 852     }
 853    else if (wc < 0x200000)
 854     {
 855       first = 0xf0;
 856       charlen = 4;
 857     }
 858   else if (wc < 0x4000000)
 859     {
 860       first = 0xf8;
 861       charlen = 5;
 862     }
 863   else
 864     {
 865       first = 0xfc;
 866       charlen = 6;
 867     }
 868   /* End of copied code */
 869
 870   g_string_maybe_expand (string, charlen);
 871
 872   if (pos < 0)
 873     pos = string->len;
 874   else
 875     g_return_val_if_fail (pos <= string->len, string);
 876
 877   /* If not just an append, move the old stuff */
 878   if (pos < string->len)
 879     memmove (string->str + pos + charlen, string->str + pos, string->len - pos);
 880
 881   dest = string->str + pos;
 882   /* Code copied from g_unichar_to_utf() */
 883   for (i = charlen - 1; i > 0; --i)
 884     {
 885       dest[i] = (wc & 0x3f) | 0x80;
 886       wc >>= 6;
 887     }
 888   dest[0] = wc | first;
 889   /* End of copied code */
 890
 891   string->len += charlen;
 892
 893   string->str[string->len] = 0;
 894
 895   return string;
 896 }
 897
 898 /**
 899  * g_string_overwrite:
 900  * @string: a #GString
 901  * @pos: the position at which to start overwriting
 902  * @val: the string that will overwrite the @string starting at @pos
 903  *
 904  * Overwrites part of a string, lengthening it if necessary.
 905  *
 906  * Returns: @string
 907  *
 908  * Since: 2.14
 909  */
 910 GString *
 911 g_string_overwrite (GString     *string,
 912                     gsize        pos,
 913                     const gchar *val)
 914 {
 915   g_return_val_if_fail (val != NULL, string);
 916   return g_string_overwrite_len (string, pos, val, strlen (val));
 917 }
 918
 919 /**
 920  * g_string_overwrite_len:
 921  * @string: a #GString
 922  * @pos: the position at which to start overwriting
 923  * @val: the string that will overwrite the @string starting at @pos
 924  * @len: the number of bytes to write from @val
 925  *
 926  * Overwrites part of a string, lengthening it if necessary.
 927  * This function will work with embedded nuls.
 928  *
 929  * Returns: @string
 930  *
 931  * Since: 2.14
 932  */
 933 GString *
 934 g_string_overwrite_len (GString     *string,
 935                         gsize        pos,
 936                         const gchar *val,
 937                         gssize       len)
 938 {
 939   gsize end;
 940
 941   g_return_val_if_fail (string != NULL, NULL);
 942
 943   if (!len)
 944     return string;
 945
 946   g_return_val_if_fail (val != NULL, string);
 947   g_return_val_if_fail (pos <= string->len, string);
 948
 949   if (len < 0)
 950     len = strlen (val);
 951
 952   end = pos + len;
 953
 954   if (end > string->len)
 955     g_string_maybe_expand (string, end - string->len);
 956
 957   memcpy (string->str + pos, val, len);
 958
 959   if (end > string->len)
 960     {
 961       string->str[end] = '\0';
 962       string->len = end;
 963     }
 964
 965   return string;
 966 }
 967
 968 /**
 969  * g_string_erase:
 970  * @string: a #GString
 971  * @pos: the position of the content to remove
 972  * @len: the number of bytes to remove, or -1 to remove all
 973  *       following bytes
 974  *
 975  * Removes @len bytes from a #GString, starting at position @pos.
 976  * The rest of the #GString is shifted down to fill the gap.
 977  *
 978  * Returns: @string
 979  */
 980 GString *
 981 g_string_erase (GString *string,
 982                 gssize   pos,
 983                 gssize   len)
 984 {
 985   g_return_val_if_fail (string != NULL, NULL);
 986   g_return_val_if_fail (pos >= 0, string);
 987   g_return_val_if_fail (pos <= string->len, string);
 988
 989   if (len < 0)
 990     len = string->len - pos;
 991   else
 992     {
 993       g_return_val_if_fail (pos + len <= string->len, string);
 994
 995       if (pos + len < string->len)
 996         memmove (string->str + pos, string->str + pos + len, string->len - (pos + len));
 997     }
 998
 999   string->len -= len;
1000
1001   string->str[string->len] = 0;
1002
1003   return string;
1004 }
1005
1006 /**
1007  * g_string_ascii_down:
1008  * @string: a GString
1009  *
1010  * Converts all uppercase ASCII letters to lowercase ASCII letters.
1011  *
1012  * Returns: passed-in @string pointer, with all the
1013  *     uppercase characters converted to lowercase in place,
1014  *     with semantics that exactly match g_ascii_tolower().
1015  */
1016 GString *
1017 g_string_ascii_down (GString *string)
1018 {
1019   gchar *s;
1020   gint n;
1021
1022   g_return_val_if_fail (string != NULL, NULL);
1023
1024   n = string->len;
1025   s = string->str;
1026
1027   while (n)
1028     {
1029       *s = g_ascii_tolower (*s);
1030       s++;
1031       n--;
1032     }
1033
1034   return string;
1035 }
1036
1037 /**
1038  * g_string_ascii_up:
1039  * @string: a GString
1040  *
1041  * Converts all lowercase ASCII letters to uppercase ASCII letters.
1042  *
1043  * Returns: passed-in @string pointer, with all the
1044  *     lowercase characters converted to uppercase in place,
1045  *     with semantics that exactly match g_ascii_toupper().
1046  */
1047 GString *
1048 g_string_ascii_up (GString *string)
1049 {
1050   gchar *s;
1051   gint n;
1052
1053   g_return_val_if_fail (string != NULL, NULL);
1054
1055   n = string->len;
1056   s = string->str;
1057
1058   while (n)
1059     {
1060       *s = g_ascii_toupper (*s);
1061       s++;
1062       n--;
1063     }
1064
1065   return string;
1066 }
1067
1068 /**
1069  * g_string_down:
1070  * @string: a #GString
1071  *
1072  * Converts a #GString to lowercase.
1073  *
1074  * Returns: the #GString
1075  *
1076  * Deprecated:2.2: This function uses the locale-specific
1077  *     tolower() function, which is almost never the right thing.
1078  *     Use g_string_ascii_down() or g_utf8_strdown() instead.
1079  */
1080 GString *
1081 g_string_down (GString *string)
1082 {
1083   guchar *s;
1084   glong n;
1085
1086   g_return_val_if_fail (string != NULL, NULL);
1087
1088   n = string->len;
1089   s = (guchar *) string->str;
1090
1091   while (n)
1092     {
1093       if (isupper (*s))
1094         *s = tolower (*s);
1095       s++;
1096       n--;
1097     }
1098
1099   return string;
1100 }
1101
1102 /**
1103  * g_string_up:
1104  * @string: a #GString
1105  *
1106  * Converts a #GString to uppercase.
1107  *
1108  * Returns: @string
1109  *
1110  * Deprecated:2.2: This function uses the locale-specific
1111  *     toupper() function, which is almost never the right thing.
1112  *     Use g_string_ascii_up() or g_utf8_strup() instead.
1113  */
1114 GString *
1115 g_string_up (GString *string)
1116 {
1117   guchar *s;
1118   glong n;
1119
1120   g_return_val_if_fail (string != NULL, NULL);
1121
1122   n = string->len;
1123   s = (guchar *) string->str;
1124
1125   while (n)
1126     {
1127       if (islower (*s))
1128         *s = toupper (*s);
1129       s++;
1130       n--;
1131     }
1132
1133   return string;
1134 }
1135
1136 /**
1137  * g_string_append_vprintf:
1138  * @string: a #GString
1139  * @format: the string format. See the printf() documentation
1140  * @args: the list of arguments to insert in the output
1141  *
1142  * Appends a formatted string onto the end of a #GString.
1143  * This function is similar to g_string_append_printf()
1144  * except that the arguments to the format string are passed
1145  * as a va_list.
1146  *
1147  * Since: 2.14
1148  */
1149 void
1150 g_string_append_vprintf (GString     *string,
1151                          const gchar *format,
1152                          va_list      args)
1153 {
1154   gchar *buf;
1155   gint len;
1156
1157   g_return_if_fail (string != NULL);
1158   g_return_if_fail (format != NULL);
1159
1160   len = g_vasprintf (&buf, format, args);
1161
1162   if (len >= 0)
1163     {
1164       g_string_maybe_expand (string, len);
1165       memcpy (string->str + string->len, buf, len + 1);
1166       string->len += len;
1167       g_free (buf);
1168     }
1169 }
1170
1171 /**
1172  * g_string_vprintf:
1173  * @string: a #GString
1174  * @format: the string format. See the printf() documentation
1175  * @args: the parameters to insert into the format string
1176  *
1177  * Writes a formatted string into a #GString.
1178  * This function is similar to g_string_printf() except that
1179  * the arguments to the format string are passed as a va_list.
1180  *
1181  * Since: 2.14
1182  */
1183 void
1184 g_string_vprintf (GString     *string,
1185                   const gchar *format,
1186                   va_list      args)
1187 {
1188   g_string_truncate (string, 0);
1189   g_string_append_vprintf (string, format, args);
1190 }
1191
1192 /**
1193  * g_string_sprintf:
1194  * @string: a #GString
1195  * @format: the string format. See the sprintf() documentation
1196  * @...: the parameters to insert into the format string
1197  *
1198  * Writes a formatted string into a #GString.
1199  * This is similar to the standard sprintf() function,
1200  * except that the #GString buffer automatically expands
1201  * to contain the results. The previous contents of the
1202  * #GString are destroyed.
1203  *
1204  * Deprecated: This function has been renamed to g_string_printf().
1205  */
1206
1207 /**
1208  * g_string_printf:
1209  * @string: a #GString
1210  * @format: the string format. See the printf() documentation
1211  * @...: the parameters to insert into the format string
1212  *
1213  * Writes a formatted string into a #GString.
1214  * This is similar to the standard sprintf() function,
1215  * except that the #GString buffer automatically expands
1216  * to contain the results. The previous contents of the
1217  * #GString are destroyed.
1218  */
1219 void
1220 g_string_printf (GString     *string,
1221                  const gchar *format,
1222                  ...)
1223 {
1224   va_list args;
1225
1226   g_string_truncate (string, 0);
1227
1228   va_start (args, format);
1229   g_string_append_vprintf (string, format, args);
1230   va_end (args);
1231 }
1232
1233 /**
1234  * g_string_sprintfa:
1235  * @string: a #GString
1236  * @format: the string format. See the sprintf() documentation
1237  * @...: the parameters to insert into the format string
1238  *
1239  * Appends a formatted string onto the end of a #GString.
1240  * This function is similar to g_string_sprintf() except that
1241  * the text is appended to the #GString.
1242  *
1243  * Deprecated: This function has been renamed to g_string_append_printf()
1244  */
1245
1246 /**
1247  * g_string_append_printf:
1248  * @string: a #GString
1249  * @format: the string format. See the printf() documentation
1250  * @...: the parameters to insert into the format string
1251  *
1252  * Appends a formatted string onto the end of a #GString.
1253  * This function is similar to g_string_printf() except
1254  * that the text is appended to the #GString.
1255  */
1256 void
1257 g_string_append_printf (GString     *string,
1258                         const gchar *format,
1259                         ...)
1260 {
1261   va_list args;
1262
1263   va_start (args, format);
1264   g_string_append_vprintf (string, format, args);
1265   va_end (args);
1266 }