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