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 and returns %TRUE if they are equal.
  65  * It can be passed to g_hash_table_new() as the @key_equal_func
  66  * 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 size = 1;
 143
 144   size = nearest_power (1, size);
 145
 146   new_chunk->const_table       = NULL;
 147   new_chunk->storage_list      = NULL;
 148   new_chunk->storage_next      = size;
 149   new_chunk->default_size      = size;
 150   new_chunk->this_size         = 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  * The characters in the string can be changed, if necessary, though you
 301  * should not change anything after the end of the string.
 302  *
 303  * Return value: a pointer to the copy of @string within the #GStringChunk
 304  *
 305  * Since: 2.4
 306  **/
 307 gchar*
 308 g_string_chunk_insert_len (GStringChunk *chunk,
 309                            const gchar  *string,
 310                            gssize        len)
 311 {
 312   gssize size;
 313   gchar* pos;
 314
 315   g_return_val_if_fail (chunk != NULL, NULL);
 316
 317   if (len < 0)
 318     size = strlen (string);
 319   else
 320     size = len;
 321
 322   if ((chunk->storage_next + size + 1) > chunk->this_size)
 323     {
 324       gsize new_size = nearest_power (chunk->default_size, size + 1);
 325
 326       chunk->storage_list = g_slist_prepend (chunk->storage_list,
 327                                              g_new (gchar, new_size));
 328
 329       chunk->this_size = new_size;
 330       chunk->storage_next = 0;
 331     }
 332
 333   pos = ((gchar *) chunk->storage_list->data) + chunk->storage_next;
 334
 335   *(pos + size) = '\0';
 336
 337   strncpy (pos, string, size);
 338   if (len > 0)
 339     size = strlen (pos);
 340
 341   chunk->storage_next += size + 1;
 342
 343   return pos;
 344 }
 345
 346 /* Strings.
 347  */
 348 static void
 349 g_string_maybe_expand (GString* string,
 350                        gsize    len)
 351 {
 352   if (string->len + len >= string->allocated_len)
 353     {
 354       string->allocated_len = nearest_power (1, string->len + len + 1);
 355       string->str = g_realloc (string->str, string->allocated_len);
 356     }
 357 }
 358
 359 /**
 360  * g_string_sized_new:
 361  * @dfl_size: the default size of the space allocated to
 362  *            hold the string.
 363  *
 364  * Creates a new #GString, with enough space for @dfl_size
 365  * bytes. This is useful if you are going to add a lot of
 366  * text to the string and don't want it to be reallocated
 367  * too often.
 368  *
 369  * Returns: the new #GString.
 370  */
 371 GString*
 372 g_string_sized_new (gsize dfl_size)
 373 {
 374   GString *string = g_slice_new (GString);
 375
 376   string->allocated_len = 0;
 377   string->len   = 0;
 378   string->str   = NULL;
 379
 380   g_string_maybe_expand (string, MAX (dfl_size, 2));
 381   string->str[0] = 0;
 382
 383   return string;
 384 }
 385
 386 /**
 387  * g_string_new:
 388  * @init: the initial text to copy into the string.
 389  *
 390  * Creates a new #GString, initialized with the given string.
 391  *
 392  * Returns: the new #GString.
 393  */
 394 GString*
 395 g_string_new (const gchar *init)
 396 {
 397   GString *string;
 398
 399   if (init == NULL || *init == '\0')
 400     string = g_string_sized_new (2);
 401   else
 402     {
 403       gint len;
 404
 405       len = strlen (init);
 406       string = g_string_sized_new (len + 2);
 407
 408       g_string_append_len (string, init, len);
 409     }
 410
 411   return string;
 412 }
 413
 414 /**
 415  * g_string_new_len:
 416  * @init: initial contents of string.
 417  * @len: length of @init to use.
 418  *
 419  * Creates a new #GString with @len bytes of the
 420  * @init buffer.  Because a length is provided, @init
 421  * need not be nul-terminated, and can contain embedded
 422  * nul bytes.
 423  *
 424  * Returns: a new #GString.
 425  */
 426 GString*
 427 g_string_new_len (const gchar *init,
 428                   gssize       len)
 429 {
 430   GString *string;
 431
 432   if (len < 0)
 433     return g_string_new (init);
 434   else
 435     {
 436       string = g_string_sized_new (len);
 437
 438       if (init)
 439         g_string_append_len (string, init, len);
 440
 441       return string;
 442     }
 443 }
 444
 445 /**
 446  * g_string_free:
 447  * @string: a #GString
 448  * @free_segment: if %TRUE the actual character data is freed as well
 449  *
 450  * Frees the memory allocated for the #GString.
 451  * If @free_segment is %TRUE it also frees the character data.
 452  *
 453  * Returns: the character data of @string
 454  *          (i.e. %NULL if @free_segment is %TRUE)
 455  */
 456 gchar*
 457 g_string_free (GString *string,
 458                gboolean free_segment)
 459 {
 460   gchar *segment;
 461
 462   g_return_val_if_fail (string != NULL, NULL);
 463
 464   if (free_segment)
 465     {
 466       g_free (string->str);
 467       segment = NULL;
 468     }
 469   else
 470     segment = string->str;
 471
 472   g_slice_free (GString, string);
 473
 474   return segment;
 475 }
 476
 477 /**
 478  * g_string_equal:
 479  * @v: a #GString
 480  * @v2: another #GString
 481  *
 482  * Compares two strings for equality, returning %TRUE if they are equal.
 483  * For use with #GHashTable.
 484  *
 485  * Returns: %TRUE if they strings are the same
 486  *          length and contain the same bytes.
 487  */
 488 gboolean
 489 g_string_equal (const GString *v,
 490                 const GString *v2)
 491 {
 492   gchar *p, *q;
 493   GString *string1 = (GString *) v;
 494   GString *string2 = (GString *) v2;
 495   gsize i = string1->len;
 496
 497   if (i != string2->len)
 498     return FALSE;
 499
 500   p = string1->str;
 501   q = string2->str;
 502   while (i)
 503     {
 504       if (*p != *q)
 505         return FALSE;
 506       p++;
 507       q++;
 508       i--;
 509     }
 510   return TRUE;
 511 }
 512
 513 /**
 514  * g_string_hash:
 515  * @str: a string to hash
 516  *
 517  * Creates a hash code for @str; for use with #GHashTable.
 518  *
 519  * Returns: hash code for @str
 520  */
 521 /* 31 bit hash function */
 522 guint
 523 g_string_hash (const GString *str)
 524 {
 525   const gchar *p = str->str;
 526   gsize n = str->len;
 527   guint h = 0;
 528
 529   while (n--)
 530     {
 531       h = (h << 5) - h + *p;
 532       p++;
 533     }
 534
 535   return h;
 536 }
 537
 538 /**
 539  * g_string_assign:
 540  * @string: the destination #GString. Its current contents
 541  *          are destroyed.
 542  * @rval: the string to copy into @string
 543  *
 544  * Copies the bytes from a string into a #GString,
 545  * destroying any previous contents. It is rather like
 546  * the standard strcpy() function, except that you do not
 547  * have to worry about having enough space to copy the string.
 548  *
 549  * Returns: the destination #GString.
 550  */
 551 GString*
 552 g_string_assign (GString     *string,
 553                  const gchar *rval)
 554 {
 555   g_return_val_if_fail (string != NULL, NULL);
 556   g_return_val_if_fail (rval != NULL, string);
 557
 558   /* Make sure assigning to itself doesn't corrupt the string.  */
 559   if (string->str != rval)
 560     {
 561       /* Assigning from substring should be ok since g_string_truncate
 562          does not realloc.  */
 563       g_string_truncate (string, 0);
 564       g_string_append (string, rval);
 565     }
 566
 567   return string;
 568 }
 569
 570 /**
 571  * g_string_truncate:
 572  * @string: a #GString
 573  * @len: the new size of the #GString
 574  *
 575  * Cuts off the end of the GString, leaving the first @len bytes.
 576  *
 577  * Returns: the #GString
 578  */
 579 GString*
 580 g_string_truncate (GString *string,
 581                    gsize    len)
 582 {
 583   g_return_val_if_fail (string != NULL, NULL);
 584
 585   string->len = MIN (len, string->len);
 586   string->str[string->len] = 0;
 587
 588   return string;
 589 }
 590
 591 /**
 592  * g_string_set_size:
 593  * @string: a #GString
 594  * @len: the new length
 595  *
 596  * Sets the length of a #GString. If the length is less than
 597  * the current length, the string will be truncated. If the
 598  * length is greater than the current length, the contents
 599  * of the newly added area are undefined. (However, as
 600  * always, string->str[string->len] will be a nul byte.)
 601  *
 602  * Return value: @string
 603  **/
 604 GString*
 605 g_string_set_size (GString *string,
 606                    gsize    len)
 607 {
 608   g_return_val_if_fail (string != NULL, NULL);
 609
 610   if (len >= string->allocated_len)
 611     g_string_maybe_expand (string, len - string->len);
 612
 613   string->len = len;
 614   string->str[len] = 0;
 615
 616   return string;
 617 }
 618
 619 /**
 620  * g_string_insert_len:
 621  * @string: a #GString
 622  * @pos: position in @string where insertion should
 623  *       happen, or -1 for at the end
 624  * @val: bytes to insert
 625  * @len: number of bytes of @val to insert
 626  *
 627  * Inserts @len bytes of @val into @string at @pos.
 628  * Because @len is provided, @val may contain embedded
 629  * nuls and need not be nul-terminated. If @pos is -1,
 630  * bytes are inserted at the end of the string.
 631  *
 632  * Returns: the #GString
 633  */
 634 GString*
 635 g_string_insert_len (GString     *string,
 636                      gssize       pos,
 637                      const gchar *val,
 638                      gssize       len)
 639 {
 640   g_return_val_if_fail (string != NULL, NULL);
 641   g_return_val_if_fail (val != NULL, string);
 642
 643   if (len < 0)
 644     len = strlen (val);
 645
 646   if (pos < 0)
 647     pos = string->len;
 648   else
 649     g_return_val_if_fail (pos <= string->len, string);
 650
 651   /* Check whether val represents a substring of string.  This test
 652      probably violates chapter and verse of the C standards, since
 653      ">=" and "<=" are only valid when val really is a substring.
 654      In practice, it will work on modern archs.  */
 655   if (val >= string->str && val <= string->str + string->len)
 656     {
 657       gsize offset = val - string->str;
 658       gsize precount = 0;
 659
 660       g_string_maybe_expand (string, len);
 661       val = string->str + offset;
 662       /* At this point, val is valid again.  */
 663
 664       /* Open up space where we are going to insert.  */
 665       if (pos < string->len)
 666         g_memmove (string->str + pos + len, string->str + pos, string->len - pos);
 667
 668       /* Move the source part before the gap, if any.  */
 669       if (offset < pos)
 670         {
 671           precount = MIN (len, pos - offset);
 672           memcpy (string->str + pos, val, precount);
 673         }
 674
 675       /* Move the source part after the gap, if any.  */
 676       if (len > precount)
 677         memcpy (string->str + pos + precount,
 678                 val + /* Already moved: */ precount + /* Space opened up: */ len,
 679                 len - precount);
 680     }
 681   else
 682     {
 683       g_string_maybe_expand (string, len);
 684
 685       /* If we aren't appending at the end, move a hunk
 686        * of the old string to the end, opening up space
 687        */
 688       if (pos < string->len)
 689         g_memmove (string->str + pos + len, string->str + pos, string->len - pos);
 690
 691       /* insert the new string */
 692       if (len == 1)
 693         string->str[pos] = *val;
 694       else
 695         memcpy (string->str + pos, val, len);
 696     }
 697
 698   string->len += len;
 699
 700   string->str[string->len] = 0;
 701
 702   return string;
 703 }
 704
 705 /**
 706  * g_string_append:
 707  * @string: a #GString.
 708  * @val: the string to append onto the end of the #GString.
 709  *
 710  * Adds a string onto the end of a #GString, expanding it if necessary.
 711  *
 712  * Returns: the #GString.
 713  */
 714 GString*
 715 g_string_append (GString     *string,
 716                  const gchar *val)
 717 {
 718   g_return_val_if_fail (string != NULL, NULL);
 719   g_return_val_if_fail (val != NULL, string);
 720
 721   return g_string_insert_len (string, -1, val, -1);
 722 }
 723
 724 /**
 725  * g_string_append_len:
 726  * @string: a #GString
 727  * @val: bytes to append
 728  * @len: number of bytes of @val to use.
 729  *
 730  * Appends @len bytes of @val to @string.
 731  * Because @len is provided, @val may contain
 732  * embedded nuls and need not be nul-terminated.
 733  *
 734  * Returns: the #GString
 735  */
 736 GString*
 737 g_string_append_len (GString     *string,
 738                      const gchar *val,
 739                      gssize       len)
 740 {
 741   g_return_val_if_fail (string != NULL, NULL);
 742   g_return_val_if_fail (val != NULL, string);
 743
 744   return g_string_insert_len (string, -1, val, len);
 745 }
 746
 747 /**
 748  * g_string_append_c:
 749  * @string: a #GString.
 750  * @c: the byte to append onto the end of the #GString.
 751  *
 752  * Adds a byte onto the end of a #GString, expanding it if necessary.
 753  *
 754  * Returns: the #GString.
 755  */
 756 #undef g_string_append_c
 757 GString*
 758 g_string_append_c (GString *string,
 759                    gchar    c)
 760 {
 761   g_return_val_if_fail (string != NULL, NULL);
 762
 763   return g_string_insert_c (string, -1, c);
 764 }
 765
 766 /**
 767  * g_string_append_unichar:
 768  * @string: a #GString
 769  * @wc: a Unicode character
 770  *
 771  * Converts a Unicode character into UTF-8, and appends it
 772  * to the string.
 773  *
 774  * Return value: @string
 775  **/
 776 GString*
 777 g_string_append_unichar (GString  *string,
 778                          gunichar  wc)
 779 {
 780   g_return_val_if_fail (string != NULL, NULL);
 781
 782   return g_string_insert_unichar (string, -1, wc);
 783 }
 784
 785 /**
 786  * g_string_prepend:
 787  * @string: a #GString
 788  * @val: the string to prepend on the start of the #GString
 789  *
 790  * Adds a string on to the start of a #GString,
 791  * expanding it if necessary.
 792  *
 793  * Returns: the #GString
 794  */
 795 GString*
 796 g_string_prepend (GString     *string,
 797                   const gchar *val)
 798 {
 799   g_return_val_if_fail (string != NULL, NULL);
 800   g_return_val_if_fail (val != NULL, string);
 801
 802   return g_string_insert_len (string, 0, val, -1);
 803 }
 804
 805 /**
 806  * g_string_prepend_len:
 807  * @string: a #GString
 808  * @val: bytes to prepend
 809  * @len: number of bytes in @val to prepend
 810  *
 811  * Prepends @len bytes of @val to @string.
 812  * Because @len is provided, @val may contain
 813  * embedded nuls and need not be nul-terminated.
 814  *
 815  * Returns: the #GString passed in
 816  */
 817 GString*
 818 g_string_prepend_len (GString     *string,
 819                       const gchar *val,
 820                       gssize       len)
 821 {
 822   g_return_val_if_fail (string != NULL, NULL);
 823   g_return_val_if_fail (val != NULL, string);
 824
 825   return g_string_insert_len (string, 0, val, len);
 826 }
 827
 828 /**
 829  * g_string_prepend_c:
 830  * @string: a #GString
 831  * @c: the byte to prepend on the start of the #GString
 832  *
 833  * Adds a byte onto the start of a #GString,
 834  * expanding it if necessary.
 835  *
 836  * Returns: the #GString
 837  */
 838 GString*
 839 g_string_prepend_c (GString *string,
 840                     gchar    c)
 841 {
 842   g_return_val_if_fail (string != NULL, NULL);
 843
 844   return g_string_insert_c (string, 0, c);
 845 }
 846
 847 /**
 848  * g_string_prepend_unichar:
 849  * @string: a #GString.
 850  * @wc: a Unicode character.
 851  *
 852  * Converts a Unicode character into UTF-8, and prepends it
 853  * to the string.
 854  *
 855  * Return value: @string.
 856  **/
 857 GString*
 858 g_string_prepend_unichar (GString  *string,
 859                           gunichar  wc)
 860 {
 861   g_return_val_if_fail (string != NULL, NULL);
 862
 863   return g_string_insert_unichar (string, 0, wc);
 864 }
 865
 866 /**
 867  * g_string_insert:
 868  * @string: a #GString
 869  * @pos: the position to insert the copy of the string
 870  * @val: the string to insert
 871  *
 872  * Inserts a copy of a string into a #GString,
 873  * expanding it if necessary.
 874  *
 875  * Returns: the #GString
 876  */
 877 GString*
 878 g_string_insert (GString     *string,
 879                  gssize       pos,
 880                  const gchar *val)
 881 {
 882   g_return_val_if_fail (string != NULL, NULL);
 883   g_return_val_if_fail (val != NULL, string);
 884   if (pos >= 0)
 885     g_return_val_if_fail (pos <= string->len, string);
 886
 887   return g_string_insert_len (string, pos, val, -1);
 888 }
 889
 890 /**
 891  * g_string_insert_c:
 892  * @string: a #GString
 893  * @pos: the position to insert the byte
 894  * @c: the byte to insert
 895  *
 896  * Inserts a byte into a #GString, expanding it if necessary.
 897  *
 898  * Returns: the #GString
 899  */
 900 GString*
 901 g_string_insert_c (GString *string,
 902                    gssize   pos,
 903                    gchar    c)
 904 {
 905   g_return_val_if_fail (string != NULL, NULL);
 906
 907   g_string_maybe_expand (string, 1);
 908
 909   if (pos < 0)
 910     pos = string->len;
 911   else
 912     g_return_val_if_fail (pos <= string->len, string);
 913
 914   /* If not just an append, move the old stuff */
 915   if (pos < string->len)
 916     g_memmove (string->str + pos + 1, string->str + pos, string->len - pos);
 917
 918   string->str[pos] = c;
 919
 920   string->len += 1;
 921
 922   string->str[string->len] = 0;
 923
 924   return string;
 925 }
 926
 927 /**
 928  * g_string_insert_unichar:
 929  * @string: a #GString
 930  * @pos: the position at which to insert character, or -1 to
 931  *       append at the end of the string.
 932  * @wc: a Unicode character
 933  *
 934  * Converts a Unicode character into UTF-8, and insert it
 935  * into the string at the given position.
 936  *
 937  * Return value: @string
 938  **/
 939 GString*
 940 g_string_insert_unichar (GString *string,
 941                          gssize   pos,
 942                          gunichar wc)
 943 {
 944   gint charlen, first, i;
 945   gchar *dest;
 946
 947   g_return_val_if_fail (string != NULL, NULL);
 948
 949   /* Code copied from g_unichar_to_utf() */
 950   if (wc < 0x80)
 951     {
 952       first = 0;
 953       charlen = 1;
 954     }
 955   else if (wc < 0x800)
 956     {
 957       first = 0xc0;
 958       charlen = 2;
 959     }
 960   else if (wc < 0x10000)
 961     {
 962       first = 0xe0;
 963       charlen = 3;
 964     }
 965    else if (wc < 0x200000)
 966     {
 967       first = 0xf0;
 968       charlen = 4;
 969     }
 970   else if (wc < 0x4000000)
 971     {
 972       first = 0xf8;
 973       charlen = 5;
 974     }
 975   else
 976     {
 977       first = 0xfc;
 978       charlen = 6;
 979     }
 980   /* End of copied code */
 981
 982   g_string_maybe_expand (string, charlen);
 983
 984   if (pos < 0)
 985     pos = string->len;
 986   else
 987     g_return_val_if_fail (pos <= string->len, string);
 988
 989   /* If not just an append, move the old stuff */
 990   if (pos < string->len)
 991     g_memmove (string->str + pos + charlen, string->str + pos, string->len - pos);
 992
 993   dest = string->str + pos;
 994   /* Code copied from g_unichar_to_utf() */
 995   for (i = charlen - 1; i > 0; --i)
 996     {
 997       dest[i] = (wc & 0x3f) | 0x80;
 998       wc >>= 6;
 999     }
1000   dest[0] = wc | first;
1001   /* End of copied code */
1002
1003   string->len += charlen;
1004
1005   string->str[string->len] = 0;
1006
1007   return string;
1008 }
1009
1010 /**
1011  * g_string_erase:
1012  * @string: a #GString
1013  * @pos: the position of the content to remove
1014  * @len: the number of bytes to remove, or -1 to remove all
1015  *       following bytes
1016  *
1017  * Removes @len bytes from a #GString, starting at position @pos.
1018  * The rest of the #GString is shifted down to fill the gap.
1019  *
1020  * Returns: the #GString
1021  */
1022 GString*
1023 g_string_erase (GString *string,
1024                 gssize   pos,
1025                 gssize   len)
1026 {
1027   g_return_val_if_fail (string != NULL, NULL);
1028   g_return_val_if_fail (pos >= 0, string);
1029   g_return_val_if_fail (pos <= string->len, string);
1030
1031   if (len < 0)
1032     len = string->len - pos;
1033   else
1034     {
1035       g_return_val_if_fail (pos + len <= string->len, string);
1036
1037       if (pos + len < string->len)
1038         g_memmove (string->str + pos, string->str + pos + len, string->len - (pos + len));
1039     }
1040
1041   string->len -= len;
1042
1043   string->str[string->len] = 0;
1044
1045   return string;
1046 }
1047
1048 /**
1049  * g_string_ascii_down:
1050  * @string: a GString
1051  *
1052  * Converts all upper case ASCII letters to lower case ASCII letters.
1053  *
1054  * Return value: passed-in @string pointer, with all the upper case
1055  *               characters converted to lower case in place, with
1056  *               semantics that exactly match g_ascii_tolower.
1057  **/
1058 GString*
1059 g_string_ascii_down (GString *string)
1060 {
1061   gchar *s;
1062   gint n;
1063
1064   g_return_val_if_fail (string != NULL, NULL);
1065
1066   n = string->len;
1067   s = string->str;
1068
1069   while (n)
1070     {
1071       *s = g_ascii_tolower (*s);
1072       s++;
1073       n--;
1074     }
1075
1076   return string;
1077 }
1078
1079 /**
1080  * g_string_ascii_up:
1081  * @string: a GString
1082  *
1083  * Converts all lower case ASCII letters to upper case ASCII letters.
1084  *
1085  * Return value: passed-in @string pointer, with all the lower case
1086  *               characters converted to upper case in place, with
1087  *               semantics that exactly match g_ascii_toupper.
1088  **/
1089 GString*
1090 g_string_ascii_up (GString *string)
1091 {
1092   gchar *s;
1093   gint n;
1094
1095   g_return_val_if_fail (string != NULL, NULL);
1096
1097   n = string->len;
1098   s = string->str;
1099
1100   while (n)
1101     {
1102       *s = g_ascii_toupper (*s);
1103       s++;
1104       n--;
1105     }
1106
1107   return string;
1108 }
1109
1110 /**
1111  * g_string_down:
1112  * @string: a #GString
1113  *
1114  * Converts a #GString to lowercase.
1115  *
1116  * Returns: the #GString.
1117  *
1118  * Deprecated:2.2: This function uses the locale-specific tolower() function,
1119  * which is almost never the right thing. Use g_string_ascii_down() or
1120  * g_utf8_strdown() instead.
1121  */
1122 GString*
1123 g_string_down (GString *string)
1124 {
1125   guchar *s;
1126   glong n;
1127
1128   g_return_val_if_fail (string != NULL, NULL);
1129
1130   n = string->len;
1131   s = (guchar *) string->str;
1132
1133   while (n)
1134     {
1135       if (isupper (*s))
1136         *s = tolower (*s);
1137       s++;
1138       n--;
1139     }
1140
1141   return string;
1142 }
1143
1144 /**
1145  * g_string_up:
1146  * @string: a #GString
1147  *
1148  * Converts a #GString to uppercase.
1149  *
1150  * Return value: the #GString
1151  *
1152  * Deprecated:2.2: This function uses the locale-specific toupper() function,
1153  * which is almost never the right thing. Use g_string_ascii_up() or
1154  * g_utf8_strup() instead.
1155  **/
1156 GString*
1157 g_string_up (GString *string)
1158 {
1159   guchar *s;
1160   glong n;
1161
1162   g_return_val_if_fail (string != NULL, NULL);
1163
1164   n = string->len;
1165   s = (guchar *) string->str;
1166
1167   while (n)
1168     {
1169       if (islower (*s))
1170         *s = toupper (*s);
1171       s++;
1172       n--;
1173     }
1174
1175   return string;
1176 }
1177
1178 static void
1179 g_string_append_printf_internal (GString     *string,
1180                                  const gchar *fmt,
1181                                  va_list      args)
1182 {
1183   gchar *buffer;
1184   gint length;
1185
1186   length = g_vasprintf (&buffer, fmt, args);
1187   g_string_append_len (string, buffer, length);
1188   g_free (buffer);
1189 }
1190
1191 /**
1192  * g_string_sprintf:
1193  * @string: a #GString.
1194  * @format: the string format. See the sprintf() documentation.
1195  * @Varargs: the parameters to insert into the format string.
1196  *
1197  * Writes a formatted string into a #GString.
1198  * This is similar to the standard sprintf() function,
1199  * except that the #GString buffer automatically expands
1200  * to contain the results. The previous contents of the
1201  * #GString are destroyed.
1202  *
1203  * Deprecated: This function has been renamed to g_string_printf().
1204  */
1205
1206 /**
1207  * g_string_printf:
1208  * @string: a #GString.
1209  * @format: the string format. See the printf() documentation.
1210  * @Varargs: the parameters to insert into the format string.
1211  *
1212  * Writes a formatted string into a #GString.
1213  * This is similar to the standard sprintf() function,
1214  * except that the #GString buffer automatically expands
1215  * to contain the results. The previous contents of the
1216  * #GString are destroyed.
1217  */
1218 void
1219 g_string_printf (GString *string,
1220                  const gchar *fmt,
1221                  ...)
1222 {
1223   va_list args;
1224
1225   g_string_truncate (string, 0);
1226
1227   va_start (args, fmt);
1228   g_string_append_printf_internal (string, fmt, args);
1229   va_end (args);
1230 }
1231
1232 /**
1233  * g_string_sprintfa:
1234  * @string: a #GString.
1235  * @format: the string format. See the sprintf() documentation.
1236  * @Varargs: the parameters to insert into the format string.
1237  *
1238  * Appends a formatted string onto the end of a #GString.
1239  * This function is is similar to g_string_sprintf() except that
1240  * the text is appended to the #GString.
1241  *
1242  * Deprecated: This function has been renamed to
1243  * g_string_append_printf().
1244  */
1245
1246 /**
1247  * g_string_append_printf:
1248  * @string: a #GString.
1249  * @format: the string format. See the printf() documentation.
1250  * @Varargs: the parameters to insert into the format string.
1251  *
1252  * Appends a formatted string onto the end of a #GString.
1253  * This function is is similar to g_string_printf() except
1254  * that the text is appended to the #GString.
1255  */
1256 void
1257 g_string_append_printf (GString *string,
1258                         const gchar *fmt,
1259                         ...)
1260 {
1261   va_list args;
1262
1263   va_start (args, fmt);
1264   g_string_append_printf_internal (string, fmt, args);
1265   va_end (args);
1266 }
1267
1268 #define __G_STRING_C__
1269 #include "galiasdef.c"