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