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