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