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