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.1 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: (nullable): 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: (transfer full): 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: (transfer full): 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: (transfer none): @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: (transfer none): @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: (transfer none): @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: (transfer none): @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 (G_UNLIKELY (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: (transfer none): @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: (transfer none): @string
 591  */
 592 GString *
 593 g_string_append (GString     *string,
 594                  const gchar *val)
 595 {
 596   return g_string_insert_len (string, -1, val, -1);
 597 }
 598
 599 /**
 600  * g_string_append_len:
 601  * @string: a #GString
 602  * @val: bytes to append
 603  * @len: number of bytes of @val to use
 604  *
 605  * Appends @len bytes of @val to @string. Because @len is
 606  * provided, @val may contain embedded nuls and need not
 607  * be nul-terminated.
 608  *
 609  * Since this function does not stop at nul bytes, it is
 610  * the caller's responsibility to ensure that @val has at
 611  * least @len addressable bytes.
 612  *
 613  * Returns: (transfer none): @string
 614  */
 615 GString *
 616 g_string_append_len (GString     *string,
 617                      const gchar *val,
 618                      gssize       len)
 619 {
 620   return g_string_insert_len (string, -1, val, len);
 621 }
 622
 623 /**
 624  * g_string_append_c:
 625  * @string: a #GString
 626  * @c: the byte to append onto the end of @string
 627  *
 628  * Adds a byte onto the end of a #GString, expanding
 629  * it if necessary.
 630  *
 631  * Returns: (transfer none): @string
 632  */
 633 #undef g_string_append_c
 634 GString *
 635 g_string_append_c (GString *string,
 636                    gchar    c)
 637 {
 638   g_return_val_if_fail (string != NULL, NULL);
 639
 640   return g_string_insert_c (string, -1, c);
 641 }
 642
 643 /**
 644  * g_string_append_unichar:
 645  * @string: a #GString
 646  * @wc: a Unicode character
 647  *
 648  * Converts a Unicode character into UTF-8, and appends it
 649  * to the string.
 650  *
 651  * Returns: (transfer none): @string
 652  */
 653 GString *
 654 g_string_append_unichar (GString  *string,
 655                          gunichar  wc)
 656 {
 657   g_return_val_if_fail (string != NULL, NULL);
 658
 659   return g_string_insert_unichar (string, -1, wc);
 660 }
 661
 662 /**
 663  * g_string_prepend:
 664  * @string: a #GString
 665  * @val: the string to prepend on the start of @string
 666  *
 667  * Adds a string on to the start of a #GString,
 668  * expanding it if necessary.
 669  *
 670  * Returns: (transfer none): @string
 671  */
 672 GString *
 673 g_string_prepend (GString     *string,
 674                   const gchar *val)
 675 {
 676   return g_string_insert_len (string, 0, val, -1);
 677 }
 678
 679 /**
 680  * g_string_prepend_len:
 681  * @string: a #GString
 682  * @val: bytes to prepend
 683  * @len: number of bytes in @val to prepend
 684  *
 685  * Prepends @len bytes of @val to @string.
 686  * Because @len is provided, @val may contain
 687  * embedded nuls and need not be nul-terminated.
 688  *
 689  * Since this function does not stop at nul bytes,
 690  * it is the caller's responsibility to ensure that
 691  * @val has at least @len addressable bytes.
 692  *
 693  * Returns: (transfer none): @string
 694  */
 695 GString *
 696 g_string_prepend_len (GString     *string,
 697                       const gchar *val,
 698                       gssize       len)
 699 {
 700   return g_string_insert_len (string, 0, val, len);
 701 }
 702
 703 /**
 704  * g_string_prepend_c:
 705  * @string: a #GString
 706  * @c: the byte to prepend on the start of the #GString
 707  *
 708  * Adds a byte onto the start of a #GString,
 709  * expanding it if necessary.
 710  *
 711  * Returns: (transfer none): @string
 712  */
 713 GString *
 714 g_string_prepend_c (GString *string,
 715                     gchar    c)
 716 {
 717   g_return_val_if_fail (string != NULL, NULL);
 718
 719   return g_string_insert_c (string, 0, c);
 720 }
 721
 722 /**
 723  * g_string_prepend_unichar:
 724  * @string: a #GString
 725  * @wc: a Unicode character
 726  *
 727  * Converts a Unicode character into UTF-8, and prepends it
 728  * to the string.
 729  *
 730  * Returns: (transfer none): @string
 731  */
 732 GString *
 733 g_string_prepend_unichar (GString  *string,
 734                           gunichar  wc)
 735 {
 736   g_return_val_if_fail (string != NULL, NULL);
 737
 738   return g_string_insert_unichar (string, 0, wc);
 739 }
 740
 741 /**
 742  * g_string_insert:
 743  * @string: a #GString
 744  * @pos: the position to insert the copy of the string
 745  * @val: the string to insert
 746  *
 747  * Inserts a copy of a string into a #GString,
 748  * expanding it if necessary.
 749  *
 750  * Returns: (transfer none): @string
 751  */
 752 GString *
 753 g_string_insert (GString     *string,
 754                  gssize       pos,
 755                  const gchar *val)
 756 {
 757   return g_string_insert_len (string, pos, val, -1);
 758 }
 759
 760 /**
 761  * g_string_insert_c:
 762  * @string: a #GString
 763  * @pos: the position to insert the byte
 764  * @c: the byte to insert
 765  *
 766  * Inserts a byte into a #GString, expanding it if necessary.
 767  *
 768  * Returns: (transfer none): @string
 769  */
 770 GString *
 771 g_string_insert_c (GString *string,
 772                    gssize   pos,
 773                    gchar    c)
 774 {
 775   g_return_val_if_fail (string != NULL, NULL);
 776
 777   g_string_maybe_expand (string, 1);
 778
 779   if (pos < 0)
 780     pos = string->len;
 781   else
 782     g_return_val_if_fail (pos <= string->len, string);
 783
 784   /* If not just an append, move the old stuff */
 785   if (pos < string->len)
 786     memmove (string->str + pos + 1, string->str + pos, string->len - pos);
 787
 788   string->str[pos] = c;
 789
 790   string->len += 1;
 791
 792   string->str[string->len] = 0;
 793
 794   return string;
 795 }
 796
 797 /**
 798  * g_string_insert_unichar:
 799  * @string: a #GString
 800  * @pos: the position at which to insert character, or -1
 801  *     to append at the end of the string
 802  * @wc: a Unicode character
 803  *
 804  * Converts a Unicode character into UTF-8, and insert it
 805  * into the string at the given position.
 806  *
 807  * Returns: (transfer none): @string
 808  */
 809 GString *
 810 g_string_insert_unichar (GString  *string,
 811                          gssize    pos,
 812                          gunichar  wc)
 813 {
 814   gint charlen, first, i;
 815   gchar *dest;
 816
 817   g_return_val_if_fail (string != NULL, NULL);
 818
 819   /* Code copied from g_unichar_to_utf() */
 820   if (wc < 0x80)
 821     {
 822       first = 0;
 823       charlen = 1;
 824     }
 825   else if (wc < 0x800)
 826     {
 827       first = 0xc0;
 828       charlen = 2;
 829     }
 830   else if (wc < 0x10000)
 831     {
 832       first = 0xe0;
 833       charlen = 3;
 834     }
 835    else if (wc < 0x200000)
 836     {
 837       first = 0xf0;
 838       charlen = 4;
 839     }
 840   else if (wc < 0x4000000)
 841     {
 842       first = 0xf8;
 843       charlen = 5;
 844     }
 845   else
 846     {
 847       first = 0xfc;
 848       charlen = 6;
 849     }
 850   /* End of copied code */
 851
 852   g_string_maybe_expand (string, charlen);
 853
 854   if (pos < 0)
 855     pos = string->len;
 856   else
 857     g_return_val_if_fail (pos <= string->len, string);
 858
 859   /* If not just an append, move the old stuff */
 860   if (pos < string->len)
 861     memmove (string->str + pos + charlen, string->str + pos, string->len - pos);
 862
 863   dest = string->str + pos;
 864   /* Code copied from g_unichar_to_utf() */
 865   for (i = charlen - 1; i > 0; --i)
 866     {
 867       dest[i] = (wc & 0x3f) | 0x80;
 868       wc >>= 6;
 869     }
 870   dest[0] = wc | first;
 871   /* End of copied code */
 872
 873   string->len += charlen;
 874
 875   string->str[string->len] = 0;
 876
 877   return string;
 878 }
 879
 880 /**
 881  * g_string_overwrite:
 882  * @string: a #GString
 883  * @pos: the position at which to start overwriting
 884  * @val: the string that will overwrite the @string starting at @pos
 885  *
 886  * Overwrites part of a string, lengthening it if necessary.
 887  *
 888  * Returns: (transfer none): @string
 889  *
 890  * Since: 2.14
 891  */
 892 GString *
 893 g_string_overwrite (GString     *string,
 894                     gsize        pos,
 895                     const gchar *val)
 896 {
 897   g_return_val_if_fail (val != NULL, string);
 898   return g_string_overwrite_len (string, pos, val, strlen (val));
 899 }
 900
 901 /**
 902  * g_string_overwrite_len:
 903  * @string: a #GString
 904  * @pos: the position at which to start overwriting
 905  * @val: the string that will overwrite the @string starting at @pos
 906  * @len: the number of bytes to write from @val
 907  *
 908  * Overwrites part of a string, lengthening it if necessary.
 909  * This function will work with embedded nuls.
 910  *
 911  * Returns: (transfer none): @string
 912  *
 913  * Since: 2.14
 914  */
 915 GString *
 916 g_string_overwrite_len (GString     *string,
 917                         gsize        pos,
 918                         const gchar *val,
 919                         gssize       len)
 920 {
 921   gsize end;
 922
 923   g_return_val_if_fail (string != NULL, NULL);
 924
 925   if (!len)
 926     return string;
 927
 928   g_return_val_if_fail (val != NULL, string);
 929   g_return_val_if_fail (pos <= string->len, string);
 930
 931   if (len < 0)
 932     len = strlen (val);
 933
 934   end = pos + len;
 935
 936   if (end > string->len)
 937     g_string_maybe_expand (string, end - string->len);
 938
 939   memcpy (string->str + pos, val, len);
 940
 941   if (end > string->len)
 942     {
 943       string->str[end] = '\0';
 944       string->len = end;
 945     }
 946
 947   return string;
 948 }
 949
 950 /**
 951  * g_string_erase:
 952  * @string: a #GString
 953  * @pos: the position of the content to remove
 954  * @len: the number of bytes to remove, or -1 to remove all
 955  *       following bytes
 956  *
 957  * Removes @len bytes from a #GString, starting at position @pos.
 958  * The rest of the #GString is shifted down to fill the gap.
 959  *
 960  * Returns: (transfer none): @string
 961  */
 962 GString *
 963 g_string_erase (GString *string,
 964                 gssize   pos,
 965                 gssize   len)
 966 {
 967   g_return_val_if_fail (string != NULL, NULL);
 968   g_return_val_if_fail (pos >= 0, string);
 969   g_return_val_if_fail (pos <= string->len, string);
 970
 971   if (len < 0)
 972     len = string->len - pos;
 973   else
 974     {
 975       g_return_val_if_fail (pos + len <= string->len, string);
 976
 977       if (pos + len < string->len)
 978         memmove (string->str + pos, string->str + pos + len, string->len - (pos + len));
 979     }
 980
 981   string->len -= len;
 982
 983   string->str[string->len] = 0;
 984
 985   return string;
 986 }
 987
 988 /**
 989  * g_string_ascii_down:
 990  * @string: a GString
 991  *
 992  * Converts all uppercase ASCII letters to lowercase ASCII letters.
 993  *
 994  * Returns: (transfer none): passed-in @string pointer, with all the
 995  *     uppercase characters converted to lowercase in place,
 996  *     with semantics that exactly match g_ascii_tolower().
 997  */
 998 GString *
 999 g_string_ascii_down (GString *string)
1000 {
1001   gchar *s;
1002   gint n;
1003
1004   g_return_val_if_fail (string != NULL, NULL);
1005
1006   n = string->len;
1007   s = string->str;
1008
1009   while (n)
1010     {
1011       *s = g_ascii_tolower (*s);
1012       s++;
1013       n--;
1014     }
1015
1016   return string;
1017 }
1018
1019 /**
1020  * g_string_ascii_up:
1021  * @string: a GString
1022  *
1023  * Converts all lowercase ASCII letters to uppercase ASCII letters.
1024  *
1025  * Returns: (transfer none): passed-in @string pointer, with all the
1026  *     lowercase characters converted to uppercase in place,
1027  *     with semantics that exactly match g_ascii_toupper().
1028  */
1029 GString *
1030 g_string_ascii_up (GString *string)
1031 {
1032   gchar *s;
1033   gint n;
1034
1035   g_return_val_if_fail (string != NULL, NULL);
1036
1037   n = string->len;
1038   s = string->str;
1039
1040   while (n)
1041     {
1042       *s = g_ascii_toupper (*s);
1043       s++;
1044       n--;
1045     }
1046
1047   return string;
1048 }
1049
1050 /**
1051  * g_string_down:
1052  * @string: a #GString
1053  *
1054  * Converts a #GString to lowercase.
1055  *
1056  * Returns: (transfer none): the #GString
1057  *
1058  * Deprecated:2.2: This function uses the locale-specific
1059  *     tolower() function, which is almost never the right thing.
1060  *     Use g_string_ascii_down() or g_utf8_strdown() instead.
1061  */
1062 GString *
1063 g_string_down (GString *string)
1064 {
1065   guchar *s;
1066   glong n;
1067
1068   g_return_val_if_fail (string != NULL, NULL);
1069
1070   n = string->len;
1071   s = (guchar *) string->str;
1072
1073   while (n)
1074     {
1075       if (isupper (*s))
1076         *s = tolower (*s);
1077       s++;
1078       n--;
1079     }
1080
1081   return string;
1082 }
1083
1084 /**
1085  * g_string_up:
1086  * @string: a #GString
1087  *
1088  * Converts a #GString to uppercase.
1089  *
1090  * Returns: (transfer none): @string
1091  *
1092  * Deprecated:2.2: This function uses the locale-specific
1093  *     toupper() function, which is almost never the right thing.
1094  *     Use g_string_ascii_up() or g_utf8_strup() instead.
1095  */
1096 GString *
1097 g_string_up (GString *string)
1098 {
1099   guchar *s;
1100   glong n;
1101
1102   g_return_val_if_fail (string != NULL, NULL);
1103
1104   n = string->len;
1105   s = (guchar *) string->str;
1106
1107   while (n)
1108     {
1109       if (islower (*s))
1110         *s = toupper (*s);
1111       s++;
1112       n--;
1113     }
1114
1115   return string;
1116 }
1117
1118 /**
1119  * g_string_append_vprintf:
1120  * @string: a #GString
1121  * @format: the string format. See the printf() documentation
1122  * @args: the list of arguments to insert in the output
1123  *
1124  * Appends a formatted string onto the end of a #GString.
1125  * This function is similar to g_string_append_printf()
1126  * except that the arguments to the format string are passed
1127  * as a va_list.
1128  *
1129  * Since: 2.14
1130  */
1131 void
1132 g_string_append_vprintf (GString     *string,
1133                          const gchar *format,
1134                          va_list      args)
1135 {
1136   gchar *buf;
1137   gint len;
1138
1139   g_return_if_fail (string != NULL);
1140   g_return_if_fail (format != NULL);
1141
1142   len = g_vasprintf (&buf, format, args);
1143
1144   if (len >= 0)
1145     {
1146       g_string_maybe_expand (string, len);
1147       memcpy (string->str + string->len, buf, len + 1);
1148       string->len += len;
1149       g_free (buf);
1150     }
1151 }
1152
1153 /**
1154  * g_string_vprintf:
1155  * @string: a #GString
1156  * @format: the string format. See the printf() documentation
1157  * @args: the parameters to insert into the format string
1158  *
1159  * Writes a formatted string into a #GString.
1160  * This function is similar to g_string_printf() except that
1161  * the arguments to the format string are passed as a va_list.
1162  *
1163  * Since: 2.14
1164  */
1165 void
1166 g_string_vprintf (GString     *string,
1167                   const gchar *format,
1168                   va_list      args)
1169 {
1170   g_string_truncate (string, 0);
1171   g_string_append_vprintf (string, format, args);
1172 }
1173
1174 /**
1175  * g_string_sprintf:
1176  * @string: a #GString
1177  * @format: the string format. See the sprintf() documentation
1178  * @...: the parameters to insert into the format string
1179  *
1180  * Writes a formatted string into a #GString.
1181  * This is similar to the standard sprintf() function,
1182  * except that the #GString buffer automatically expands
1183  * to contain the results. The previous contents of the
1184  * #GString are destroyed.
1185  *
1186  * Deprecated: This function has been renamed to g_string_printf().
1187  */
1188
1189 /**
1190  * g_string_printf:
1191  * @string: a #GString
1192  * @format: the string format. See the printf() documentation
1193  * @...: the parameters to insert into the format string
1194  *
1195  * Writes a formatted string into a #GString.
1196  * This is similar to the standard sprintf() function,
1197  * except that the #GString buffer automatically expands
1198  * to contain the results. The previous contents of the
1199  * #GString are destroyed.
1200  */
1201 void
1202 g_string_printf (GString     *string,
1203                  const gchar *format,
1204                  ...)
1205 {
1206   va_list args;
1207
1208   g_string_truncate (string, 0);
1209
1210   va_start (args, format);
1211   g_string_append_vprintf (string, format, args);
1212   va_end (args);
1213 }
1214
1215 /**
1216  * g_string_sprintfa:
1217  * @string: a #GString
1218  * @format: the string format. See the sprintf() documentation
1219  * @...: the parameters to insert into the format string
1220  *
1221  * Appends a formatted string onto the end of a #GString.
1222  * This function is similar to g_string_sprintf() except that
1223  * the text is appended to the #GString.
1224  *
1225  * Deprecated: This function has been renamed to g_string_append_printf()
1226  */
1227
1228 /**
1229  * g_string_append_printf:
1230  * @string: a #GString
1231  * @format: the string format. See the printf() documentation
1232  * @...: the parameters to insert into the format string
1233  *
1234  * Appends a formatted string onto the end of a #GString.
1235  * This function is similar to g_string_printf() except
1236  * that the text is appended to the #GString.
1237  */
1238 void
1239 g_string_append_printf (GString     *string,
1240                         const gchar *format,
1241                         ...)
1242 {
1243   va_list args;
1244
1245   va_start (args, format);
1246   g_string_append_vprintf (string, format, args);
1247   va_end (args);
1248 }