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