glib/gstring.c

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