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;
136 for (p = v; *p != '\0'; p++)
137 h = (h << 5) - h + *p;
142 #define MY_MAXSIZE ((gsize)-1)
145 nearest_power (gsize base, gsize num)
147 if (num > MY_MAXSIZE / 2)
166 * g_string_chunk_new:
167 * @size: the default size of the blocks of memory which are
168 * allocated to store the strings. If a particular string
169 * is larger than this default size, a larger block of
170 * memory will be allocated for it.
172 * Creates a new #GStringChunk.
174 * Returns: a new #GStringChunk
177 g_string_chunk_new (gsize size)
179 GStringChunk *new_chunk = g_new (GStringChunk, 1);
180 gsize actual_size = 1;
182 actual_size = nearest_power (1, size);
184 new_chunk->const_table = NULL;
185 new_chunk->storage_list = NULL;
186 new_chunk->storage_next = actual_size;
187 new_chunk->default_size = actual_size;
188 new_chunk->this_size = actual_size;
194 * g_string_chunk_free:
195 * @chunk: a #GStringChunk
197 * Frees all memory allocated by the #GStringChunk.
198 * After calling g_string_chunk_free() it is not safe to
199 * access any of the strings which were contained within it.
202 g_string_chunk_free (GStringChunk *chunk)
206 g_return_if_fail (chunk != NULL);
208 if (chunk->storage_list)
210 for (tmp_list = chunk->storage_list; tmp_list; tmp_list = tmp_list->next)
211 g_free (tmp_list->data);
213 g_slist_free (chunk->storage_list);
216 if (chunk->const_table)
217 g_hash_table_destroy (chunk->const_table);
223 * g_string_chunk_clear:
224 * @chunk: a #GStringChunk
226 * Frees all strings contained within the #GStringChunk.
227 * After calling g_string_chunk_clear() it is not safe to
228 * access any of the strings which were contained within it.
233 g_string_chunk_clear (GStringChunk *chunk)
237 g_return_if_fail (chunk != NULL);
239 if (chunk->storage_list)
241 for (tmp_list = chunk->storage_list; tmp_list; tmp_list = tmp_list->next)
242 g_free (tmp_list->data);
244 g_slist_free (chunk->storage_list);
246 chunk->storage_list = NULL;
247 chunk->storage_next = chunk->default_size;
248 chunk->this_size = chunk->default_size;
251 if (chunk->const_table)
252 g_hash_table_remove_all (chunk->const_table);
256 * g_string_chunk_insert:
257 * @chunk: a #GStringChunk
258 * @string: the string to add
260 * Adds a copy of @string to the #GStringChunk.
261 * It returns a pointer to the new copy of the string
262 * in the #GStringChunk. The characters in the string
263 * can be changed, if necessary, though you should not
264 * change anything after the end of the string.
266 * Unlike g_string_chunk_insert_const(), this function
267 * does not check for duplicates. Also strings added
268 * with g_string_chunk_insert() will not be searched
269 * by g_string_chunk_insert_const() when looking for
272 * Returns: a pointer to the copy of @string within
276 g_string_chunk_insert (GStringChunk *chunk,
279 g_return_val_if_fail (chunk != NULL, NULL);
281 return g_string_chunk_insert_len (chunk, string, -1);
285 * g_string_chunk_insert_const:
286 * @chunk: a #GStringChunk
287 * @string: the string to add
289 * Adds a copy of @string to the #GStringChunk, unless the same
290 * string has already been added to the #GStringChunk with
291 * g_string_chunk_insert_const().
293 * This function is useful if you need to copy a large number
294 * of strings but do not want to waste space storing duplicates.
295 * But you must remember that there may be several pointers to
296 * the same string, and so any changes made to the strings
297 * should be done very carefully.
299 * Note that g_string_chunk_insert_const() will not return a
300 * pointer to a string added with g_string_chunk_insert(), even
303 * Returns: a pointer to the new or existing copy of @string
304 * within the #GStringChunk
307 g_string_chunk_insert_const (GStringChunk *chunk,
312 g_return_val_if_fail (chunk != NULL, NULL);
314 if (!chunk->const_table)
315 chunk->const_table = g_hash_table_new (g_str_hash, g_str_equal);
317 lookup = (char*) g_hash_table_lookup (chunk->const_table, (gchar *)string);
321 lookup = g_string_chunk_insert (chunk, string);
322 g_hash_table_insert (chunk->const_table, lookup, lookup);
329 * g_string_chunk_insert_len:
330 * @chunk: a #GStringChunk
331 * @string: bytes to insert
332 * @len: number of bytes of @string to insert, or -1 to insert a
333 * nul-terminated string
335 * Adds a copy of the first @len bytes of @string to the #GStringChunk.
336 * The copy is nul-terminated.
338 * Since this function does not stop at nul bytes, it is the caller's
339 * responsibility to ensure that @string has at least @len addressable
342 * The characters in the returned string can be changed, if necessary,
343 * though you should not change anything after the end of the string.
345 * Return value: a pointer to the copy of @string within the #GStringChunk
350 g_string_chunk_insert_len (GStringChunk *chunk,
357 g_return_val_if_fail (chunk != NULL, NULL);
360 size = strlen (string);
364 if ((chunk->storage_next + size + 1) > chunk->this_size)
366 gsize new_size = nearest_power (chunk->default_size, size + 1);
368 chunk->storage_list = g_slist_prepend (chunk->storage_list,
369 g_new (gchar, new_size));
371 chunk->this_size = new_size;
372 chunk->storage_next = 0;
375 pos = ((gchar *) chunk->storage_list->data) + chunk->storage_next;
377 *(pos + size) = '\0';
379 memcpy (pos, string, size);
381 chunk->storage_next += size + 1;
389 g_string_maybe_expand (GString* string,
392 if (string->len + len >= string->allocated_len)
394 string->allocated_len = nearest_power (1, string->len + len + 1);
395 string->str = g_realloc (string->str, string->allocated_len);
400 * g_string_sized_new:
401 * @dfl_size: the default size of the space allocated to
404 * Creates a new #GString, with enough space for @dfl_size
405 * bytes. This is useful if you are going to add a lot of
406 * text to the string and don't want it to be reallocated
409 * Returns: the new #GString
412 g_string_sized_new (gsize dfl_size)
414 GString *string = g_slice_new (GString);
416 string->allocated_len = 0;
420 g_string_maybe_expand (string, MAX (dfl_size, 2));
428 * @init: the initial text to copy into the string
430 * Creates a new #GString, initialized with the given string.
432 * Returns: the new #GString
435 g_string_new (const gchar *init)
439 if (init == NULL || *init == '\0')
440 string = g_string_sized_new (2);
446 string = g_string_sized_new (len + 2);
448 g_string_append_len (string, init, len);
456 * @init: initial contents of the string
457 * @len: length of @init to use
459 * Creates a new #GString with @len bytes of the @init buffer.
460 * Because a length is provided, @init need not be nul-terminated,
461 * and can contain embedded nul bytes.
463 * Since this function does not stop at nul bytes, it is the caller's
464 * responsibility to ensure that @init has at least @len addressable
467 * Returns: a new #GString
470 g_string_new_len (const gchar *init,
476 return g_string_new (init);
479 string = g_string_sized_new (len);
482 g_string_append_len (string, init, len);
490 * @string: a #GString
491 * @free_segment: if %TRUE the actual character data is freed as well
493 * Frees the memory allocated for the #GString.
494 * If @free_segment is %TRUE it also frees the character data.
496 * Returns: the character data of @string
497 * (i.e. %NULL if @free_segment is %TRUE)
500 g_string_free (GString *string,
501 gboolean free_segment)
505 g_return_val_if_fail (string != NULL, NULL);
509 g_free (string->str);
513 segment = string->str;
515 g_slice_free (GString, string);
523 * @v2: another #GString
525 * Compares two strings for equality, returning %TRUE if they are equal.
526 * For use with #GHashTable.
528 * Returns: %TRUE if they strings are the same length and contain the
532 g_string_equal (const GString *v,
536 GString *string1 = (GString *) v;
537 GString *string2 = (GString *) v2;
538 gsize i = string1->len;
540 if (i != string2->len)
558 * @str: a string to hash
560 * Creates a hash code for @str; for use with #GHashTable.
562 * Returns: hash code for @str
564 /* 31 bit hash function */
566 g_string_hash (const GString *str)
568 const gchar *p = str->str;
574 h = (h << 5) - h + *p;
583 * @string: the destination #GString. Its current contents
585 * @rval: the string to copy into @string
587 * Copies the bytes from a string into a #GString,
588 * destroying any previous contents. It is rather like
589 * the standard strcpy() function, except that you do not
590 * have to worry about having enough space to copy the string.
595 g_string_assign (GString *string,
598 g_return_val_if_fail (string != NULL, NULL);
599 g_return_val_if_fail (rval != NULL, string);
601 /* Make sure assigning to itself doesn't corrupt the string. */
602 if (string->str != rval)
604 /* Assigning from substring should be ok since g_string_truncate
606 g_string_truncate (string, 0);
607 g_string_append (string, rval);
615 * @string: a #GString
616 * @len: the new size of @string
618 * Cuts off the end of the GString, leaving the first @len bytes.
623 g_string_truncate (GString *string,
626 g_return_val_if_fail (string != NULL, NULL);
628 string->len = MIN (len, string->len);
629 string->str[string->len] = 0;
636 * @string: a #GString
637 * @len: the new length
639 * Sets the length of a #GString. If the length is less than
640 * the current length, the string will be truncated. If the
641 * length is greater than the current length, the contents
642 * of the newly added area are undefined. (However, as
643 * always, string->str[string->len] will be a nul byte.)
645 * Return value: @string
648 g_string_set_size (GString *string,
651 g_return_val_if_fail (string != NULL, NULL);
653 if (len >= string->allocated_len)
654 g_string_maybe_expand (string, len - string->len);
657 string->str[len] = 0;
663 * g_string_insert_len:
664 * @string: a #GString
665 * @pos: position in @string where insertion should
666 * happen, or -1 for at the end
667 * @val: bytes to insert
668 * @len: number of bytes of @val to insert
670 * Inserts @len bytes of @val into @string at @pos.
671 * Because @len is provided, @val may contain embedded
672 * nuls and need not be nul-terminated. If @pos is -1,
673 * bytes are inserted at the end of the string.
675 * Since this function does not stop at nul bytes, it is
676 * the caller's responsibility to ensure that @val has at
677 * least @len addressable bytes.
682 g_string_insert_len (GString *string,
687 g_return_val_if_fail (string != NULL, NULL);
688 g_return_val_if_fail (len == 0 || val != NULL, string);
699 g_return_val_if_fail (pos <= string->len, string);
701 /* Check whether val represents a substring of string. This test
702 probably violates chapter and verse of the C standards, since
703 ">=" and "<=" are only valid when val really is a substring.
704 In practice, it will work on modern archs. */
705 if (val >= string->str && val <= string->str + string->len)
707 gsize offset = val - string->str;
710 g_string_maybe_expand (string, len);
711 val = string->str + offset;
712 /* At this point, val is valid again. */
714 /* Open up space where we are going to insert. */
715 if (pos < string->len)
716 g_memmove (string->str + pos + len, string->str + pos, string->len - pos);
718 /* Move the source part before the gap, if any. */
721 precount = MIN (len, pos - offset);
722 memcpy (string->str + pos, val, precount);
725 /* Move the source part after the gap, if any. */
727 memcpy (string->str + pos + precount,
728 val + /* Already moved: */ precount + /* Space opened up: */ len,
733 g_string_maybe_expand (string, len);
735 /* If we aren't appending at the end, move a hunk
736 * of the old string to the end, opening up space
738 if (pos < string->len)
739 g_memmove (string->str + pos + len, string->str + pos, string->len - pos);
741 /* insert the new string */
743 string->str[pos] = *val;
745 memcpy (string->str + pos, val, len);
750 string->str[string->len] = 0;
755 #define SUB_DELIM_CHARS "!$&'()*+,;="
758 is_valid (char c, const char *reserved_chars_allowed)
760 if (g_ascii_isalnum (c) ||
767 if (reserved_chars_allowed &&
768 strchr (reserved_chars_allowed, c) != NULL)
775 gunichar_ok (gunichar c)
778 (c != (gunichar) -2) &&
779 (c != (gunichar) -1);
783 * g_string_append_uri_escaped:
784 * @string: a #GString
785 * @unescaped: a string
786 * @reserved_chars_allowed: a string of reserved characters allowed to be used, or %NULL
787 * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters
789 * Appends @unescaped to @string, escaped any characters that
790 * are reserved in URIs using URI-style escape sequences.
797 g_string_append_uri_escaped (GString *string,
798 const char *unescaped,
799 const char *reserved_chars_allowed,
804 static const gchar hex[16] = "0123456789ABCDEF";
806 g_return_val_if_fail (string != NULL, NULL);
807 g_return_val_if_fail (unescaped != NULL, NULL);
809 end = unescaped + strlen (unescaped);
811 while ((c = *unescaped) != 0)
813 if (c >= 0x80 && allow_utf8 &&
814 gunichar_ok (g_utf8_get_char_validated (unescaped, end - unescaped)))
816 int len = g_utf8_skip [c];
817 g_string_append_len (string, unescaped, len);
820 else if (is_valid (c, reserved_chars_allowed))
822 g_string_append_c (string, c);
827 g_string_append_c (string, '%');
828 g_string_append_c (string, hex[((guchar)c) >> 4]);
829 g_string_append_c (string, hex[((guchar)c) & 0xf]);
839 * @string: a #GString
840 * @val: the string to append onto the end of @string
842 * Adds a string onto the end of a #GString, expanding
848 g_string_append (GString *string,
851 g_return_val_if_fail (string != NULL, NULL);
852 g_return_val_if_fail (val != NULL, string);
854 return g_string_insert_len (string, -1, val, -1);
858 * g_string_append_len:
859 * @string: a #GString
860 * @val: bytes to append
861 * @len: number of bytes of @val to use
863 * Appends @len bytes of @val to @string. Because @len is
864 * provided, @val may contain embedded nuls and need not
867 * Since this function does not stop at nul bytes, it is
868 * the caller's responsibility to ensure that @val has at
869 * least @len addressable bytes.
874 g_string_append_len (GString *string,
878 g_return_val_if_fail (string != NULL, NULL);
879 g_return_val_if_fail (len == 0 || val != NULL, string);
881 return g_string_insert_len (string, -1, val, len);
886 * @string: a #GString
887 * @c: the byte to append onto the end of @string
889 * Adds a byte onto the end of a #GString, expanding
894 #undef g_string_append_c
896 g_string_append_c (GString *string,
899 g_return_val_if_fail (string != NULL, NULL);
901 return g_string_insert_c (string, -1, c);
905 * g_string_append_unichar:
906 * @string: a #GString
907 * @wc: a Unicode character
909 * Converts a Unicode character into UTF-8, and appends it
912 * Return value: @string
915 g_string_append_unichar (GString *string,
918 g_return_val_if_fail (string != NULL, NULL);
920 return g_string_insert_unichar (string, -1, wc);
925 * @string: a #GString
926 * @val: the string to prepend on the start of @string
928 * Adds a string on to the start of a #GString,
929 * expanding it if necessary.
934 g_string_prepend (GString *string,
937 g_return_val_if_fail (string != NULL, NULL);
938 g_return_val_if_fail (val != NULL, string);
940 return g_string_insert_len (string, 0, val, -1);
944 * g_string_prepend_len:
945 * @string: a #GString
946 * @val: bytes to prepend
947 * @len: number of bytes in @val to prepend
949 * Prepends @len bytes of @val to @string.
950 * Because @len is provided, @val may contain
951 * embedded nuls and need not be nul-terminated.
953 * Since this function does not stop at nul bytes,
954 * it is the caller's responsibility to ensure that
955 * @val has at least @len addressable bytes.
960 g_string_prepend_len (GString *string,
964 g_return_val_if_fail (string != NULL, NULL);
965 g_return_val_if_fail (val != NULL, string);
967 return g_string_insert_len (string, 0, val, len);
971 * g_string_prepend_c:
972 * @string: a #GString
973 * @c: the byte to prepend on the start of the #GString
975 * Adds a byte onto the start of a #GString,
976 * expanding it if necessary.
981 g_string_prepend_c (GString *string,
984 g_return_val_if_fail (string != NULL, NULL);
986 return g_string_insert_c (string, 0, c);
990 * g_string_prepend_unichar:
991 * @string: a #GString
992 * @wc: a Unicode character
994 * Converts a Unicode character into UTF-8, and prepends it
997 * Return value: @string
1000 g_string_prepend_unichar (GString *string,
1003 g_return_val_if_fail (string != NULL, NULL);
1005 return g_string_insert_unichar (string, 0, wc);
1010 * @string: a #GString
1011 * @pos: the position to insert the copy of the string
1012 * @val: the string to insert
1014 * Inserts a copy of a string into a #GString,
1015 * expanding it if necessary.
1020 g_string_insert (GString *string,
1024 g_return_val_if_fail (string != NULL, NULL);
1025 g_return_val_if_fail (val != NULL, string);
1027 g_return_val_if_fail (pos <= string->len, string);
1029 return g_string_insert_len (string, pos, val, -1);
1033 * g_string_insert_c:
1034 * @string: a #GString
1035 * @pos: the position to insert the byte
1036 * @c: the byte to insert
1038 * Inserts a byte into a #GString, expanding it if necessary.
1043 g_string_insert_c (GString *string,
1047 g_return_val_if_fail (string != NULL, NULL);
1049 g_string_maybe_expand (string, 1);
1054 g_return_val_if_fail (pos <= string->len, string);
1056 /* If not just an append, move the old stuff */
1057 if (pos < string->len)
1058 g_memmove (string->str + pos + 1, string->str + pos, string->len - pos);
1060 string->str[pos] = c;
1064 string->str[string->len] = 0;
1070 * g_string_insert_unichar:
1071 * @string: a #GString
1072 * @pos: the position at which to insert character, or -1 to
1073 * append at the end of the string
1074 * @wc: a Unicode character
1076 * Converts a Unicode character into UTF-8, and insert it
1077 * into the string at the given position.
1079 * Return value: @string
1082 g_string_insert_unichar (GString *string,
1086 gint charlen, first, i;
1089 g_return_val_if_fail (string != NULL, NULL);
1091 /* Code copied from g_unichar_to_utf() */
1097 else if (wc < 0x800)
1102 else if (wc < 0x10000)
1107 else if (wc < 0x200000)
1112 else if (wc < 0x4000000)
1122 /* End of copied code */
1124 g_string_maybe_expand (string, charlen);
1129 g_return_val_if_fail (pos <= string->len, string);
1131 /* If not just an append, move the old stuff */
1132 if (pos < string->len)
1133 g_memmove (string->str + pos + charlen, string->str + pos, string->len - pos);
1135 dest = string->str + pos;
1136 /* Code copied from g_unichar_to_utf() */
1137 for (i = charlen - 1; i > 0; --i)
1139 dest[i] = (wc & 0x3f) | 0x80;
1142 dest[0] = wc | first;
1143 /* End of copied code */
1145 string->len += charlen;
1147 string->str[string->len] = 0;
1153 * g_string_overwrite:
1154 * @string: a #GString
1155 * @pos: the position at which to start overwriting
1156 * @val: the string that will overwrite the @string starting at @pos
1158 * Overwrites part of a string, lengthening it if necessary.
1160 * Return value: @string
1165 g_string_overwrite (GString *string,
1169 g_return_val_if_fail (val != NULL, string);
1170 return g_string_overwrite_len (string, pos, val, strlen (val));
1174 * g_string_overwrite_len:
1175 * @string: a #GString
1176 * @pos: the position at which to start overwriting
1177 * @val: the string that will overwrite the @string starting at @pos
1178 * @len: the number of bytes to write from @val
1180 * Overwrites part of a string, lengthening it if necessary.
1181 * This function will work with embedded nuls.
1183 * Return value: @string
1188 g_string_overwrite_len (GString *string,
1195 g_return_val_if_fail (string != NULL, NULL);
1200 g_return_val_if_fail (val != NULL, string);
1201 g_return_val_if_fail (pos <= string->len, string);
1208 if (end > string->len)
1209 g_string_maybe_expand (string, end - string->len);
1211 memcpy (string->str + pos, val, len);
1213 if (end > string->len)
1215 string->str[end] = '\0';
1224 * @string: a #GString
1225 * @pos: the position of the content to remove
1226 * @len: the number of bytes to remove, or -1 to remove all
1229 * Removes @len bytes from a #GString, starting at position @pos.
1230 * The rest of the #GString is shifted down to fill the gap.
1235 g_string_erase (GString *string,
1239 g_return_val_if_fail (string != NULL, NULL);
1240 g_return_val_if_fail (pos >= 0, string);
1241 g_return_val_if_fail (pos <= string->len, string);
1244 len = string->len - pos;
1247 g_return_val_if_fail (pos + len <= string->len, string);
1249 if (pos + len < string->len)
1250 g_memmove (string->str + pos, string->str + pos + len, string->len - (pos + len));
1255 string->str[string->len] = 0;
1261 * g_string_ascii_down:
1262 * @string: a GString
1264 * Converts all upper case ASCII letters to lower case ASCII letters.
1266 * Return value: passed-in @string pointer, with all the upper case
1267 * characters converted to lower case in place, with
1268 * semantics that exactly match g_ascii_tolower().
1271 g_string_ascii_down (GString *string)
1276 g_return_val_if_fail (string != NULL, NULL);
1283 *s = g_ascii_tolower (*s);
1292 * g_string_ascii_up:
1293 * @string: a GString
1295 * Converts all lower case ASCII letters to upper case ASCII letters.
1297 * Return value: passed-in @string pointer, with all the lower case
1298 * characters converted to upper case in place, with
1299 * semantics that exactly match g_ascii_toupper().
1302 g_string_ascii_up (GString *string)
1307 g_return_val_if_fail (string != NULL, NULL);
1314 *s = g_ascii_toupper (*s);
1324 * @string: a #GString
1326 * Converts a #GString to lowercase.
1328 * Returns: the #GString.
1330 * Deprecated:2.2: This function uses the locale-specific
1331 * tolower() function, which is almost never the right thing.
1332 * Use g_string_ascii_down() or g_utf8_strdown() instead.
1335 g_string_down (GString *string)
1340 g_return_val_if_fail (string != NULL, NULL);
1343 s = (guchar *) string->str;
1358 * @string: a #GString
1360 * Converts a #GString to uppercase.
1362 * Return value: @string
1364 * Deprecated:2.2: This function uses the locale-specific
1365 * toupper() function, which is almost never the right thing.
1366 * Use g_string_ascii_up() or g_utf8_strup() instead.
1369 g_string_up (GString *string)
1374 g_return_val_if_fail (string != NULL, NULL);
1377 s = (guchar *) string->str;
1391 * g_string_append_vprintf:
1392 * @string: a #GString
1393 * @format: the string format. See the printf() documentation
1394 * @args: the list of arguments to insert in the output
1396 * Appends a formatted string onto the end of a #GString.
1397 * This function is similar to g_string_append_printf()
1398 * except that the arguments to the format string are passed
1404 g_string_append_vprintf (GString *string,
1405 const gchar *format,
1411 g_return_if_fail (string != NULL);
1412 g_return_if_fail (format != NULL);
1414 len = g_vasprintf (&buf, format, args);
1418 g_string_maybe_expand (string, len);
1419 memcpy (string->str + string->len, buf, len + 1);
1427 * @string: a #GString
1428 * @format: the string format. See the printf() documentation
1429 * @args: the parameters to insert into the format string
1431 * Writes a formatted string into a #GString.
1432 * This function is similar to g_string_printf() except that
1433 * the arguments to the format string are passed as a va_list.
1438 g_string_vprintf (GString *string,
1439 const gchar *format,
1442 g_string_truncate (string, 0);
1443 g_string_append_vprintf (string, format, args);
1448 * @string: a #GString
1449 * @format: the string format. See the sprintf() documentation
1450 * @Varargs: the parameters to insert into the format string
1452 * Writes a formatted string into a #GString.
1453 * This is similar to the standard sprintf() function,
1454 * except that the #GString buffer automatically expands
1455 * to contain the results. The previous contents of the
1456 * #GString are destroyed.
1458 * Deprecated: This function has been renamed to g_string_printf().
1463 * @string: a #GString
1464 * @format: the string format. See the printf() documentation
1465 * @Varargs: the parameters to insert into the format string
1467 * Writes a formatted string into a #GString.
1468 * This is similar to the standard sprintf() function,
1469 * except that the #GString buffer automatically expands
1470 * to contain the results. The previous contents of the
1471 * #GString are destroyed.
1474 g_string_printf (GString *string,
1475 const gchar *format,
1480 g_string_truncate (string, 0);
1482 va_start (args, format);
1483 g_string_append_vprintf (string, format, args);
1488 * g_string_sprintfa:
1489 * @string: a #GString
1490 * @format: the string format. See the sprintf() documentation
1491 * @Varargs: the parameters to insert into the format string
1493 * Appends a formatted string onto the end of a #GString.
1494 * This function is similar to g_string_sprintf() except that
1495 * the text is appended to the #GString.
1497 * Deprecated: This function has been renamed to g_string_append_printf()
1501 * g_string_append_printf:
1502 * @string: a #GString
1503 * @format: the string format. See the printf() documentation
1504 * @Varargs: the parameters to insert into the format string
1506 * Appends a formatted string onto the end of a #GString.
1507 * This function is similar to g_string_printf() except
1508 * that the text is appended to the #GString.
1511 g_string_append_printf (GString *string,
1512 const gchar *format,
1517 va_start (args, format);
1518 g_string_append_vprintf (string, format, args);