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