1 <!-- ##### SECTION Title ##### -->
2 String Utility Functions
4 <!-- ##### SECTION Short_Description ##### -->
5 various string-related functions.
7 <!-- ##### SECTION Long_Description ##### -->
9 This section describes a number of utility functions for creating,
10 duplicating, and manipulating strings.
13 <!-- ##### SECTION See_Also ##### -->
18 <!-- ##### FUNCTION g_strdup ##### -->
21 The returned string should be freed when no longer needed.
24 @str: the string to duplicate.
25 @Returns: a newly-allocated copy of @str.
28 <!-- ##### FUNCTION g_strndup ##### -->
30 Duplicates the first @n characters of a string, returning a newly-allocated
31 buffer @n + 1 characters long which will always be nul-terminated.
32 If @str is less than @n characters long the buffer is padded with nuls.
33 The returned value should be freed when no longer needed.
36 @str: the string to duplicate part of.
37 @n: the maximum number of characters to copy from @str.
38 @Returns: a newly-allocated buffer containing the first @n characters of @str,
42 <!-- ##### FUNCTION g_strdupv ##### -->
44 Copies a %NULL-terminated array of strings. The result consists of a
45 %NULL-terminated array, with one malloc block holding the array of strings, and
46 each string itself allocated. The simplest way to free the result is with
47 g_strfreev() which frees each string in a vector, then the vector itself.
50 @str_array: array to copy
54 <!-- ##### FUNCTION g_strnfill ##### -->
56 Creates a new string @length characters long filled with @fill_char.
57 The returned string should be freed when no longer needed.
60 @length: the length of the new string.
61 @fill_char: the character to fill the string with.
62 @Returns: a newly-allocated string filled the @fill_char.
65 <!-- ##### FUNCTION g_stpcpy ##### -->
75 <!-- ##### FUNCTION g_strstr_len ##### -->
86 <!-- ##### FUNCTION g_strrstr ##### -->
96 <!-- ##### FUNCTION g_strrstr_len ##### -->
107 <!-- ##### FUNCTION g_strlcpy ##### -->
109 Portability wrapper that calls strlcpy() on systems which have it, and emulates
110 strlcpy() otherwise. Copies @src to @dest; @dest is guaranteed to be
111 nul-terminated; @src must be nul-terminated; @dest_size is the buffer size, not
112 the number of chars to copy. Caveat: strlcpy() is supposedly more secure than
113 strcpy() or strncpy(), but if you really want to avoid screwups, g_strdup() is
117 @dest: destination buffer
119 @dest_size: length of @dest in bytes
120 @Returns: length of @src
123 <!-- ##### FUNCTION g_strlcat ##### -->
125 Portability wrapper that calls <function>strlcat()</function> on systems which have it, and emulates it otherwise. Appends nul-terminated @src string to @dest, guaranteeing
126 nul-termination for @dest. The total size of @dest won't exceed
127 @dest_size. Caveat: this is supposedly a more secure alternative to <function>strcat()</function> or
128 <function>strncat()</function>, but for real security g_strconcat() is harder to mess up.
131 @dest: destination buffer, already containing one nul-terminated string
133 @dest_size: length of @dest buffer in bytes (not length of existing string inside @dest)
134 @Returns: length of @src plus initial length of string in @dest
137 <!-- ##### FUNCTION g_strdup_printf ##### -->
139 Similar to the standard C <function>sprintf()</function> function
140 but safer, since it calculates the maximum space required and allocates
141 memory to hold the result.
142 The returned string should be freed when no longer needed.
145 @format: the standard <function>sprintf()</function> format string.
146 @Varargs: the parameters to insert into the format string.
147 @Returns: a newly-allocated string holding the result.
150 <!-- ##### FUNCTION g_strdup_vprintf ##### -->
152 Similar to the standard C <function>vsprintf()</function> function
153 but safer, since it calculates the maximum space required and allocates
154 memory to hold the result.
155 The returned string should be freed when no longer needed.
158 @format: the standard <function>sprintf()</function> format string.
159 @args: the list of parameters to insert into the format string.
160 @Returns: a newly-allocated string holding the result.
163 <!-- ##### FUNCTION g_snprintf ##### -->
165 A safer form of the standard <function>sprintf()</function> function.
166 The output is guaranteed to not exceed @n characters (including the
167 terminating nul character), so it is easy to ensure that a buffer overflow
171 See also g_strdup_printf().
175 In versions of GLib prior to 1.2.3, this function may return -1 if the output
176 was truncated, and the truncated string may not be nul-terminated.
177 In versions prior to 1.3.12, this function returns the length of the output
183 The return value of g_snprintf() conforms to the <function>snprintf()</function>
184 function as standardized in ISO C99. Note that this is different from
185 traditional <function>snprintf()</function>, which returns the length of
190 @string: the buffer to hold the output.
191 @n: the maximum number of characters to produce (including the terminating nul
193 @format: the format string. See the <function>sprintf()</function>.
195 @Varargs: the arguments to insert in the output.
196 @Returns: the number of characters which would be produced if the buffer was
200 <!-- ##### FUNCTION g_vsnprintf ##### -->
202 A safer form of the standard <function>vsprintf()</function> function.
203 The output is guaranteed to not exceed @n characters (including the
204 terminating nul character), so it is easy to ensure that a buffer overflow
208 See also g_strdup_vprintf().
212 In versions of GLib prior to 1.2.3, this function may return -1 if the output
213 was truncated, and the truncated string may not be nul-terminated.
214 In versions prior to 1.3.12, this function returns the length of the output
220 The return value of g_vsnprintf() conforms to the <function>vsnprintf()</function>
221 function as standardized in ISO C99. Note that this is different from
222 traditional <function>vsnprintf()</function>, which returns the length of
227 @string: the buffer to hold the output.
228 @n: the maximum number of characters to produce (including the terminating nul
230 @format: the format string. See the <function>sprintf()</function>
232 @args: the list of arguments to insert in the output.
233 @Returns: the number of characters which would be produced if the buffer was
237 <!-- ##### FUNCTION g_printf_string_upper_bound ##### -->
239 Calculates the maximum space needed to store the output of the
240 <function>sprintf()</function> function.
243 @format: the format string. See the <function>printf()</function>
245 @args: the parameters to be inserted into the format string.
246 @Returns: the maximum space needed to store the formatted string.
249 <!-- ##### FUNCTION g_ascii_isalnum ##### -->
251 Determines whether a character is alphanumeric.
254 Unlike the standard C library <function>isalnum()</function> function, this only
255 recognizes standard ASCII letters and ignores the locale, returning
256 %FALSE for all non-ASCII characters. Also unlike the standard
257 library function, this takes a <type>char</type>, not an <type>int</type>,
258 so don't call it on %EOF but no need to cast to #guchar before passing a
259 possibly non-ASCII character in.
263 @Returns: %TRUE if @c is an ASCII alphanumeric character
266 <!-- ##### FUNCTION g_ascii_isalpha ##### -->
268 Determines whether a character is alphabetic (i.e. a letter).
271 Unlike the standard C library <function>isalpha()</function> function, this only
272 recognizes standard ASCII letters and ignores the locale, returning
273 %FALSE for all non-ASCII characters. Also unlike the standard
274 library function, this takes a <type>char</type>, not an <type>int</type>,
275 so don't call it on %EOF but no need to cast to #guchar before passing a
276 possibly non-ASCII character in.
280 @Returns: %TRUE if @c is an ASCII alphabetic character
283 <!-- ##### FUNCTION g_ascii_iscntrl ##### -->
285 Determines whether a character is a control character.
288 Unlike the standard C library <function>iscntrl()</function> function, this only
289 recognizes standard ASCII control characters and ignores the locale,
290 returning %FALSE for all non-ASCII characters. Also unlike the standard
291 library function, this takes a <type>char</type>, not an <type>int</type>,
292 so don't call it on %EOF but no need to cast to #guchar before passing a
293 possibly non-ASCII character in.
297 @Returns: %TRUE if @c is an ASCII control character.
300 <!-- ##### FUNCTION g_ascii_isdigit ##### -->
302 Determines whether a character is digit (0-9).
305 Unlike the standard C library <function>isdigit()</function> function,
306 this takes a <type>char</type>, not an <type>int</type>, so don't call it
307 on %EOF but no need to cast to #guchar before passing a possibly
308 non-ASCII character in.
312 @Returns: %TRUE if @c is an ASCII digit.
315 <!-- ##### FUNCTION g_ascii_isgraph ##### -->
317 Determines whether a character is a printing character and not a space.
320 Unlike the standard C library <function>isgraph()</function> function,
321 this only recognizes standard ASCII characters and ignores the locale,
322 returning %FALSE for all non-ASCII characters. Also unlike the standard
323 library function, this takes a <type>char</type>, not an <type>int</type>,
324 so don't call it on %EOF but no need to cast to #guchar before passing a
325 possibly non-ASCII character in.
329 @Returns: %TRUE if @c is an ASCII printing character other than space.
332 <!-- ##### FUNCTION g_ascii_islower ##### -->
334 Determines whether a character is an ASCII lower case letter.
337 Unlike the standard C library <function>islower()</function> function,
338 this only recognizes standard ASCII letters and ignores the locale,
339 returning %FALSE for all non-ASCII characters. Also unlike the standard
340 library function, this takes a <type>char</type>, not an <type>int</type>,
341 so don't call it on %EOF but no need to worry about casting to #guchar
342 before passing a possibly non-ASCII character in.
346 @Returns: %TRUE if @c is an ASCII lower case letter
349 <!-- ##### FUNCTION g_ascii_isprint ##### -->
351 Determines whether a character is a printing character.
354 Unlike the standard C library <function>isprint()</function> function,
355 this only recognizes standard ASCII characters and ignores the locale,
356 returning %FALSE for all non-ASCII characters. Also unlike the standard
357 library function, this takes a <type>char</type>, not an <type>int</type>,
358 so don't call it on %EOF but no need to cast to #guchar before passing a
359 possibly non-ASCII character in.
363 @Returns: %TRUE if @c is an ASCII printing character.
366 <!-- ##### FUNCTION g_ascii_ispunct ##### -->
368 Determines whether a character is a punctuation character.
371 Unlike the standard C library <function>ispunct()</function> function,
372 this only recognizes standard ASCII letters and ignores the locale,
373 returning %FALSE for all non-ASCII characters. Also unlike the standard
374 library function, this takes a <type>char</type>, not an <type>int</type>,
375 so don't call it on %EOF but no need to cast to #guchar before passing a
376 possibly non-ASCII character in.
380 @Returns: %TRUE if @c is an ASCII punctuation character.
383 <!-- ##### FUNCTION g_ascii_isspace ##### -->
385 Determines whether a character is a white-space character.
388 Unlike the standard C library <function>isspace()</function> function,
389 this only recognizes standard ASCII white-space and ignores the locale,
390 returning %FALSE for all non-ASCII characters. Also unlike the standard
391 library function, this takes a <type>char</type>, not an <type>int</type>,
392 so don't call it on %EOF but no need to cast to #guchar before passing a
393 possibly non-ASCII character in.
397 @Returns: %TRUE if @c is an ASCII white-space character
400 <!-- ##### FUNCTION g_ascii_isupper ##### -->
402 Determines whether a character is an ASCII upper case letter.
405 Unlike the standard C library <function>isupper()</function> function,
406 this only recognizes standard ASCII letters and ignores the locale,
407 returning %FALSE for all non-ASCII characters. Also unlike the standard
408 library function, this takes a <type>char</type>, not an <type>int</type>,
409 so don't call it on %EOF but no need to worry about casting to #guchar
410 before passing a possibly non-ASCII character in.
414 @Returns: %TRUE if @c is an ASCII upper case letter
417 <!-- ##### FUNCTION g_ascii_isxdigit ##### -->
419 Determines whether a character is a hexadecimal-digit character.
422 Unlike the standard C library <function>isxdigit()</function> function,
423 this takes a <type>char</type>, not an <type>int</type>, so
424 don't call it on %EOF but no need to cast to #guchar before passing a
425 possibly non-ASCII character in.
429 @Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
432 <!-- ##### FUNCTION g_ascii_digit_value ##### -->
441 <!-- ##### FUNCTION g_ascii_xdigit_value ##### -->
450 <!-- ##### FUNCTION g_ascii_strcasecmp ##### -->
460 <!-- ##### FUNCTION g_ascii_strncasecmp ##### -->
471 <!-- ##### FUNCTION g_ascii_strup ##### -->
479 <!-- # Unused Parameters # -->
483 <!-- ##### FUNCTION g_ascii_strdown ##### -->
491 <!-- # Unused Parameters # -->
495 <!-- ##### FUNCTION g_ascii_tolower ##### -->
504 <!-- ##### FUNCTION g_ascii_toupper ##### -->
513 <!-- ##### FUNCTION g_string_ascii_up ##### -->
522 <!-- ##### FUNCTION g_string_ascii_down ##### -->
531 <!-- ##### FUNCTION g_strup ##### -->
533 Converts a string to upper case. This function is totally broken
534 for the reasons discussed in the g_strncasecmp() docs -
535 use g_ascii_strup() or g_utf8_strup() instead.
538 @string: the string to convert.
542 <!-- ##### FUNCTION g_strdown ##### -->
544 Converts a string to lower case. This function is totally broken for
545 the reasons discussed in the g_strncasecmp() docs - use
546 g_ascii_strdown() or g_utf8_strdown() instead.
549 @string: the string to convert.
553 <!-- ##### FUNCTION g_strcasecmp ##### -->
555 A case-insensitive string comparison, corresponding to the standard
556 <function>strcasecmp()</function> function on platforms which support it.
559 See g_strncasecmp() for a discussion of why this is deprecated and
564 @s2: a string to compare with @s1.
565 @Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
569 <!-- ##### FUNCTION g_strncasecmp ##### -->
571 A case-insensitive string comparison, corresponding to the standard
572 <function>strncasecmp()</function> function on platforms which support it.
573 It is similar to g_strcasecmp() except it only compares the first @n characters
577 The problem with g_strncasecmp() is that it does the comparison by
578 calling <function>toupper()</function>/<function>tolower()</function>
579 on each byte. <function>toupper()</function>/<function>tolower()</function> are
580 locale-specific and operate on single bytes. However, it is impossible
581 to handle things correctly from an i18n standpoint by operating on
582 bytes, since characters may be multibyte. Thus g_strncasecmp() is
583 broken if your string is guaranteed to be ASCII, since it's
584 locale-sensitive, and it's broken if your string is localized, since
585 it doesn't work on many encodings at all, including UTF-8, EUC-JP,
589 There are therefore two replacement functions: g_ascii_strncasecmp(),
590 which only works on ASCII and is not locale-sensitive, and
591 g_utf8_casefold(), which is good for case-insensitive sorting of
596 @s2: a string to compare with @s1.
597 @n: the maximum number of characters to compare.
598 @Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
602 <!-- ##### FUNCTION g_strreverse ##### -->
604 Reverses all of the characters in a string.
605 For example, <literal>g_strreverse ("abcdef")</literal> will result in "fedcba".
608 @string: the string to reverse.
609 @Returns: the same pointer passed in as @string.
612 <!-- ##### MACRO G_ASCII_DTOSTR_BUF_SIZE ##### -->
614 A good size for a buffer to be passed into g_ascii_dtostr().
615 It is guaranteed to be enough for all output of that function on systems with
616 64bit IEEE-compatible doubles.
619 The typical usage would be something like:
620 <informalexample><programlisting>
621 char buf[G_ASCII_DTOSTR_BUF_SIZE];
623 fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
624 </programlisting></informalexample>
629 <!-- ##### FUNCTION g_ascii_strtod ##### -->
639 <!-- ##### FUNCTION g_ascii_dtostr ##### -->
648 <!-- # Unused Parameters # -->
652 <!-- ##### FUNCTION g_ascii_formatd ##### -->
664 <!-- ##### FUNCTION g_strtod ##### -->
674 <!-- ##### FUNCTION g_strchug ##### -->
676 Removes leading whitespace from a string, by moving the rest of the
680 @string: a string to remove the leading whitespace from.
684 <!-- ##### FUNCTION g_strchomp ##### -->
686 Removes trailing whitespace from a string.
689 @string: a string to remove the trailing whitespace from.
693 <!-- ##### MACRO g_strstrip ##### -->
695 Removes leading and trailing whitespace from a string.
698 @string: a string to remove the leading and trailing whitespace from.
701 <!-- ##### FUNCTION g_strdelimit ##### -->
703 Converts any delimiter characters in @string to @new_delimiter.
704 Any characters in @string which are found in @delimiters are changed
705 to the @new_delimiter character.
708 @string: the string to convert.
709 @delimiters: a string containing the current delimiters, or %NULL to use the
710 standard delimiters defined in #G_STR_DELIMITERS.
711 @new_delimiter: the new delimiter character.
715 <!-- ##### MACRO G_STR_DELIMITERS ##### -->
717 The standard delimiters, used in g_strdelimit().
722 <!-- ##### FUNCTION g_strescape ##### -->
724 Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\' and
725 '"' in the string @source by inserting a '\' before
726 them. Additionally all characters in the range 0x01-0x1F (everything
727 below SPACE) and in the range 0x80-0xFF (all non-ASCII chars) are
728 replaced with a '\' followed by their octal representation. Characters
729 supplied in @exceptions are not escaped.
733 g_strcompress() does the reverse conversion.
736 @source: a string to escape.
737 @exceptions: a string of characters not to escape in @source.
738 @Returns: a newly-allocated copy of @source with certain
739 characters escaped. See above.
742 <!-- ##### FUNCTION g_strcompress ##### -->
744 Replaces all escaped characters with their one byte equivalent. It
745 does the reverse conversion of g_strescape().
748 @source: a string to compress.
749 @Returns: a newly-allocated copy of @source with all escaped
750 character compressed.
753 <!-- ##### FUNCTION g_strcanon ##### -->
755 For each character in @string, if the character is not in @valid_chars,
756 replaces the character with @substitutor. Modifies @string in place,
757 and return @string itself, not a copy. The return value is to allow
758 nesting such as <literal>g_strup (g_strcanon (str))</literal>.
761 @string: a nul-terminated array of bytes.
762 @valid_chars: bytes permitted in @string.
763 @substitutor: replacement character for disallowed bytes.
767 <!-- ##### FUNCTION g_strsplit ##### -->
777 <!-- ##### FUNCTION g_strfreev ##### -->
779 Frees a %NULL-terminated array of strings, and the array itself.
782 @str_array: a %NULL-terminated array of strings to free.
785 <!-- ##### FUNCTION g_strconcat ##### -->
787 Concatenates all of the given strings into one long string. The returned string
788 should be freed when no longer needed. WARNING: THE VARIABLE ARGUMENT LIST MUST
789 END WITH %NULL. If you forget the %NULL, g_strconcat() will start appending
790 random memory junk to your string.
793 @string1: The first string to add, which must not be %NULL.
794 @Varargs: a %NULL-terminated list of strings to append to the string.
795 @Returns: a newly-allocated string containing all the string arguments.
798 <!-- ##### FUNCTION g_strjoin ##### -->
800 Joins a number of strings together to form one long string, with the optional
801 @separator inserted between each of them.
804 @separator: a string to insert between each of the strings, or %NULL.
805 @Varargs: a %NULL-terminated list of strings to join.
806 @Returns: a newly-allocated string containing all of the strings joined
807 together, with @separator between them.
810 <!-- ##### FUNCTION g_strjoinv ##### -->
812 Joins a number of strings together to form one long string, with the optional
813 @separator inserted between each of them.
816 @separator: a string to insert between each of the strings, or %NULL.
817 @str_array: a %NULL-terminated array of strings to join.
818 @Returns: a newly-allocated string containing all of the strings joined
819 together, with @separator between them.
822 <!-- ##### FUNCTION g_strerror ##### -->
824 Returns a string corresponding to the given error code, e.g. "no such process".
825 This function is included since not all platforms support the
826 <function>strerror()</function> function.
829 @errnum: the system error number. See the standard C %errno
831 @Returns: a string describing the error code.
832 If the error code is unknown, it returns "unknown error (<code>)".
833 The string can only be used until the next call to g_strerror.
836 <!-- ##### FUNCTION g_strsignal ##### -->
838 Returns a string describing the given signal, e.g. "Segmentation fault".
839 This function is included since not all platforms support the
840 <function>strsignal()</function> function.
843 @signum: the signal number. See the <literal>signal</literal>
845 @Returns: a string describing the signal.
846 If the signal is unknown, it returns "unknown signal (<signum>)".
847 The string can only be used until the next call to g_strsignal.