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/.
50 * @short_description: text buffers which grow automatically
53 * A #GString is an object that handles the memory management of a C
54 * string for you. The emphasis of #GString is on text, typically
55 * UTF-8. Crucially, the "str" member of a #GString is guaranteed to
56 * have a trailing nul character, and it is therefore always safe to
57 * call functions such as strchr() or g_strdup() on it.
59 * However, a #GString can also hold arbitrary binary data, because it
60 * has a "len" member, which includes any possible embedded nul
61 * characters in the data. Conceptually then, #GString is like a
62 * #GByteArray with the addition of many convenience methods for text,
63 * and a guaranteed nul terminator.
68 * @str: points to the character data. It may move as text is added.
69 * The @str field is null-terminated and so
70 * can be used as an ordinary C string.
71 * @len: contains the length of the string, not including the
72 * terminating nul byte.
73 * @allocated_len: the number of bytes that can be stored in the
74 * string before it needs to be reallocated. May be larger than @len.
76 * The GString struct contains the public fields of a GString.
80 #define MY_MAXSIZE ((gsize)-1)
83 nearest_power (gsize base, gsize num)
85 if (num > MY_MAXSIZE / 2)
101 g_string_maybe_expand (GString *string,
104 if (string->len + len >= string->allocated_len)
106 string->allocated_len = nearest_power (1, string->len + len + 1);
107 string->str = g_realloc (string->str, string->allocated_len);
112 * g_string_sized_new:
113 * @dfl_size: the default size of the space allocated to
116 * Creates a new #GString, with enough space for @dfl_size
117 * bytes. This is useful if you are going to add a lot of
118 * text to the string and don't want it to be reallocated
121 * Returns: the new #GString
124 g_string_sized_new (gsize dfl_size)
126 GString *string = g_slice_new (GString);
128 string->allocated_len = 0;
132 g_string_maybe_expand (string, MAX (dfl_size, 2));
140 * @init: the initial text to copy into the string
142 * Creates a new #GString, initialized with the given string.
144 * Returns: the new #GString
147 g_string_new (const gchar *init)
151 if (init == NULL || *init == '\0')
152 string = g_string_sized_new (2);
158 string = g_string_sized_new (len + 2);
160 g_string_append_len (string, init, len);
168 * @init: initial contents of the string
169 * @len: length of @init to use
171 * Creates a new #GString with @len bytes of the @init buffer.
172 * Because a length is provided, @init need not be nul-terminated,
173 * and can contain embedded nul bytes.
175 * Since this function does not stop at nul bytes, it is the caller's
176 * responsibility to ensure that @init has at least @len addressable
179 * Returns: a new #GString
182 g_string_new_len (const gchar *init,
188 return g_string_new (init);
191 string = g_string_sized_new (len);
194 g_string_append_len (string, init, len);
202 * @string: a #GString
203 * @free_segment: if %TRUE, the actual character data is freed as well
205 * Frees the memory allocated for the #GString.
206 * If @free_segment is %TRUE it also frees the character data. If
207 * it's %FALSE, the caller gains ownership of the buffer and must
208 * free it after use with g_free().
210 * Returns: the character data of @string
211 * (i.e. %NULL if @free_segment is %TRUE)
214 g_string_free (GString *string,
215 gboolean free_segment)
219 g_return_val_if_fail (string != NULL, NULL);
223 g_free (string->str);
227 segment = string->str;
229 g_slice_free (GString, string);
235 * g_string_free_to_bytes:
236 * @string: (transfer full): a #GString
238 * Transfers ownership of the contents of @string to a newly allocated
239 * #GBytes. The #GString structure itself is deallocated, and it is
240 * therefore invalid to use @string after invoking this function.
242 * Note that while #GString ensures that its buffer always has a
243 * trailing nul character (not reflected in its "len"), the returned
244 * #GBytes does not include this extra nul; i.e. it has length exactly
245 * equal to the "len" member.
247 * Returns: A newly allocated #GBytes containing contents of @string; @string itself is freed
251 g_string_free_to_bytes (GString *string)
256 g_return_val_if_fail (string != NULL, NULL);
260 buf = g_string_free (string, FALSE);
262 return g_bytes_new_take (buf, len);
268 * @v2: another #GString
270 * Compares two strings for equality, returning %TRUE if they are equal.
271 * For use with #GHashTable.
273 * Returns: %TRUE if they strings are the same length and contain the
277 g_string_equal (const GString *v,
281 GString *string1 = (GString *) v;
282 GString *string2 = (GString *) v2;
283 gsize i = string1->len;
285 if (i != string2->len)
303 * @str: a string to hash
305 * Creates a hash code for @str; for use with #GHashTable.
307 * Returns: hash code for @str
310 g_string_hash (const GString *str)
312 const gchar *p = str->str;
316 /* 31 bit hash function */
319 h = (h << 5) - h + *p;
328 * @string: the destination #GString. Its current contents
330 * @rval: the string to copy into @string
332 * Copies the bytes from a string into a #GString,
333 * destroying any previous contents. It is rather like
334 * the standard strcpy() function, except that you do not
335 * have to worry about having enough space to copy the string.
340 g_string_assign (GString *string,
343 g_return_val_if_fail (string != NULL, NULL);
344 g_return_val_if_fail (rval != NULL, string);
346 /* Make sure assigning to itself doesn't corrupt the string. */
347 if (string->str != rval)
349 /* Assigning from substring should be ok, since
350 * g_string_truncate() does not reallocate.
352 g_string_truncate (string, 0);
353 g_string_append (string, rval);
361 * @string: a #GString
362 * @len: the new size of @string
364 * Cuts off the end of the GString, leaving the first @len bytes.
369 g_string_truncate (GString *string,
372 g_return_val_if_fail (string != NULL, NULL);
374 string->len = MIN (len, string->len);
375 string->str[string->len] = 0;
382 * @string: a #GString
383 * @len: the new length
385 * Sets the length of a #GString. If the length is less than
386 * the current length, the string will be truncated. If the
387 * length is greater than the current length, the contents
388 * of the newly added area are undefined. (However, as
389 * always, string->str[string->len] will be a nul byte.)
391 * Return value: @string
394 g_string_set_size (GString *string,
397 g_return_val_if_fail (string != NULL, NULL);
399 if (len >= string->allocated_len)
400 g_string_maybe_expand (string, len - string->len);
403 string->str[len] = 0;
409 * g_string_insert_len:
410 * @string: a #GString
411 * @pos: position in @string where insertion should
412 * happen, or -1 for at the end
413 * @val: bytes to insert
414 * @len: number of bytes of @val to insert
416 * Inserts @len bytes of @val into @string at @pos.
417 * Because @len is provided, @val may contain embedded
418 * nuls and need not be nul-terminated. If @pos is -1,
419 * bytes are inserted at the end of the string.
421 * Since this function does not stop at nul bytes, it is
422 * the caller's responsibility to ensure that @val has at
423 * least @len addressable bytes.
428 g_string_insert_len (GString *string,
433 g_return_val_if_fail (string != NULL, NULL);
434 g_return_val_if_fail (len == 0 || val != NULL, string);
445 g_return_val_if_fail (pos <= string->len, string);
447 /* Check whether val represents a substring of string.
448 * This test probably violates chapter and verse of the C standards,
449 * since ">=" and "<=" are only valid when val really is a substring.
450 * In practice, it will work on modern archs.
452 if (val >= string->str && val <= string->str + string->len)
454 gsize offset = val - string->str;
457 g_string_maybe_expand (string, len);
458 val = string->str + offset;
459 /* At this point, val is valid again. */
461 /* Open up space where we are going to insert. */
462 if (pos < string->len)
463 g_memmove (string->str + pos + len, string->str + pos, string->len - pos);
465 /* Move the source part before the gap, if any. */
468 precount = MIN (len, pos - offset);
469 memcpy (string->str + pos, val, precount);
472 /* Move the source part after the gap, if any. */
474 memcpy (string->str + pos + precount,
475 val + /* Already moved: */ precount + /* Space opened up: */ len,
480 g_string_maybe_expand (string, len);
482 /* If we aren't appending at the end, move a hunk
483 * of the old string to the end, opening up space
485 if (pos < string->len)
486 g_memmove (string->str + pos + len, string->str + pos, string->len - pos);
488 /* insert the new string */
490 string->str[pos] = *val;
492 memcpy (string->str + pos, val, len);
497 string->str[string->len] = 0;
502 #define SUB_DELIM_CHARS "!$&'()*+,;="
506 const char *reserved_chars_allowed)
508 if (g_ascii_isalnum (c) ||
515 if (reserved_chars_allowed &&
516 strchr (reserved_chars_allowed, c) != NULL)
523 gunichar_ok (gunichar c)
526 (c != (gunichar) -2) &&
527 (c != (gunichar) -1);
531 * g_string_append_uri_escaped:
532 * @string: a #GString
533 * @unescaped: a string
534 * @reserved_chars_allowed: a string of reserved characters allowed
535 * to be used, or %NULL
536 * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters
538 * Appends @unescaped to @string, escaped any characters that
539 * are reserved in URIs using URI-style escape sequences.
546 g_string_append_uri_escaped (GString *string,
547 const gchar *unescaped,
548 const gchar *reserved_chars_allowed,
553 static const gchar hex[16] = "0123456789ABCDEF";
555 g_return_val_if_fail (string != NULL, NULL);
556 g_return_val_if_fail (unescaped != NULL, NULL);
558 end = unescaped + strlen (unescaped);
560 while ((c = *unescaped) != 0)
562 if (c >= 0x80 && allow_utf8 &&
563 gunichar_ok (g_utf8_get_char_validated (unescaped, end - unescaped)))
565 int len = g_utf8_skip [c];
566 g_string_append_len (string, unescaped, len);
569 else if (is_valid (c, reserved_chars_allowed))
571 g_string_append_c (string, c);
576 g_string_append_c (string, '%');
577 g_string_append_c (string, hex[((guchar)c) >> 4]);
578 g_string_append_c (string, hex[((guchar)c) & 0xf]);
588 * @string: a #GString
589 * @val: the string to append onto the end of @string
591 * Adds a string onto the end of a #GString, expanding
597 g_string_append (GString *string,
600 g_return_val_if_fail (string != NULL, NULL);
601 g_return_val_if_fail (val != NULL, string);
603 return g_string_insert_len (string, -1, val, -1);
607 * g_string_append_len:
608 * @string: a #GString
609 * @val: bytes to append
610 * @len: number of bytes of @val to use
612 * Appends @len bytes of @val to @string. Because @len is
613 * provided, @val may contain embedded nuls and need not
616 * Since this function does not stop at nul bytes, it is
617 * the caller's responsibility to ensure that @val has at
618 * least @len addressable bytes.
623 g_string_append_len (GString *string,
627 g_return_val_if_fail (string != NULL, NULL);
628 g_return_val_if_fail (len == 0 || val != NULL, string);
630 return g_string_insert_len (string, -1, val, len);
635 * @string: a #GString
636 * @c: the byte to append onto the end of @string
638 * Adds a byte onto the end of a #GString, expanding
643 #undef g_string_append_c
645 g_string_append_c (GString *string,
648 g_return_val_if_fail (string != NULL, NULL);
650 return g_string_insert_c (string, -1, c);
654 * g_string_append_unichar:
655 * @string: a #GString
656 * @wc: a Unicode character
658 * Converts a Unicode character into UTF-8, and appends it
661 * Return value: @string
664 g_string_append_unichar (GString *string,
667 g_return_val_if_fail (string != NULL, NULL);
669 return g_string_insert_unichar (string, -1, wc);
674 * @string: a #GString
675 * @val: the string to prepend on the start of @string
677 * Adds a string on to the start of a #GString,
678 * expanding it if necessary.
683 g_string_prepend (GString *string,
686 g_return_val_if_fail (string != NULL, NULL);
687 g_return_val_if_fail (val != NULL, string);
689 return g_string_insert_len (string, 0, val, -1);
693 * g_string_prepend_len:
694 * @string: a #GString
695 * @val: bytes to prepend
696 * @len: number of bytes in @val to prepend
698 * Prepends @len bytes of @val to @string.
699 * Because @len is provided, @val may contain
700 * embedded nuls and need not be nul-terminated.
702 * Since this function does not stop at nul bytes,
703 * it is the caller's responsibility to ensure that
704 * @val has at least @len addressable bytes.
709 g_string_prepend_len (GString *string,
713 g_return_val_if_fail (string != NULL, NULL);
714 g_return_val_if_fail (val != NULL, string);
716 return g_string_insert_len (string, 0, val, len);
720 * g_string_prepend_c:
721 * @string: a #GString
722 * @c: the byte to prepend on the start of the #GString
724 * Adds a byte onto the start of a #GString,
725 * expanding it if necessary.
730 g_string_prepend_c (GString *string,
733 g_return_val_if_fail (string != NULL, NULL);
735 return g_string_insert_c (string, 0, c);
739 * g_string_prepend_unichar:
740 * @string: a #GString
741 * @wc: a Unicode character
743 * Converts a Unicode character into UTF-8, and prepends it
746 * Return value: @string
749 g_string_prepend_unichar (GString *string,
752 g_return_val_if_fail (string != NULL, NULL);
754 return g_string_insert_unichar (string, 0, wc);
759 * @string: a #GString
760 * @pos: the position to insert the copy of the string
761 * @val: the string to insert
763 * Inserts a copy of a string into a #GString,
764 * expanding it if necessary.
769 g_string_insert (GString *string,
773 g_return_val_if_fail (string != NULL, NULL);
774 g_return_val_if_fail (val != NULL, string);
777 g_return_val_if_fail (pos <= string->len, string);
779 return g_string_insert_len (string, pos, val, -1);
784 * @string: a #GString
785 * @pos: the position to insert the byte
786 * @c: the byte to insert
788 * Inserts a byte into a #GString, expanding it if necessary.
793 g_string_insert_c (GString *string,
797 g_return_val_if_fail (string != NULL, NULL);
799 g_string_maybe_expand (string, 1);
804 g_return_val_if_fail (pos <= string->len, string);
806 /* If not just an append, move the old stuff */
807 if (pos < string->len)
808 g_memmove (string->str + pos + 1, string->str + pos, string->len - pos);
810 string->str[pos] = c;
814 string->str[string->len] = 0;
820 * g_string_insert_unichar:
821 * @string: a #GString
822 * @pos: the position at which to insert character, or -1
823 * to append at the end of the string
824 * @wc: a Unicode character
826 * Converts a Unicode character into UTF-8, and insert it
827 * into the string at the given position.
829 * Return value: @string
832 g_string_insert_unichar (GString *string,
836 gint charlen, first, i;
839 g_return_val_if_fail (string != NULL, NULL);
841 /* Code copied from g_unichar_to_utf() */
852 else if (wc < 0x10000)
857 else if (wc < 0x200000)
862 else if (wc < 0x4000000)
872 /* End of copied code */
874 g_string_maybe_expand (string, charlen);
879 g_return_val_if_fail (pos <= string->len, string);
881 /* If not just an append, move the old stuff */
882 if (pos < string->len)
883 g_memmove (string->str + pos + charlen, string->str + pos, string->len - pos);
885 dest = string->str + pos;
886 /* Code copied from g_unichar_to_utf() */
887 for (i = charlen - 1; i > 0; --i)
889 dest[i] = (wc & 0x3f) | 0x80;
892 dest[0] = wc | first;
893 /* End of copied code */
895 string->len += charlen;
897 string->str[string->len] = 0;
903 * g_string_overwrite:
904 * @string: a #GString
905 * @pos: the position at which to start overwriting
906 * @val: the string that will overwrite the @string starting at @pos
908 * Overwrites part of a string, lengthening it if necessary.
910 * Return value: @string
915 g_string_overwrite (GString *string,
919 g_return_val_if_fail (val != NULL, string);
920 return g_string_overwrite_len (string, pos, val, strlen (val));
924 * g_string_overwrite_len:
925 * @string: a #GString
926 * @pos: the position at which to start overwriting
927 * @val: the string that will overwrite the @string starting at @pos
928 * @len: the number of bytes to write from @val
930 * Overwrites part of a string, lengthening it if necessary.
931 * This function will work with embedded nuls.
933 * Return value: @string
938 g_string_overwrite_len (GString *string,
945 g_return_val_if_fail (string != NULL, NULL);
950 g_return_val_if_fail (val != NULL, string);
951 g_return_val_if_fail (pos <= string->len, string);
958 if (end > string->len)
959 g_string_maybe_expand (string, end - string->len);
961 memcpy (string->str + pos, val, len);
963 if (end > string->len)
965 string->str[end] = '\0';
974 * @string: a #GString
975 * @pos: the position of the content to remove
976 * @len: the number of bytes to remove, or -1 to remove all
979 * Removes @len bytes from a #GString, starting at position @pos.
980 * The rest of the #GString is shifted down to fill the gap.
985 g_string_erase (GString *string,
989 g_return_val_if_fail (string != NULL, NULL);
990 g_return_val_if_fail (pos >= 0, string);
991 g_return_val_if_fail (pos <= string->len, string);
994 len = string->len - pos;
997 g_return_val_if_fail (pos + len <= string->len, string);
999 if (pos + len < string->len)
1000 g_memmove (string->str + pos, string->str + pos + len, string->len - (pos + len));
1005 string->str[string->len] = 0;
1011 * g_string_ascii_down:
1012 * @string: a GString
1014 * Converts all uppercase ASCII letters to lowercase ASCII letters.
1016 * Return value: passed-in @string pointer, with all the
1017 * uppercase characters converted to lowercase in place,
1018 * with semantics that exactly match g_ascii_tolower().
1021 g_string_ascii_down (GString *string)
1026 g_return_val_if_fail (string != NULL, NULL);
1033 *s = g_ascii_tolower (*s);
1042 * g_string_ascii_up:
1043 * @string: a GString
1045 * Converts all lowercase ASCII letters to uppercase ASCII letters.
1047 * Return value: passed-in @string pointer, with all the
1048 * lowercase characters converted to uppercase in place,
1049 * with semantics that exactly match g_ascii_toupper().
1052 g_string_ascii_up (GString *string)
1057 g_return_val_if_fail (string != NULL, NULL);
1064 *s = g_ascii_toupper (*s);
1074 * @string: a #GString
1076 * Converts a #GString to lowercase.
1078 * Returns: the #GString
1080 * Deprecated:2.2: This function uses the locale-specific
1081 * tolower() function, which is almost never the right thing.
1082 * Use g_string_ascii_down() or g_utf8_strdown() instead.
1085 g_string_down (GString *string)
1090 g_return_val_if_fail (string != NULL, NULL);
1093 s = (guchar *) string->str;
1108 * @string: a #GString
1110 * Converts a #GString to uppercase.
1112 * Return value: @string
1114 * Deprecated:2.2: This function uses the locale-specific
1115 * toupper() function, which is almost never the right thing.
1116 * Use g_string_ascii_up() or g_utf8_strup() instead.
1119 g_string_up (GString *string)
1124 g_return_val_if_fail (string != NULL, NULL);
1127 s = (guchar *) string->str;
1141 * g_string_append_vprintf:
1142 * @string: a #GString
1143 * @format: the string format. See the printf() documentation
1144 * @args: the list of arguments to insert in the output
1146 * Appends a formatted string onto the end of a #GString.
1147 * This function is similar to g_string_append_printf()
1148 * except that the arguments to the format string are passed
1154 g_string_append_vprintf (GString *string,
1155 const gchar *format,
1161 g_return_if_fail (string != NULL);
1162 g_return_if_fail (format != NULL);
1164 len = g_vasprintf (&buf, format, args);
1168 g_string_maybe_expand (string, len);
1169 memcpy (string->str + string->len, buf, len + 1);
1177 * @string: a #GString
1178 * @format: the string format. See the printf() documentation
1179 * @args: the parameters to insert into the format string
1181 * Writes a formatted string into a #GString.
1182 * This function is similar to g_string_printf() except that
1183 * the arguments to the format string are passed as a va_list.
1188 g_string_vprintf (GString *string,
1189 const gchar *format,
1192 g_string_truncate (string, 0);
1193 g_string_append_vprintf (string, format, args);
1198 * @string: a #GString
1199 * @format: the string format. See the sprintf() documentation
1200 * @...: the parameters to insert into the format string
1202 * Writes a formatted string into a #GString.
1203 * This is similar to the standard sprintf() function,
1204 * except that the #GString buffer automatically expands
1205 * to contain the results. The previous contents of the
1206 * #GString are destroyed.
1208 * Deprecated: This function has been renamed to g_string_printf().
1213 * @string: a #GString
1214 * @format: the string format. See the printf() documentation
1215 * @...: the parameters to insert into the format string
1217 * Writes a formatted string into a #GString.
1218 * This is similar to the standard sprintf() function,
1219 * except that the #GString buffer automatically expands
1220 * to contain the results. The previous contents of the
1221 * #GString are destroyed.
1224 g_string_printf (GString *string,
1225 const gchar *format,
1230 g_string_truncate (string, 0);
1232 va_start (args, format);
1233 g_string_append_vprintf (string, format, args);
1238 * g_string_sprintfa:
1239 * @string: a #GString
1240 * @format: the string format. See the sprintf() documentation
1241 * @...: the parameters to insert into the format string
1243 * Appends a formatted string onto the end of a #GString.
1244 * This function is similar to g_string_sprintf() except that
1245 * the text is appended to the #GString.
1247 * Deprecated: This function has been renamed to g_string_append_printf()
1251 * g_string_append_printf:
1252 * @string: a #GString
1253 * @format: the string format. See the printf() documentation
1254 * @...: the parameters to insert into the format string
1256 * Appends a formatted string onto the end of a #GString.
1257 * This function is similar to g_string_printf() except
1258 * that the text is appended to the #GString.
1261 g_string_append_printf (GString *string,
1262 const gchar *format,
1267 va_start (args, format);
1268 g_string_append_vprintf (string, format, args);