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