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