1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
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.
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.
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.
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/.
48 * SECTION: string_chunks
49 * @title: String Chunks
50 * @short_description: efficient storage of groups of strings
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.
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.
61 * By adding strings with g_string_chunk_insert_const() it is also
62 * possible to remove duplicates.
64 * To create a new #GStringChunk use g_string_chunk_new().
66 * To add strings to a #GStringChunk use g_string_chunk_insert().
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().
72 * To free the entire #GStringChunk use g_string_chunk_free(). It is
73 * not possible to free individual strings.
79 * An opaque data structure representing String Chunks. It should only
80 * be accessed by using the following functions.
84 GHashTable
*const_table
;
97 * @v2: a key to compare with @v1
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.
103 * Note that this function is primarily meant as a hash table comparison
104 * function. For a general-purpose, %NULL-safe string comparison function,
107 * Returns: %TRUE if the two keys match
110 g_str_equal (gconstpointer v1
,
113 const gchar
*string1
= v1
;
114 const gchar
*string2
= v2
;
116 return strcmp (string1
, string2
) == 0;
123 * Converts a string to a hash value.
124 * It can be passed to g_hash_table_new() as the @hash_func
125 * parameter, when using strings as keys in a #GHashTable.
127 * Returns: a hash value corresponding to the key
130 g_str_hash (gconstpointer v
)
132 /* 31 bit hash function */
133 const signed char *p
= v
;
137 for (p
+= 1; *p
!= '\0'; p
++)
138 h
= (h
<< 5) - h
+ *p
;
143 #define MY_MAXSIZE ((gsize)-1)
146 nearest_power (gsize base
, gsize num
)
148 if (num
> MY_MAXSIZE
/ 2)
167 * g_string_chunk_new:
168 * @size: the default size of the blocks of memory which are
169 * allocated to store the strings. If a particular string
170 * is larger than this default size, a larger block of
171 * memory will be allocated for it.
173 * Creates a new #GStringChunk.
175 * Returns: a new #GStringChunk
178 g_string_chunk_new (gsize size
)
180 GStringChunk
*new_chunk
= g_new (GStringChunk
, 1);
181 gsize actual_size
= 1;
183 actual_size
= nearest_power (1, size
);
185 new_chunk
->const_table
= NULL
;
186 new_chunk
->storage_list
= NULL
;
187 new_chunk
->storage_next
= actual_size
;
188 new_chunk
->default_size
= actual_size
;
189 new_chunk
->this_size
= actual_size
;
195 * g_string_chunk_free:
196 * @chunk: a #GStringChunk
198 * Frees all memory allocated by the #GStringChunk.
199 * After calling g_string_chunk_free() it is not safe to
200 * access any of the strings which were contained within it.
203 g_string_chunk_free (GStringChunk
*chunk
)
207 g_return_if_fail (chunk
!= NULL
);
209 if (chunk
->storage_list
)
211 for (tmp_list
= chunk
->storage_list
; tmp_list
; tmp_list
= tmp_list
->next
)
212 g_free (tmp_list
->data
);
214 g_slist_free (chunk
->storage_list
);
217 if (chunk
->const_table
)
218 g_hash_table_destroy (chunk
->const_table
);
224 * g_string_chunk_clear:
225 * @chunk: a #GStringChunk
227 * Frees all strings contained within the #GStringChunk.
228 * After calling g_string_chunk_clear() it is not safe to
229 * access any of the strings which were contained within it.
234 g_string_chunk_clear (GStringChunk
*chunk
)
238 g_return_if_fail (chunk
!= NULL
);
240 if (chunk
->storage_list
)
242 for (tmp_list
= chunk
->storage_list
; tmp_list
; tmp_list
= tmp_list
->next
)
243 g_free (tmp_list
->data
);
245 g_slist_free (chunk
->storage_list
);
247 chunk
->storage_list
= NULL
;
248 chunk
->storage_next
= chunk
->default_size
;
249 chunk
->this_size
= chunk
->default_size
;
252 if (chunk
->const_table
)
253 g_hash_table_remove_all (chunk
->const_table
);
257 * g_string_chunk_insert:
258 * @chunk: a #GStringChunk
259 * @string: the string to add
261 * Adds a copy of @string to the #GStringChunk.
262 * It returns a pointer to the new copy of the string
263 * in the #GStringChunk. The characters in the string
264 * can be changed, if necessary, though you should not
265 * change anything after the end of the string.
267 * Unlike g_string_chunk_insert_const(), this function
268 * does not check for duplicates. Also strings added
269 * with g_string_chunk_insert() will not be searched
270 * by g_string_chunk_insert_const() when looking for
273 * Returns: a pointer to the copy of @string within
277 g_string_chunk_insert (GStringChunk
*chunk
,
280 g_return_val_if_fail (chunk
!= NULL
, NULL
);
282 return g_string_chunk_insert_len (chunk
, string
, -1);
286 * g_string_chunk_insert_const:
287 * @chunk: a #GStringChunk
288 * @string: the string to add
290 * Adds a copy of @string to the #GStringChunk, unless the same
291 * string has already been added to the #GStringChunk with
292 * g_string_chunk_insert_const().
294 * This function is useful if you need to copy a large number
295 * of strings but do not want to waste space storing duplicates.
296 * But you must remember that there may be several pointers to
297 * the same string, and so any changes made to the strings
298 * should be done very carefully.
300 * Note that g_string_chunk_insert_const() will not return a
301 * pointer to a string added with g_string_chunk_insert(), even
304 * Returns: a pointer to the new or existing copy of @string
305 * within the #GStringChunk
308 g_string_chunk_insert_const (GStringChunk
*chunk
,
313 g_return_val_if_fail (chunk
!= NULL
, NULL
);
315 if (!chunk
->const_table
)
316 chunk
->const_table
= g_hash_table_new (g_str_hash
, g_str_equal
);
318 lookup
= (char*) g_hash_table_lookup (chunk
->const_table
, (gchar
*)string
);
322 lookup
= g_string_chunk_insert (chunk
, string
);
323 g_hash_table_insert (chunk
->const_table
, lookup
, lookup
);
330 * g_string_chunk_insert_len:
331 * @chunk: a #GStringChunk
332 * @string: bytes to insert
333 * @len: number of bytes of @string to insert, or -1 to insert a
334 * nul-terminated string
336 * Adds a copy of the first @len bytes of @string to the #GStringChunk.
337 * The copy is nul-terminated.
339 * Since this function does not stop at nul bytes, it is the caller's
340 * responsibility to ensure that @string has at least @len addressable
343 * The characters in the returned string can be changed, if necessary,
344 * though you should not change anything after the end of the string.
346 * Return value: a pointer to the copy of @string within the #GStringChunk
351 g_string_chunk_insert_len (GStringChunk
*chunk
,
358 g_return_val_if_fail (chunk
!= NULL
, NULL
);
361 size
= strlen (string
);
365 if ((chunk
->storage_next
+ size
+ 1) > chunk
->this_size
)
367 gsize new_size
= nearest_power (chunk
->default_size
, size
+ 1);
369 chunk
->storage_list
= g_slist_prepend (chunk
->storage_list
,
370 g_new (gchar
, new_size
));
372 chunk
->this_size
= new_size
;
373 chunk
->storage_next
= 0;
376 pos
= ((gchar
*) chunk
->storage_list
->data
) + chunk
->storage_next
;
378 *(pos
+ size
) = '\0';
380 memcpy (pos
, string
, size
);
382 chunk
->storage_next
+= size
+ 1;
390 g_string_maybe_expand (GString
* string
,
393 if (string
->len
+ len
>= string
->allocated_len
)
395 string
->allocated_len
= nearest_power (1, string
->len
+ len
+ 1);
396 string
->str
= g_realloc (string
->str
, string
->allocated_len
);
401 * g_string_sized_new:
402 * @dfl_size: the default size of the space allocated to
405 * Creates a new #GString, with enough space for @dfl_size
406 * bytes. This is useful if you are going to add a lot of
407 * text to the string and don't want it to be reallocated
410 * Returns: the new #GString
413 g_string_sized_new (gsize dfl_size
)
415 GString
*string
= g_slice_new (GString
);
417 string
->allocated_len
= 0;
421 g_string_maybe_expand (string
, MAX (dfl_size
, 2));
429 * @init: the initial text to copy into the string
431 * Creates a new #GString, initialized with the given string.
433 * Returns: the new #GString
436 g_string_new (const gchar
*init
)
440 if (init
== NULL
|| *init
== '\0')
441 string
= g_string_sized_new (2);
447 string
= g_string_sized_new (len
+ 2);
449 g_string_append_len (string
, init
, len
);
457 * @init: initial contents of the string
458 * @len: length of @init to use
460 * Creates a new #GString with @len bytes of the @init buffer.
461 * Because a length is provided, @init need not be nul-terminated,
462 * and can contain embedded nul bytes.
464 * Since this function does not stop at nul bytes, it is the caller's
465 * responsibility to ensure that @init has at least @len addressable
468 * Returns: a new #GString
471 g_string_new_len (const gchar
*init
,
477 return g_string_new (init
);
480 string
= g_string_sized_new (len
);
483 g_string_append_len (string
, init
, len
);
491 * @string: a #GString
492 * @free_segment: if %TRUE the actual character data is freed as well
494 * Frees the memory allocated for the #GString.
495 * If @free_segment is %TRUE it also frees the character data.
497 * Returns: the character data of @string
498 * (i.e. %NULL if @free_segment is %TRUE)
501 g_string_free (GString
*string
,
502 gboolean free_segment
)
506 g_return_val_if_fail (string
!= NULL
, NULL
);
510 g_free (string
->str
);
514 segment
= string
->str
;
516 g_slice_free (GString
, string
);
524 * @v2: another #GString
526 * Compares two strings for equality, returning %TRUE if they are equal.
527 * For use with #GHashTable.
529 * Returns: %TRUE if they strings are the same length and contain the
533 g_string_equal (const GString
*v
,
537 GString
*string1
= (GString
*) v
;
538 GString
*string2
= (GString
*) v2
;
539 gsize i
= string1
->len
;
541 if (i
!= string2
->len
)
559 * @str: a string to hash
561 * Creates a hash code for @str; for use with #GHashTable.
563 * Returns: hash code for @str
565 /* 31 bit hash function */
567 g_string_hash (const GString
*str
)
569 const gchar
*p
= str
->str
;
575 h
= (h
<< 5) - h
+ *p
;
584 * @string: the destination #GString. Its current contents
586 * @rval: the string to copy into @string
588 * Copies the bytes from a string into a #GString,
589 * destroying any previous contents. It is rather like
590 * the standard strcpy() function, except that you do not
591 * have to worry about having enough space to copy the string.
596 g_string_assign (GString
*string
,
599 g_return_val_if_fail (string
!= NULL
, NULL
);
600 g_return_val_if_fail (rval
!= NULL
, string
);
602 /* Make sure assigning to itself doesn't corrupt the string. */
603 if (string
->str
!= rval
)
605 /* Assigning from substring should be ok since g_string_truncate
607 g_string_truncate (string
, 0);
608 g_string_append (string
, rval
);
616 * @string: a #GString
617 * @len: the new size of @string
619 * Cuts off the end of the GString, leaving the first @len bytes.
624 g_string_truncate (GString
*string
,
627 g_return_val_if_fail (string
!= NULL
, NULL
);
629 string
->len
= MIN (len
, string
->len
);
630 string
->str
[string
->len
] = 0;
637 * @string: a #GString
638 * @len: the new length
640 * Sets the length of a #GString. If the length is less than
641 * the current length, the string will be truncated. If the
642 * length is greater than the current length, the contents
643 * of the newly added area are undefined. (However, as
644 * always, string->str[string->len] will be a nul byte.)
646 * Return value: @string
649 g_string_set_size (GString
*string
,
652 g_return_val_if_fail (string
!= NULL
, NULL
);
654 if (len
>= string
->allocated_len
)
655 g_string_maybe_expand (string
, len
- string
->len
);
658 string
->str
[len
] = 0;
664 * g_string_insert_len:
665 * @string: a #GString
666 * @pos: position in @string where insertion should
667 * happen, or -1 for at the end
668 * @val: bytes to insert
669 * @len: number of bytes of @val to insert
671 * Inserts @len bytes of @val into @string at @pos.
672 * Because @len is provided, @val may contain embedded
673 * nuls and need not be nul-terminated. If @pos is -1,
674 * bytes are inserted at the end of the string.
676 * Since this function does not stop at nul bytes, it is
677 * the caller's responsibility to ensure that @val has at
678 * least @len addressable bytes.
683 g_string_insert_len (GString
*string
,
688 g_return_val_if_fail (string
!= NULL
, NULL
);
689 g_return_val_if_fail (val
!= NULL
, string
);
697 g_return_val_if_fail (pos
<= string
->len
, string
);
699 /* Check whether val represents a substring of string. This test
700 probably violates chapter and verse of the C standards, since
701 ">=" and "<=" are only valid when val really is a substring.
702 In practice, it will work on modern archs. */
703 if (val
>= string
->str
&& val
<= string
->str
+ string
->len
)
705 gsize offset
= val
- string
->str
;
708 g_string_maybe_expand (string
, len
);
709 val
= string
->str
+ offset
;
710 /* At this point, val is valid again. */
712 /* Open up space where we are going to insert. */
713 if (pos
< string
->len
)
714 g_memmove (string
->str
+ pos
+ len
, string
->str
+ pos
, string
->len
- pos
);
716 /* Move the source part before the gap, if any. */
719 precount
= MIN (len
, pos
- offset
);
720 memcpy (string
->str
+ pos
, val
, precount
);
723 /* Move the source part after the gap, if any. */
725 memcpy (string
->str
+ pos
+ precount
,
726 val
+ /* Already moved: */ precount
+ /* Space opened up: */ len
,
731 g_string_maybe_expand (string
, len
);
733 /* If we aren't appending at the end, move a hunk
734 * of the old string to the end, opening up space
736 if (pos
< string
->len
)
737 g_memmove (string
->str
+ pos
+ len
, string
->str
+ pos
, string
->len
- pos
);
739 /* insert the new string */
741 string
->str
[pos
] = *val
;
743 memcpy (string
->str
+ pos
, val
, len
);
748 string
->str
[string
->len
] = 0;
753 #define SUB_DELIM_CHARS "!$&'()*+,;="
756 is_valid (char c
, const char *reserved_chars_allowed
)
758 if (g_ascii_isalnum (c
) ||
765 if (reserved_chars_allowed
&&
766 strchr (reserved_chars_allowed
, c
) != NULL
)
773 gunichar_ok (gunichar c
)
776 (c
!= (gunichar
) -2) &&
777 (c
!= (gunichar
) -1);
781 * g_string_append_uri_escaped:
782 * @string: a #GString
783 * @unescaped: a string
784 * @reserved_chars_allowed: a string of reserved characters allowed to be used, or %NULL
785 * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters
787 * Appends @unescaped to @string, escaped any characters that
788 * are reserved in URIs using URI-style escape sequences.
795 g_string_append_uri_escaped (GString
*string
,
796 const char *unescaped
,
797 const char *reserved_chars_allowed
,
802 static const gchar hex
[16] = "0123456789ABCDEF";
804 g_return_val_if_fail (string
!= NULL
, NULL
);
805 g_return_val_if_fail (unescaped
!= NULL
, NULL
);
807 end
= unescaped
+ strlen (unescaped
);
809 while ((c
= *unescaped
) != 0)
811 if (c
>= 0x80 && allow_utf8
&&
812 gunichar_ok (g_utf8_get_char_validated (unescaped
, end
- unescaped
)))
814 int len
= g_utf8_skip
[c
];
815 g_string_append_len (string
, unescaped
, len
);
818 else if (is_valid (c
, reserved_chars_allowed
))
820 g_string_append_c (string
, c
);
825 g_string_append_c (string
, '%');
826 g_string_append_c (string
, hex
[((guchar
)c
) >> 4]);
827 g_string_append_c (string
, hex
[((guchar
)c
) & 0xf]);
837 * @string: a #GString
838 * @val: the string to append onto the end of @string
840 * Adds a string onto the end of a #GString, expanding
846 g_string_append (GString
*string
,
849 g_return_val_if_fail (string
!= NULL
, NULL
);
850 g_return_val_if_fail (val
!= NULL
, string
);
852 return g_string_insert_len (string
, -1, val
, -1);
856 * g_string_append_len:
857 * @string: a #GString
858 * @val: bytes to append
859 * @len: number of bytes of @val to use
861 * Appends @len bytes of @val to @string. Because @len is
862 * provided, @val may contain embedded nuls and need not
865 * Since this function does not stop at nul bytes, it is
866 * the caller's responsibility to ensure that @val has at
867 * least @len addressable bytes.
872 g_string_append_len (GString
*string
,
876 g_return_val_if_fail (string
!= NULL
, NULL
);
877 g_return_val_if_fail (len
== 0 || val
!= NULL
, string
);
879 return g_string_insert_len (string
, -1, val
, len
);
884 * @string: a #GString
885 * @c: the byte to append onto the end of @string
887 * Adds a byte onto the end of a #GString, expanding
892 #undef g_string_append_c
894 g_string_append_c (GString
*string
,
897 g_return_val_if_fail (string
!= NULL
, NULL
);
899 return g_string_insert_c (string
, -1, c
);
903 * g_string_append_unichar:
904 * @string: a #GString
905 * @wc: a Unicode character
907 * Converts a Unicode character into UTF-8, and appends it
910 * Return value: @string
913 g_string_append_unichar (GString
*string
,
916 g_return_val_if_fail (string
!= NULL
, NULL
);
918 return g_string_insert_unichar (string
, -1, wc
);
923 * @string: a #GString
924 * @val: the string to prepend on the start of @string
926 * Adds a string on to the start of a #GString,
927 * expanding it if necessary.
932 g_string_prepend (GString
*string
,
935 g_return_val_if_fail (string
!= NULL
, NULL
);
936 g_return_val_if_fail (val
!= NULL
, string
);
938 return g_string_insert_len (string
, 0, val
, -1);
942 * g_string_prepend_len:
943 * @string: a #GString
944 * @val: bytes to prepend
945 * @len: number of bytes in @val to prepend
947 * Prepends @len bytes of @val to @string.
948 * Because @len is provided, @val may contain
949 * embedded nuls and need not be nul-terminated.
951 * Since this function does not stop at nul bytes,
952 * it is the caller's responsibility to ensure that
953 * @val has at least @len addressable bytes.
958 g_string_prepend_len (GString
*string
,
962 g_return_val_if_fail (string
!= NULL
, NULL
);
963 g_return_val_if_fail (val
!= NULL
, string
);
965 return g_string_insert_len (string
, 0, val
, len
);
969 * g_string_prepend_c:
970 * @string: a #GString
971 * @c: the byte to prepend on the start of the #GString
973 * Adds a byte onto the start of a #GString,
974 * expanding it if necessary.
979 g_string_prepend_c (GString
*string
,
982 g_return_val_if_fail (string
!= NULL
, NULL
);
984 return g_string_insert_c (string
, 0, c
);
988 * g_string_prepend_unichar:
989 * @string: a #GString
990 * @wc: a Unicode character
992 * Converts a Unicode character into UTF-8, and prepends it
995 * Return value: @string
998 g_string_prepend_unichar (GString
*string
,
1001 g_return_val_if_fail (string
!= NULL
, NULL
);
1003 return g_string_insert_unichar (string
, 0, wc
);
1008 * @string: a #GString
1009 * @pos: the position to insert the copy of the string
1010 * @val: the string to insert
1012 * Inserts a copy of a string into a #GString,
1013 * expanding it if necessary.
1018 g_string_insert (GString
*string
,
1022 g_return_val_if_fail (string
!= NULL
, NULL
);
1023 g_return_val_if_fail (val
!= NULL
, string
);
1025 g_return_val_if_fail (pos
<= string
->len
, string
);
1027 return g_string_insert_len (string
, pos
, val
, -1);
1031 * g_string_insert_c:
1032 * @string: a #GString
1033 * @pos: the position to insert the byte
1034 * @c: the byte to insert
1036 * Inserts a byte into a #GString, expanding it if necessary.
1041 g_string_insert_c (GString
*string
,
1045 g_return_val_if_fail (string
!= NULL
, NULL
);
1047 g_string_maybe_expand (string
, 1);
1052 g_return_val_if_fail (pos
<= string
->len
, string
);
1054 /* If not just an append, move the old stuff */
1055 if (pos
< string
->len
)
1056 g_memmove (string
->str
+ pos
+ 1, string
->str
+ pos
, string
->len
- pos
);
1058 string
->str
[pos
] = c
;
1062 string
->str
[string
->len
] = 0;
1068 * g_string_insert_unichar:
1069 * @string: a #GString
1070 * @pos: the position at which to insert character, or -1 to
1071 * append at the end of the string
1072 * @wc: a Unicode character
1074 * Converts a Unicode character into UTF-8, and insert it
1075 * into the string at the given position.
1077 * Return value: @string
1080 g_string_insert_unichar (GString
*string
,
1084 gint charlen
, first
, i
;
1087 g_return_val_if_fail (string
!= NULL
, NULL
);
1089 /* Code copied from g_unichar_to_utf() */
1095 else if (wc
< 0x800)
1100 else if (wc
< 0x10000)
1105 else if (wc
< 0x200000)
1110 else if (wc
< 0x4000000)
1120 /* End of copied code */
1122 g_string_maybe_expand (string
, charlen
);
1127 g_return_val_if_fail (pos
<= string
->len
, string
);
1129 /* If not just an append, move the old stuff */
1130 if (pos
< string
->len
)
1131 g_memmove (string
->str
+ pos
+ charlen
, string
->str
+ pos
, string
->len
- pos
);
1133 dest
= string
->str
+ pos
;
1134 /* Code copied from g_unichar_to_utf() */
1135 for (i
= charlen
- 1; i
> 0; --i
)
1137 dest
[i
] = (wc
& 0x3f) | 0x80;
1140 dest
[0] = wc
| first
;
1141 /* End of copied code */
1143 string
->len
+= charlen
;
1145 string
->str
[string
->len
] = 0;
1151 * g_string_overwrite:
1152 * @string: a #GString
1153 * @pos: the position at which to start overwriting
1154 * @val: the string that will overwrite the @string starting at @pos
1156 * Overwrites part of a string, lengthening it if necessary.
1158 * Return value: @string
1163 g_string_overwrite (GString
*string
,
1167 g_return_val_if_fail (val
!= NULL
, string
);
1168 return g_string_overwrite_len (string
, pos
, val
, strlen (val
));
1172 * g_string_overwrite_len:
1173 * @string: a #GString
1174 * @pos: the position at which to start overwriting
1175 * @val: the string that will overwrite the @string starting at @pos
1176 * @len: the number of bytes to write from @val
1178 * Overwrites part of a string, lengthening it if necessary.
1179 * This function will work with embedded nuls.
1181 * Return value: @string
1186 g_string_overwrite_len (GString
*string
,
1193 g_return_val_if_fail (string
!= NULL
, NULL
);
1198 g_return_val_if_fail (val
!= NULL
, string
);
1199 g_return_val_if_fail (pos
<= string
->len
, string
);
1206 if (end
> string
->len
)
1207 g_string_maybe_expand (string
, end
- string
->len
);
1209 memcpy (string
->str
+ pos
, val
, len
);
1211 if (end
> string
->len
)
1213 string
->str
[end
] = '\0';
1222 * @string: a #GString
1223 * @pos: the position of the content to remove
1224 * @len: the number of bytes to remove, or -1 to remove all
1227 * Removes @len bytes from a #GString, starting at position @pos.
1228 * The rest of the #GString is shifted down to fill the gap.
1233 g_string_erase (GString
*string
,
1237 g_return_val_if_fail (string
!= NULL
, NULL
);
1238 g_return_val_if_fail (pos
>= 0, string
);
1239 g_return_val_if_fail (pos
<= string
->len
, string
);
1242 len
= string
->len
- pos
;
1245 g_return_val_if_fail (pos
+ len
<= string
->len
, string
);
1247 if (pos
+ len
< string
->len
)
1248 g_memmove (string
->str
+ pos
, string
->str
+ pos
+ len
, string
->len
- (pos
+ len
));
1253 string
->str
[string
->len
] = 0;
1259 * g_string_ascii_down:
1260 * @string: a GString
1262 * Converts all upper case ASCII letters to lower case ASCII letters.
1264 * Return value: passed-in @string pointer, with all the upper case
1265 * characters converted to lower case in place, with
1266 * semantics that exactly match g_ascii_tolower().
1269 g_string_ascii_down (GString
*string
)
1274 g_return_val_if_fail (string
!= NULL
, NULL
);
1281 *s
= g_ascii_tolower (*s
);
1290 * g_string_ascii_up:
1291 * @string: a GString
1293 * Converts all lower case ASCII letters to upper case ASCII letters.
1295 * Return value: passed-in @string pointer, with all the lower case
1296 * characters converted to upper case in place, with
1297 * semantics that exactly match g_ascii_toupper().
1300 g_string_ascii_up (GString
*string
)
1305 g_return_val_if_fail (string
!= NULL
, NULL
);
1312 *s
= g_ascii_toupper (*s
);
1322 * @string: a #GString
1324 * Converts a #GString to lowercase.
1326 * Returns: the #GString.
1328 * Deprecated:2.2: This function uses the locale-specific
1329 * tolower() function, which is almost never the right thing.
1330 * Use g_string_ascii_down() or g_utf8_strdown() instead.
1333 g_string_down (GString
*string
)
1338 g_return_val_if_fail (string
!= NULL
, NULL
);
1341 s
= (guchar
*) string
->str
;
1356 * @string: a #GString
1358 * Converts a #GString to uppercase.
1360 * Return value: @string
1362 * Deprecated:2.2: This function uses the locale-specific
1363 * toupper() function, which is almost never the right thing.
1364 * Use g_string_ascii_up() or g_utf8_strup() instead.
1367 g_string_up (GString
*string
)
1372 g_return_val_if_fail (string
!= NULL
, NULL
);
1375 s
= (guchar
*) string
->str
;
1389 * g_string_append_vprintf:
1390 * @string: a #GString
1391 * @format: the string format. See the printf() documentation
1392 * @args: the list of arguments to insert in the output
1394 * Appends a formatted string onto the end of a #GString.
1395 * This function is similar to g_string_append_printf()
1396 * except that the arguments to the format string are passed
1402 g_string_append_vprintf (GString
*string
,
1403 const gchar
*format
,
1409 g_return_if_fail (string
!= NULL
);
1410 g_return_if_fail (format
!= NULL
);
1412 len
= g_vasprintf (&buf
, format
, args
);
1416 g_string_maybe_expand (string
, len
);
1417 memcpy (string
->str
+ string
->len
, buf
, len
+ 1);
1425 * @string: a #GString
1426 * @format: the string format. See the printf() documentation
1427 * @args: the parameters to insert into the format string
1429 * Writes a formatted string into a #GString.
1430 * This function is similar to g_string_printf() except that
1431 * the arguments to the format string are passed as a va_list.
1436 g_string_vprintf (GString
*string
,
1437 const gchar
*format
,
1440 g_string_truncate (string
, 0);
1441 g_string_append_vprintf (string
, format
, args
);
1446 * @string: a #GString
1447 * @format: the string format. See the sprintf() documentation
1448 * @Varargs: the parameters to insert into the format string
1450 * Writes a formatted string into a #GString.
1451 * This is similar to the standard sprintf() function,
1452 * except that the #GString buffer automatically expands
1453 * to contain the results. The previous contents of the
1454 * #GString are destroyed.
1456 * Deprecated: This function has been renamed to g_string_printf().
1461 * @string: a #GString
1462 * @format: the string format. See the printf() documentation
1463 * @Varargs: the parameters to insert into the format string
1465 * Writes a formatted string into a #GString.
1466 * This is similar to the standard sprintf() function,
1467 * except that the #GString buffer automatically expands
1468 * to contain the results. The previous contents of the
1469 * #GString are destroyed.
1472 g_string_printf (GString
*string
,
1473 const gchar
*format
,
1478 g_string_truncate (string
, 0);
1480 va_start (args
, format
);
1481 g_string_append_vprintf (string
, format
, args
);
1486 * g_string_sprintfa:
1487 * @string: a #GString
1488 * @format: the string format. See the sprintf() documentation
1489 * @Varargs: the parameters to insert into the format string
1491 * Appends a formatted string onto the end of a #GString.
1492 * This function is similar to g_string_sprintf() except that
1493 * the text is appended to the #GString.
1495 * Deprecated: This function has been renamed to g_string_append_printf()
1499 * g_string_append_printf:
1500 * @string: a #GString
1501 * @format: the string format. See the printf() documentation
1502 * @Varargs: the parameters to insert into the format string
1504 * Appends a formatted string onto the end of a #GString.
1505 * This function is similar to g_string_printf() except
1506 * that the text is appended to the #GString.
1509 g_string_append_printf (GString
*string
,
1510 const gchar
*format
,
1515 va_start (args
, format
);
1516 g_string_append_vprintf (string
, format
, args
);
1520 #define __G_STRING_C__
1521 #include "galiasdef.c"