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