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/.
53 * @v2: a key to compare with @v1
55 * Compares two strings for byte-by-byte equality and returns %TRUE
56 * if they are equal. It can be passed to g_hash_table_new() as the
57 * @key_equal_func parameter, when using strings as keys in a #GHashTable.
59 * Note that this function is primarily meant as a hash table comparison
60 * function. For a general-purpose, %NULL-safe string comparison function,
63 * Returns: %TRUE if the two keys match
66 g_str_equal (gconstpointer v1,
69 const gchar *string1 = v1;
70 const gchar *string2 = v2;
72 return strcmp (string1, string2) == 0;
79 * Converts a string to a hash value.
81 * This function implements the widely used "djb" hash apparently posted
82 * by Daniel Bernstein to comp.lang.c some time ago. The 32 bit
83 * unsigned hash value starts at 5381 and for each byte 'c' in the
84 * string, is updated: <literal>hash = hash * 33 + c</literal>. This
85 * function uses the signed value of each byte.
87 * It can be passed to g_hash_table_new() as the @hash_func parameter,
88 * when using strings as keys in a #GHashTable.
90 * Returns: a hash value corresponding to the key
93 g_str_hash (gconstpointer v)
98 for (p = v; *p != '\0'; p++)
99 h = (h << 5) + h + *p;
104 #define MY_MAXSIZE ((gsize)-1)
107 nearest_power (gsize base, gsize num)
109 if (num > MY_MAXSIZE / 2)
127 * @short_description: text buffers which grow automatically
130 * A #GString is an object that handles the memory management
131 * of a C string for you. You can think of it as similar to a
132 * Java StringBuffer. In addition to the string itself, GString
133 * stores the length of the string, so can be used for binary
134 * data with embedded nul bytes. To access the C string managed
135 * by the GString @string, simply use @string->str.
140 * @str: points to the character data. It may move as text is added.
141 * The @str field is null-terminated and so
142 * can be used as an ordinary C string.
143 * @len: contains the length of the string, not including the
144 * terminating nul byte.
145 * @allocated_len: the number of bytes that can be stored in the
146 * string before it needs to be reallocated. May be larger than @len.
148 * The GString struct contains the public fields of a GString.
153 g_string_maybe_expand (GString *string,
156 if (string->len + len >= string->allocated_len)
158 string->allocated_len = nearest_power (1, string->len + len + 1);
159 string->str = g_realloc (string->str, string->allocated_len);
164 * g_string_sized_new:
165 * @dfl_size: the default size of the space allocated to
168 * Creates a new #GString, with enough space for @dfl_size
169 * bytes. This is useful if you are going to add a lot of
170 * text to the string and don't want it to be reallocated
173 * Returns: the new #GString
176 g_string_sized_new (gsize dfl_size)
178 GString *string = g_slice_new (GString);
180 string->allocated_len = 0;
184 g_string_maybe_expand (string, MAX (dfl_size, 2));
192 * @init: the initial text to copy into the string
194 * Creates a new #GString, initialized with the given string.
196 * Returns: the new #GString
199 g_string_new (const gchar *init)
203 if (init == NULL || *init == '\0')
204 string = g_string_sized_new (2);
210 string = g_string_sized_new (len + 2);
212 g_string_append_len (string, init, len);
220 * @init: initial contents of the string
221 * @len: length of @init to use
223 * Creates a new #GString with @len bytes of the @init buffer.
224 * Because a length is provided, @init need not be nul-terminated,
225 * and can contain embedded nul bytes.
227 * Since this function does not stop at nul bytes, it is the caller's
228 * responsibility to ensure that @init has at least @len addressable
231 * Returns: a new #GString
234 g_string_new_len (const gchar *init,
240 return g_string_new (init);
243 string = g_string_sized_new (len);
246 g_string_append_len (string, init, len);
254 * @string: a #GString
255 * @free_segment: if %TRUE, the actual character data is freed as well
257 * Frees the memory allocated for the #GString.
258 * If @free_segment is %TRUE it also frees the character data. If
259 * it's %FALSE, the caller gains ownership of the buffer and must
260 * free it after use with g_free().
262 * Returns: the character data of @string
263 * (i.e. %NULL if @free_segment is %TRUE)
266 g_string_free (GString *string,
267 gboolean free_segment)
271 g_return_val_if_fail (string != NULL, NULL);
275 g_free (string->str);
279 segment = string->str;
281 g_slice_free (GString, string);
289 * @v2: another #GString
291 * Compares two strings for equality, returning %TRUE if they are equal.
292 * For use with #GHashTable.
294 * Returns: %TRUE if they strings are the same length and contain the
298 g_string_equal (const GString *v,
302 GString *string1 = (GString *) v;
303 GString *string2 = (GString *) v2;
304 gsize i = string1->len;
306 if (i != string2->len)
324 * @str: a string to hash
326 * Creates a hash code for @str; for use with #GHashTable.
328 * Returns: hash code for @str
331 g_string_hash (const GString *str)
333 const gchar *p = str->str;
337 /* 31 bit hash function */
340 h = (h << 5) - h + *p;
349 * @string: the destination #GString. Its current contents
351 * @rval: the string to copy into @string
353 * Copies the bytes from a string into a #GString,
354 * destroying any previous contents. It is rather like
355 * the standard strcpy() function, except that you do not
356 * have to worry about having enough space to copy the string.
361 g_string_assign (GString *string,
364 g_return_val_if_fail (string != NULL, NULL);
365 g_return_val_if_fail (rval != NULL, string);
367 /* Make sure assigning to itself doesn't corrupt the string. */
368 if (string->str != rval)
370 /* Assigning from substring should be ok, since
371 * g_string_truncate() does not reallocate.
373 g_string_truncate (string, 0);
374 g_string_append (string, rval);
382 * @string: a #GString
383 * @len: the new size of @string
385 * Cuts off the end of the GString, leaving the first @len bytes.
390 g_string_truncate (GString *string,
393 g_return_val_if_fail (string != NULL, NULL);
395 string->len = MIN (len, string->len);
396 string->str[string->len] = 0;
403 * @string: a #GString
404 * @len: the new length
406 * Sets the length of a #GString. If the length is less than
407 * the current length, the string will be truncated. If the
408 * length is greater than the current length, the contents
409 * of the newly added area are undefined. (However, as
410 * always, string->str[string->len] will be a nul byte.)
412 * Return value: @string
415 g_string_set_size (GString *string,
418 g_return_val_if_fail (string != NULL, NULL);
420 if (len >= string->allocated_len)
421 g_string_maybe_expand (string, len - string->len);
424 string->str[len] = 0;
430 * g_string_insert_len:
431 * @string: a #GString
432 * @pos: position in @string where insertion should
433 * happen, or -1 for at the end
434 * @val: bytes to insert
435 * @len: number of bytes of @val to insert
437 * Inserts @len bytes of @val into @string at @pos.
438 * Because @len is provided, @val may contain embedded
439 * nuls and need not be nul-terminated. If @pos is -1,
440 * bytes are inserted at the end of the string.
442 * Since this function does not stop at nul bytes, it is
443 * the caller's responsibility to ensure that @val has at
444 * least @len addressable bytes.
449 g_string_insert_len (GString *string,
454 g_return_val_if_fail (string != NULL, NULL);
455 g_return_val_if_fail (len == 0 || val != NULL, string);
466 g_return_val_if_fail (pos <= string->len, string);
468 /* Check whether val represents a substring of string.
469 * This test probably violates chapter and verse of the C standards,
470 * since ">=" and "<=" are only valid when val really is a substring.
471 * In practice, it will work on modern archs.
473 if (val >= string->str && val <= string->str + string->len)
475 gsize offset = val - string->str;
478 g_string_maybe_expand (string, len);
479 val = string->str + offset;
480 /* At this point, val is valid again. */
482 /* Open up space where we are going to insert. */
483 if (pos < string->len)
484 g_memmove (string->str + pos + len, string->str + pos, string->len - pos);
486 /* Move the source part before the gap, if any. */
489 precount = MIN (len, pos - offset);
490 memcpy (string->str + pos, val, precount);
493 /* Move the source part after the gap, if any. */
495 memcpy (string->str + pos + precount,
496 val + /* Already moved: */ precount + /* Space opened up: */ len,
501 g_string_maybe_expand (string, len);
503 /* If we aren't appending at the end, move a hunk
504 * of the old string to the end, opening up space
506 if (pos < string->len)
507 g_memmove (string->str + pos + len, string->str + pos, string->len - pos);
509 /* insert the new string */
511 string->str[pos] = *val;
513 memcpy (string->str + pos, val, len);
518 string->str[string->len] = 0;
523 #define SUB_DELIM_CHARS "!$&'()*+,;="
527 const char *reserved_chars_allowed)
529 if (g_ascii_isalnum (c) ||
536 if (reserved_chars_allowed &&
537 strchr (reserved_chars_allowed, c) != NULL)
544 gunichar_ok (gunichar c)
547 (c != (gunichar) -2) &&
548 (c != (gunichar) -1);
552 * g_string_append_uri_escaped:
553 * @string: a #GString
554 * @unescaped: a string
555 * @reserved_chars_allowed: a string of reserved characters allowed
556 * to be used, or %NULL
557 * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters
559 * Appends @unescaped to @string, escaped any characters that
560 * are reserved in URIs using URI-style escape sequences.
567 g_string_append_uri_escaped (GString *string,
568 const gchar *unescaped,
569 const gchar *reserved_chars_allowed,
574 static const gchar hex[16] = "0123456789ABCDEF";
576 g_return_val_if_fail (string != NULL, NULL);
577 g_return_val_if_fail (unescaped != NULL, NULL);
579 end = unescaped + strlen (unescaped);
581 while ((c = *unescaped) != 0)
583 if (c >= 0x80 && allow_utf8 &&
584 gunichar_ok (g_utf8_get_char_validated (unescaped, end - unescaped)))
586 int len = g_utf8_skip [c];
587 g_string_append_len (string, unescaped, len);
590 else if (is_valid (c, reserved_chars_allowed))
592 g_string_append_c (string, c);
597 g_string_append_c (string, '%');
598 g_string_append_c (string, hex[((guchar)c) >> 4]);
599 g_string_append_c (string, hex[((guchar)c) & 0xf]);
609 * @string: a #GString
610 * @val: the string to append onto the end of @string
612 * Adds a string onto the end of a #GString, expanding
618 g_string_append (GString *string,
621 g_return_val_if_fail (string != NULL, NULL);
622 g_return_val_if_fail (val != NULL, string);
624 return g_string_insert_len (string, -1, val, -1);
628 * g_string_append_len:
629 * @string: a #GString
630 * @val: bytes to append
631 * @len: number of bytes of @val to use
633 * Appends @len bytes of @val to @string. Because @len is
634 * provided, @val may contain embedded nuls and need not
637 * Since this function does not stop at nul bytes, it is
638 * the caller's responsibility to ensure that @val has at
639 * least @len addressable bytes.
644 g_string_append_len (GString *string,
648 g_return_val_if_fail (string != NULL, NULL);
649 g_return_val_if_fail (len == 0 || val != NULL, string);
651 return g_string_insert_len (string, -1, val, len);
656 * @string: a #GString
657 * @c: the byte to append onto the end of @string
659 * Adds a byte onto the end of a #GString, expanding
664 #undef g_string_append_c
666 g_string_append_c (GString *string,
669 g_return_val_if_fail (string != NULL, NULL);
671 return g_string_insert_c (string, -1, c);
675 * g_string_append_unichar:
676 * @string: a #GString
677 * @wc: a Unicode character
679 * Converts a Unicode character into UTF-8, and appends it
682 * Return value: @string
685 g_string_append_unichar (GString *string,
688 g_return_val_if_fail (string != NULL, NULL);
690 return g_string_insert_unichar (string, -1, wc);
695 * @string: a #GString
696 * @val: the string to prepend on the start of @string
698 * Adds a string on to the start of a #GString,
699 * expanding it if necessary.
704 g_string_prepend (GString *string,
707 g_return_val_if_fail (string != NULL, NULL);
708 g_return_val_if_fail (val != NULL, string);
710 return g_string_insert_len (string, 0, val, -1);
714 * g_string_prepend_len:
715 * @string: a #GString
716 * @val: bytes to prepend
717 * @len: number of bytes in @val to prepend
719 * Prepends @len bytes of @val to @string.
720 * Because @len is provided, @val may contain
721 * embedded nuls and need not be nul-terminated.
723 * Since this function does not stop at nul bytes,
724 * it is the caller's responsibility to ensure that
725 * @val has at least @len addressable bytes.
730 g_string_prepend_len (GString *string,
734 g_return_val_if_fail (string != NULL, NULL);
735 g_return_val_if_fail (val != NULL, string);
737 return g_string_insert_len (string, 0, val, len);
741 * g_string_prepend_c:
742 * @string: a #GString
743 * @c: the byte to prepend on the start of the #GString
745 * Adds a byte onto the start of a #GString,
746 * expanding it if necessary.
751 g_string_prepend_c (GString *string,
754 g_return_val_if_fail (string != NULL, NULL);
756 return g_string_insert_c (string, 0, c);
760 * g_string_prepend_unichar:
761 * @string: a #GString
762 * @wc: a Unicode character
764 * Converts a Unicode character into UTF-8, and prepends it
767 * Return value: @string
770 g_string_prepend_unichar (GString *string,
773 g_return_val_if_fail (string != NULL, NULL);
775 return g_string_insert_unichar (string, 0, wc);
780 * @string: a #GString
781 * @pos: the position to insert the copy of the string
782 * @val: the string to insert
784 * Inserts a copy of a string into a #GString,
785 * expanding it if necessary.
790 g_string_insert (GString *string,
794 g_return_val_if_fail (string != NULL, NULL);
795 g_return_val_if_fail (val != NULL, string);
798 g_return_val_if_fail (pos <= string->len, string);
800 return g_string_insert_len (string, pos, val, -1);
805 * @string: a #GString
806 * @pos: the position to insert the byte
807 * @c: the byte to insert
809 * Inserts a byte into a #GString, expanding it if necessary.
814 g_string_insert_c (GString *string,
818 g_return_val_if_fail (string != NULL, NULL);
820 g_string_maybe_expand (string, 1);
825 g_return_val_if_fail (pos <= string->len, string);
827 /* If not just an append, move the old stuff */
828 if (pos < string->len)
829 g_memmove (string->str + pos + 1, string->str + pos, string->len - pos);
831 string->str[pos] = c;
835 string->str[string->len] = 0;
841 * g_string_insert_unichar:
842 * @string: a #GString
843 * @pos: the position at which to insert character, or -1
844 * to append at the end of the string
845 * @wc: a Unicode character
847 * Converts a Unicode character into UTF-8, and insert it
848 * into the string at the given position.
850 * Return value: @string
853 g_string_insert_unichar (GString *string,
857 gint charlen, first, i;
860 g_return_val_if_fail (string != NULL, NULL);
862 /* Code copied from g_unichar_to_utf() */
873 else if (wc < 0x10000)
878 else if (wc < 0x200000)
883 else if (wc < 0x4000000)
893 /* End of copied code */
895 g_string_maybe_expand (string, charlen);
900 g_return_val_if_fail (pos <= string->len, string);
902 /* If not just an append, move the old stuff */
903 if (pos < string->len)
904 g_memmove (string->str + pos + charlen, string->str + pos, string->len - pos);
906 dest = string->str + pos;
907 /* Code copied from g_unichar_to_utf() */
908 for (i = charlen - 1; i > 0; --i)
910 dest[i] = (wc & 0x3f) | 0x80;
913 dest[0] = wc | first;
914 /* End of copied code */
916 string->len += charlen;
918 string->str[string->len] = 0;
924 * g_string_overwrite:
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
929 * Overwrites part of a string, lengthening it if necessary.
931 * Return value: @string
936 g_string_overwrite (GString *string,
940 g_return_val_if_fail (val != NULL, string);
941 return g_string_overwrite_len (string, pos, val, strlen (val));
945 * g_string_overwrite_len:
946 * @string: a #GString
947 * @pos: the position at which to start overwriting
948 * @val: the string that will overwrite the @string starting at @pos
949 * @len: the number of bytes to write from @val
951 * Overwrites part of a string, lengthening it if necessary.
952 * This function will work with embedded nuls.
954 * Return value: @string
959 g_string_overwrite_len (GString *string,
966 g_return_val_if_fail (string != NULL, NULL);
971 g_return_val_if_fail (val != NULL, string);
972 g_return_val_if_fail (pos <= string->len, string);
979 if (end > string->len)
980 g_string_maybe_expand (string, end - string->len);
982 memcpy (string->str + pos, val, len);
984 if (end > string->len)
986 string->str[end] = '\0';
995 * @string: a #GString
996 * @pos: the position of the content to remove
997 * @len: the number of bytes to remove, or -1 to remove all
1000 * Removes @len bytes from a #GString, starting at position @pos.
1001 * The rest of the #GString is shifted down to fill the gap.
1006 g_string_erase (GString *string,
1010 g_return_val_if_fail (string != NULL, NULL);
1011 g_return_val_if_fail (pos >= 0, string);
1012 g_return_val_if_fail (pos <= string->len, string);
1015 len = string->len - pos;
1018 g_return_val_if_fail (pos + len <= string->len, string);
1020 if (pos + len < string->len)
1021 g_memmove (string->str + pos, string->str + pos + len, string->len - (pos + len));
1026 string->str[string->len] = 0;
1032 * g_string_ascii_down:
1033 * @string: a GString
1035 * Converts all uppercase ASCII letters to lowercase ASCII letters.
1037 * Return value: passed-in @string pointer, with all the
1038 * uppercase characters converted to lowercase in place,
1039 * with semantics that exactly match g_ascii_tolower().
1042 g_string_ascii_down (GString *string)
1047 g_return_val_if_fail (string != NULL, NULL);
1054 *s = g_ascii_tolower (*s);
1063 * g_string_ascii_up:
1064 * @string: a GString
1066 * Converts all lowercase ASCII letters to uppercase ASCII letters.
1068 * Return value: passed-in @string pointer, with all the
1069 * lowercase characters converted to uppercase in place,
1070 * with semantics that exactly match g_ascii_toupper().
1073 g_string_ascii_up (GString *string)
1078 g_return_val_if_fail (string != NULL, NULL);
1085 *s = g_ascii_toupper (*s);
1095 * @string: a #GString
1097 * Converts a #GString to lowercase.
1099 * Returns: the #GString
1101 * Deprecated:2.2: This function uses the locale-specific
1102 * tolower() function, which is almost never the right thing.
1103 * Use g_string_ascii_down() or g_utf8_strdown() instead.
1106 g_string_down (GString *string)
1111 g_return_val_if_fail (string != NULL, NULL);
1114 s = (guchar *) string->str;
1129 * @string: a #GString
1131 * Converts a #GString to uppercase.
1133 * Return value: @string
1135 * Deprecated:2.2: This function uses the locale-specific
1136 * toupper() function, which is almost never the right thing.
1137 * Use g_string_ascii_up() or g_utf8_strup() instead.
1140 g_string_up (GString *string)
1145 g_return_val_if_fail (string != NULL, NULL);
1148 s = (guchar *) string->str;
1162 * g_string_append_vprintf:
1163 * @string: a #GString
1164 * @format: the string format. See the printf() documentation
1165 * @args: the list of arguments to insert in the output
1167 * Appends a formatted string onto the end of a #GString.
1168 * This function is similar to g_string_append_printf()
1169 * except that the arguments to the format string are passed
1175 g_string_append_vprintf (GString *string,
1176 const gchar *format,
1182 g_return_if_fail (string != NULL);
1183 g_return_if_fail (format != NULL);
1185 len = g_vasprintf (&buf, format, args);
1189 g_string_maybe_expand (string, len);
1190 memcpy (string->str + string->len, buf, len + 1);
1198 * @string: a #GString
1199 * @format: the string format. See the printf() documentation
1200 * @args: the parameters to insert into the format string
1202 * Writes a formatted string into a #GString.
1203 * This function is similar to g_string_printf() except that
1204 * the arguments to the format string are passed as a va_list.
1209 g_string_vprintf (GString *string,
1210 const gchar *format,
1213 g_string_truncate (string, 0);
1214 g_string_append_vprintf (string, format, args);
1219 * @string: a #GString
1220 * @format: the string format. See the sprintf() documentation
1221 * @...: the parameters to insert into the format string
1223 * Writes a formatted string into a #GString.
1224 * This is similar to the standard sprintf() function,
1225 * except that the #GString buffer automatically expands
1226 * to contain the results. The previous contents of the
1227 * #GString are destroyed.
1229 * Deprecated: This function has been renamed to g_string_printf().
1234 * @string: a #GString
1235 * @format: the string format. See the printf() documentation
1236 * @...: the parameters to insert into the format string
1238 * Writes a formatted string into a #GString.
1239 * This is similar to the standard sprintf() function,
1240 * except that the #GString buffer automatically expands
1241 * to contain the results. The previous contents of the
1242 * #GString are destroyed.
1245 g_string_printf (GString *string,
1246 const gchar *format,
1251 g_string_truncate (string, 0);
1253 va_start (args, format);
1254 g_string_append_vprintf (string, format, args);
1259 * g_string_sprintfa:
1260 * @string: a #GString
1261 * @format: the string format. See the sprintf() documentation
1262 * @...: the parameters to insert into the format string
1264 * Appends a formatted string onto the end of a #GString.
1265 * This function is similar to g_string_sprintf() except that
1266 * the text is appended to the #GString.
1268 * Deprecated: This function has been renamed to g_string_append_printf()
1272 * g_string_append_printf:
1273 * @string: a #GString
1274 * @format: the string format. See the printf() documentation
1275 * @...: the parameters to insert into the format string
1277 * Appends a formatted string onto the end of a #GString.
1278 * This function is similar to g_string_printf() except
1279 * that the text is appended to the #GString.
1282 g_string_append_printf (GString *string,
1283 const gchar *format,
1288 va_start (args, format);
1289 g_string_append_vprintf (string, format, args);