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 #define SUB_DELIM_CHARS  "!$&'()*+,;="
 717
 718 static gboolean
 719 is_valid (char c, const char *reserved_chars_allowed)
 720 {
 721   if (g_ascii_isalnum (c) ||
 722       c == '-' ||
 723       c == '.' ||
 724       c == '_' ||
 725       c == '~')
 726     return TRUE;
 727
 728   if (reserved_chars_allowed &&
 729       strchr (reserved_chars_allowed, c) != NULL)
 730     return TRUE;
 731
 732   return FALSE;
 733 }
 734
 735 static gboolean
 736 gunichar_ok (gunichar c)
 737 {
 738   return
 739     (c != (gunichar) -2) &&
 740     (c != (gunichar) -1);
 741 }
 742
 743 /**
 744  * g_string_append_uri_escaped:
 745  * @string: a #GString
 746  * @unescaped: a string
 747  * @reserved_chars_allowed: a string of reserved characters allowed to be used
 748  * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters
 749  *
 750  * Appends @unescaped to @string, escaped any characters that
 751  * are reserved in URIs using URI-style escape sequences.
 752  *
 753  * Returns: @string
 754  *
 755  * Since: 2.16
 756  **/
 757 GString *
 758 g_string_append_uri_escaped (GString *string,
 759                              const char *unescaped,
 760                              const char *reserved_chars_allowed,
 761                              gboolean allow_utf8)
 762 {
 763   unsigned char c;
 764   const char *end;
 765   static const gchar hex[16] = "0123456789ABCDEF";
 766
 767   g_return_val_if_fail (string != NULL, NULL);
 768   g_return_val_if_fail (unescaped != NULL, NULL);
 769
 770   end = unescaped + strlen (unescaped);
 771
 772   while ((c = *unescaped) != 0)
 773     {
 774       if (c >= 0x80 && allow_utf8 &&
 775           gunichar_ok (g_utf8_get_char_validated (unescaped, end - unescaped)))
 776         {
 777           int len = g_utf8_skip [c];
 778           g_string_append_len (string, unescaped, len);
 779           unescaped += len;
 780         }
 781       else if (is_valid (c, reserved_chars_allowed))
 782         {
 783           g_string_append_c (string, c);
 784           unescaped++;
 785         }
 786       else
 787         {
 788           g_string_append_c (string, '%');
 789           g_string_append_c (string, hex[((guchar)c) >> 4]);
 790           g_string_append_c (string, hex[((guchar)c) & 0xf]);
 791           unescaped++;
 792         }
 793     }
 794
 795   return string;
 796 }
 797
 798 /**
 799  * g_string_append:
 800  * @string: a #GString
 801  * @val: the string to append onto the end of @string
 802  *
 803  * Adds a string onto the end of a #GString, expanding
 804  * it if necessary.
 805  *
 806  * Returns: @string
 807  */
 808 GString*
 809 g_string_append (GString     *string,
 810                  const gchar *val)
 811 {
 812   g_return_val_if_fail (string != NULL, NULL);
 813   g_return_val_if_fail (val != NULL, string);
 814
 815   return g_string_insert_len (string, -1, val, -1);
 816 }
 817
 818 /**
 819  * g_string_append_len:
 820  * @string: a #GString
 821  * @val: bytes to append
 822  * @len: number of bytes of @val to use
 823  *
 824  * Appends @len bytes of @val to @string. Because @len is
 825  * provided, @val may contain embedded nuls and need not
 826  * be nul-terminated.
 827  *
 828  * Since this function does not stop at nul bytes, it is
 829  * the caller's responsibility to ensure that @val has at
 830  * least @len addressable bytes.
 831  *
 832  * Returns: @string
 833  */
 834 GString*
 835 g_string_append_len (GString     *string,
 836                      const gchar *val,
 837                      gssize       len)
 838 {
 839   g_return_val_if_fail (string != NULL, NULL);
 840   g_return_val_if_fail (val != NULL, string);
 841
 842   return g_string_insert_len (string, -1, val, len);
 843 }
 844
 845 /**
 846  * g_string_append_c:
 847  * @string: a #GString
 848  * @c: the byte to append onto the end of @string
 849  *
 850  * Adds a byte onto the end of a #GString, expanding
 851  * it if necessary.
 852  *
 853  * Returns: @string
 854  */
 855 #undef g_string_append_c
 856 GString*
 857 g_string_append_c (GString *string,
 858                    gchar    c)
 859 {
 860   g_return_val_if_fail (string != NULL, NULL);
 861
 862   return g_string_insert_c (string, -1, c);
 863 }
 864
 865 /**
 866  * g_string_append_unichar:
 867  * @string: a #GString
 868  * @wc: a Unicode character
 869  *
 870  * Converts a Unicode character into UTF-8, and appends it
 871  * to the string.
 872  *
 873  * Return value: @string
 874  **/
 875 GString*
 876 g_string_append_unichar (GString  *string,
 877                          gunichar  wc)
 878 {
 879   g_return_val_if_fail (string != NULL, NULL);
 880
 881   return g_string_insert_unichar (string, -1, wc);
 882 }
 883
 884 /**
 885  * g_string_prepend:
 886  * @string: a #GString
 887  * @val: the string to prepend on the start of @string
 888  *
 889  * Adds a string on to the start of a #GString,
 890  * expanding it if necessary.
 891  *
 892  * Returns: @string
 893  */
 894 GString*
 895 g_string_prepend (GString     *string,
 896                   const gchar *val)
 897 {
 898   g_return_val_if_fail (string != NULL, NULL);
 899   g_return_val_if_fail (val != NULL, string);
 900
 901   return g_string_insert_len (string, 0, val, -1);
 902 }
 903
 904 /**
 905  * g_string_prepend_len:
 906  * @string: a #GString
 907  * @val: bytes to prepend
 908  * @len: number of bytes in @val to prepend
 909  *
 910  * Prepends @len bytes of @val to @string.
 911  * Because @len is provided, @val may contain
 912  * embedded nuls and need not be nul-terminated.
 913  *
 914  * Since this function does not stop at nul bytes,
 915  * it is the caller's responsibility to ensure that
 916  * @val has at least @len addressable bytes.
 917  *
 918  * Returns: @string
 919  */
 920 GString*
 921 g_string_prepend_len (GString     *string,
 922                       const gchar *val,
 923                       gssize       len)
 924 {
 925   g_return_val_if_fail (string != NULL, NULL);
 926   g_return_val_if_fail (val != NULL, string);
 927
 928   return g_string_insert_len (string, 0, val, len);
 929 }
 930
 931 /**
 932  * g_string_prepend_c:
 933  * @string: a #GString
 934  * @c: the byte to prepend on the start of the #GString
 935  *
 936  * Adds a byte onto the start of a #GString,
 937  * expanding it if necessary.
 938  *
 939  * Returns: @string
 940  */
 941 GString*
 942 g_string_prepend_c (GString *string,
 943                     gchar    c)
 944 {
 945   g_return_val_if_fail (string != NULL, NULL);
 946
 947   return g_string_insert_c (string, 0, c);
 948 }
 949
 950 /**
 951  * g_string_prepend_unichar:
 952  * @string: a #GString
 953  * @wc: a Unicode character
 954  *
 955  * Converts a Unicode character into UTF-8, and prepends it
 956  * to the string.
 957  *
 958  * Return value: @string
 959  **/
 960 GString*
 961 g_string_prepend_unichar (GString  *string,
 962                           gunichar  wc)
 963 {
 964   g_return_val_if_fail (string != NULL, NULL);
 965
 966   return g_string_insert_unichar (string, 0, wc);
 967 }
 968
 969 /**
 970  * g_string_insert:
 971  * @string: a #GString
 972  * @pos: the position to insert the copy of the string
 973  * @val: the string to insert
 974  *
 975  * Inserts a copy of a string into a #GString,
 976  * expanding it if necessary.
 977  *
 978  * Returns: @string
 979  */
 980 GString*
 981 g_string_insert (GString     *string,
 982                  gssize       pos,
 983                  const gchar *val)
 984 {
 985   g_return_val_if_fail (string != NULL, NULL);
 986   g_return_val_if_fail (val != NULL, string);
 987   if (pos >= 0)
 988     g_return_val_if_fail (pos <= string->len, string);
 989
 990   return g_string_insert_len (string, pos, val, -1);
 991 }
 992
 993 /**
 994  * g_string_insert_c:
 995  * @string: a #GString
 996  * @pos: the position to insert the byte
 997  * @c: the byte to insert
 998  *
 999  * Inserts a byte into a #GString, expanding it if necessary.
1000  *
1001  * Returns: @string
1002  */
1003 GString*
1004 g_string_insert_c (GString *string,
1005                    gssize   pos,
1006                    gchar    c)
1007 {
1008   g_return_val_if_fail (string != NULL, NULL);
1009
1010   g_string_maybe_expand (string, 1);
1011
1012   if (pos < 0)
1013     pos = string->len;
1014   else
1015     g_return_val_if_fail (pos <= string->len, string);
1016
1017   /* If not just an append, move the old stuff */
1018   if (pos < string->len)
1019     g_memmove (string->str + pos + 1, string->str + pos, string->len - pos);
1020
1021   string->str[pos] = c;
1022
1023   string->len += 1;
1024
1025   string->str[string->len] = 0;
1026
1027   return string;
1028 }
1029
1030 /**
1031  * g_string_insert_unichar:
1032  * @string: a #GString
1033  * @pos: the position at which to insert character, or -1 to
1034  *       append at the end of the string
1035  * @wc: a Unicode character
1036  *
1037  * Converts a Unicode character into UTF-8, and insert it
1038  * into the string at the given position.
1039  *
1040  * Return value: @string
1041  **/
1042 GString*
1043 g_string_insert_unichar (GString *string,
1044                          gssize   pos,
1045                          gunichar wc)
1046 {
1047   gint charlen, first, i;
1048   gchar *dest;
1049
1050   g_return_val_if_fail (string != NULL, NULL);
1051
1052   /* Code copied from g_unichar_to_utf() */
1053   if (wc < 0x80)
1054     {
1055       first = 0;
1056       charlen = 1;
1057     }
1058   else if (wc < 0x800)
1059     {
1060       first = 0xc0;
1061       charlen = 2;
1062     }
1063   else if (wc < 0x10000)
1064     {
1065       first = 0xe0;
1066       charlen = 3;
1067     }
1068    else if (wc < 0x200000)
1069     {
1070       first = 0xf0;
1071       charlen = 4;
1072     }
1073   else if (wc < 0x4000000)
1074     {
1075       first = 0xf8;
1076       charlen = 5;
1077     }
1078   else
1079     {
1080       first = 0xfc;
1081       charlen = 6;
1082     }
1083   /* End of copied code */
1084
1085   g_string_maybe_expand (string, charlen);
1086
1087   if (pos < 0)
1088     pos = string->len;
1089   else
1090     g_return_val_if_fail (pos <= string->len, string);
1091
1092   /* If not just an append, move the old stuff */
1093   if (pos < string->len)
1094     g_memmove (string->str + pos + charlen, string->str + pos, string->len - pos);
1095
1096   dest = string->str + pos;
1097   /* Code copied from g_unichar_to_utf() */
1098   for (i = charlen - 1; i > 0; --i)
1099     {
1100       dest[i] = (wc & 0x3f) | 0x80;
1101       wc >>= 6;
1102     }
1103   dest[0] = wc | first;
1104   /* End of copied code */
1105
1106   string->len += charlen;
1107
1108   string->str[string->len] = 0;
1109
1110   return string;
1111 }
1112
1113 /**
1114  * g_string_overwrite:
1115  * @string: a #GString
1116  * @pos: the position at which to start overwriting
1117  * @val: the string that will overwrite the @string starting at @pos
1118  *
1119  * Overwrites part of a string, lengthening it if necessary.
1120  *
1121  * Return value: @string
1122  *
1123  * Since: 2.14
1124  **/
1125 GString *
1126 g_string_overwrite (GString     *string,
1127                     gsize        pos,
1128                     const gchar *val)
1129 {
1130   g_return_val_if_fail (val != NULL, string);
1131   return g_string_overwrite_len (string, pos, val, strlen (val));
1132 }
1133
1134 /**
1135  * g_string_overwrite_len:
1136  * @string: a #GString
1137  * @pos: the position at which to start overwriting
1138  * @val: the string that will overwrite the @string starting at @pos
1139  * @len: the number of bytes to write from @val
1140  *
1141  * Overwrites part of a string, lengthening it if necessary.
1142  * This function will work with embedded nuls.
1143  *
1144  * Return value: @string
1145  *
1146  * Since: 2.14
1147  **/
1148 GString *
1149 g_string_overwrite_len (GString     *string,
1150                         gsize        pos,
1151                         const gchar *val,
1152                         gssize       len)
1153 {
1154   gsize end;
1155
1156   g_return_val_if_fail (string != NULL, NULL);
1157
1158   if (!len)
1159     return string;
1160
1161   g_return_val_if_fail (val != NULL, string);
1162   g_return_val_if_fail (pos <= string->len, string);
1163
1164   if (len < 0)
1165     len = strlen (val);
1166
1167   end = pos + len;
1168
1169   if (end > string->len)
1170     g_string_maybe_expand (string, end - string->len);
1171
1172   memcpy (string->str + pos, val, len);
1173
1174   if (end > string->len)
1175     {
1176       string->str[end] = '\0';
1177       string->len = end;
1178     }
1179
1180   return string;
1181 }
1182
1183 /**
1184  * g_string_erase:
1185  * @string: a #GString
1186  * @pos: the position of the content to remove
1187  * @len: the number of bytes to remove, or -1 to remove all
1188  *       following bytes
1189  *
1190  * Removes @len bytes from a #GString, starting at position @pos.
1191  * The rest of the #GString is shifted down to fill the gap.
1192  *
1193  * Returns: @string
1194  */
1195 GString*
1196 g_string_erase (GString *string,
1197                 gssize   pos,
1198                 gssize   len)
1199 {
1200   g_return_val_if_fail (string != NULL, NULL);
1201   g_return_val_if_fail (pos >= 0, string);
1202   g_return_val_if_fail (pos <= string->len, string);
1203
1204   if (len < 0)
1205     len = string->len - pos;
1206   else
1207     {
1208       g_return_val_if_fail (pos + len <= string->len, string);
1209
1210       if (pos + len < string->len)
1211         g_memmove (string->str + pos, string->str + pos + len, string->len - (pos + len));
1212     }
1213
1214   string->len -= len;
1215
1216   string->str[string->len] = 0;
1217
1218   return string;
1219 }
1220
1221 /**
1222  * g_string_ascii_down:
1223  * @string: a GString
1224  *
1225  * Converts all upper case ASCII letters to lower case ASCII letters.
1226  *
1227  * Return value: passed-in @string pointer, with all the upper case
1228  *               characters converted to lower case in place, with
1229  *               semantics that exactly match g_ascii_tolower().
1230  **/
1231 GString*
1232 g_string_ascii_down (GString *string)
1233 {
1234   gchar *s;
1235   gint n;
1236
1237   g_return_val_if_fail (string != NULL, NULL);
1238
1239   n = string->len;
1240   s = string->str;
1241
1242   while (n)
1243     {
1244       *s = g_ascii_tolower (*s);
1245       s++;
1246       n--;
1247     }
1248
1249   return string;
1250 }
1251
1252 /**
1253  * g_string_ascii_up:
1254  * @string: a GString
1255  *
1256  * Converts all lower case ASCII letters to upper case ASCII letters.
1257  *
1258  * Return value: passed-in @string pointer, with all the lower case
1259  *               characters converted to upper case in place, with
1260  *               semantics that exactly match g_ascii_toupper().
1261  **/
1262 GString*
1263 g_string_ascii_up (GString *string)
1264 {
1265   gchar *s;
1266   gint n;
1267
1268   g_return_val_if_fail (string != NULL, NULL);
1269
1270   n = string->len;
1271   s = string->str;
1272
1273   while (n)
1274     {
1275       *s = g_ascii_toupper (*s);
1276       s++;
1277       n--;
1278     }
1279
1280   return string;
1281 }
1282
1283 /**
1284  * g_string_down:
1285  * @string: a #GString
1286  *
1287  * Converts a #GString to lowercase.
1288  *
1289  * Returns: the #GString.
1290  *
1291  * Deprecated:2.2: This function uses the locale-specific
1292  *   tolower() function, which is almost never the right thing.
1293  *   Use g_string_ascii_down() or g_utf8_strdown() instead.
1294  */
1295 GString*
1296 g_string_down (GString *string)
1297 {
1298   guchar *s;
1299   glong n;
1300
1301   g_return_val_if_fail (string != NULL, NULL);
1302
1303   n = string->len;
1304   s = (guchar *) string->str;
1305
1306   while (n)
1307     {
1308       if (isupper (*s))
1309         *s = tolower (*s);
1310       s++;
1311       n--;
1312     }
1313
1314   return string;
1315 }
1316
1317 /**
1318  * g_string_up:
1319  * @string: a #GString
1320  *
1321  * Converts a #GString to uppercase.
1322  *
1323  * Return value: @string
1324  *
1325  * Deprecated:2.2: This function uses the locale-specific
1326  *   toupper() function, which is almost never the right thing.
1327  *   Use g_string_ascii_up() or g_utf8_strup() instead.
1328  **/
1329 GString*
1330 g_string_up (GString *string)
1331 {
1332   guchar *s;
1333   glong n;
1334
1335   g_return_val_if_fail (string != NULL, NULL);
1336
1337   n = string->len;
1338   s = (guchar *) string->str;
1339
1340   while (n)
1341     {
1342       if (islower (*s))
1343         *s = toupper (*s);
1344       s++;
1345       n--;
1346     }
1347
1348   return string;
1349 }
1350
1351 /**
1352  * g_string_append_vprintf:
1353  * @string: a #GString
1354  * @format: the string format. See the printf() documentation
1355  * @args: the list of arguments to insert in the output
1356  *
1357  * Appends a formatted string onto the end of a #GString.
1358  * This function is similar to g_string_append_printf()
1359  * except that the arguments to the format string are passed
1360  * as a va_list.
1361  *
1362  * Since: 2.14
1363  */
1364 void
1365 g_string_append_vprintf (GString     *string,
1366                          const gchar *format,
1367                          va_list      args)
1368 {
1369   gchar *buf;
1370   gint len;
1371
1372   g_return_if_fail (string != NULL);
1373   g_return_if_fail (format != NULL);
1374
1375   len = g_vasprintf (&buf, format, args);
1376
1377   if (len >= 0)
1378     {
1379       g_string_maybe_expand (string, len);
1380       memcpy (string->str + string->len, buf, len + 1);
1381       string->len += len;
1382       g_free (buf);
1383     }
1384 }
1385
1386 /**
1387  * g_string_vprintf:
1388  * @string: a #GString
1389  * @format: the string format. See the printf() documentation
1390  * @args: the parameters to insert into the format string
1391  *
1392  * Writes a formatted string into a #GString.
1393  * This function is similar to g_string_printf() except that
1394  * the arguments to the format string are passed as a va_list.
1395  *
1396  * Since: 2.14
1397  */
1398 void
1399 g_string_vprintf (GString     *string,
1400                   const gchar *format,
1401                   va_list      args)
1402 {
1403   g_string_truncate (string, 0);
1404   g_string_append_vprintf (string, format, args);
1405 }
1406
1407 /**
1408  * g_string_sprintf:
1409  * @string: a #GString
1410  * @format: the string format. See the sprintf() documentation
1411  * @Varargs: the parameters to insert into the format string
1412  *
1413  * Writes a formatted string into a #GString.
1414  * This is similar to the standard sprintf() function,
1415  * except that the #GString buffer automatically expands
1416  * to contain the results. The previous contents of the
1417  * #GString are destroyed.
1418  *
1419  * Deprecated: This function has been renamed to g_string_printf().
1420  */
1421
1422 /**
1423  * g_string_printf:
1424  * @string: a #GString
1425  * @format: the string format. See the printf() documentation
1426  * @Varargs: the parameters to insert into the format string
1427  *
1428  * Writes a formatted string into a #GString.
1429  * This is similar to the standard sprintf() function,
1430  * except that the #GString buffer automatically expands
1431  * to contain the results. The previous contents of the
1432  * #GString are destroyed.
1433  */
1434 void
1435 g_string_printf (GString     *string,
1436                  const gchar *format,
1437                  ...)
1438 {
1439   va_list args;
1440
1441   g_string_truncate (string, 0);
1442
1443   va_start (args, format);
1444   g_string_append_vprintf (string, format, args);
1445   va_end (args);
1446 }
1447
1448 /**
1449  * g_string_sprintfa:
1450  * @string: a #GString
1451  * @format: the string format. See the sprintf() documentation
1452  * @Varargs: the parameters to insert into the format string
1453  *
1454  * Appends a formatted string onto the end of a #GString.
1455  * This function is similar to g_string_sprintf() except that
1456  * the text is appended to the #GString.
1457  *
1458  * Deprecated: This function has been renamed to g_string_append_printf()
1459  */
1460
1461 /**
1462  * g_string_append_printf:
1463  * @string: a #GString
1464  * @format: the string format. See the printf() documentation
1465  * @Varargs: the parameters to insert into the format string
1466  *
1467  * Appends a formatted string onto the end of a #GString.
1468  * This function is similar to g_string_printf() except
1469  * that the text is appended to the #GString.
1470  */
1471 void
1472 g_string_append_printf (GString     *string,
1473                         const gchar *format,
1474                         ...)
1475 {
1476   va_list args;
1477
1478   va_start (args, format);
1479   g_string_append_vprintf (string, format, args);
1480   va_end (args);
1481 }
1482
1483 #define __G_STRING_C__
1484 #include "galiasdef.c"