glib/docs/reference/glib/tmpl/string_utils.sgml

<!-- ##### SECTION Title ##### -->
String Utility Functions

<!-- ##### SECTION Short_Description ##### -->
various string-related functions.

<!-- ##### SECTION Long_Description ##### -->
<para>
This section describes a number of utility functions for creating,
duplicating, and manipulating strings.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### FUNCTION g_strdup ##### -->
<para>
Duplicates a string.
The returned string should be freed when no longer needed.
</para>

@str: the string to duplicate.
@Returns: a newly-allocated copy of @str.


<!-- ##### FUNCTION g_strndup ##### -->
<para>
Duplicates the first @n characters of a string, returning a newly-allocated
buffer @n + 1 characters long which will always be null-terminated.
If @str is less than @n characters long the buffer is padded with nulls.
The returned value should be freed when no longer needed.
</para>

@str: the string to duplicate part of.
@n: the maximum number of characters to copy from @str.
@Returns: a newly-allocated buffer containing the first @n characters of @str,
null-terminated.


<!-- ##### FUNCTION g_strdupv ##### -->
<para>
Copies a %NULL-terminated array of strings. The result consists of a
%NULL-terminated array, with one malloc block holding the array of strings, and
each string itself allocated. The simplest way to free the result is with
g_strfreev() which frees each string in a vector, then the vector itself.
</para>

@str_array: array to copy
@Returns: a new array


<!-- ##### FUNCTION g_strnfill ##### -->
<para>
Creates a new string @length characters long filled with @fill_char.
The returned string should be freed when no longer needed.
</para>

@length: the length of the new string.
@fill_char: the character to fill the string with.
@Returns: a newly-allocated string filled the @fill_char.


<!-- ##### FUNCTION g_stpcpy ##### -->
<para>

</para>

@dest: 
@src: 
@Returns: 


<!-- ##### FUNCTION g_strlcpy ##### -->
<para>
Portability wrapper that calls strlcpy() on systems which have it, and emulates
strlcpy() otherwise. Copies @src to @dest; @dest is guaranteed to be
nul-terminated; @src must be nul-terminated; @dest_size is the buffer size, not
the number of chars to copy. Caveat: strlcpy() is supposedly more secure than
strcpy() or strncpy(), but if you really want to avoid screwups, g_strdup() is
an even better idea.
</para>

@dest: destination buffer
@src: source buffer
@dest_size: length of @dest in bytes
@Returns: length of @src


<!-- ##### FUNCTION g_strlcat ##### -->
<para>
Portability wrapper that calls strlcat() on systems which have it, and emulates
strlcat() otherwise. Appends nul-terminated @src string to @dest, guaranteeing
nul-termination for @dest. The total size of @dest won't exceed
@dest_size. Caveat: this is supposedly a more secure alternative to strcat() or
strncat(), but for real security g_strconcat() is harder to mess up.
</para>

@dest: destination buffer, already containing one nul-terminated string
@src: source buffer
@dest_size: length of @dest buffer in bytes (not length of existing string inside @dest)
@Returns: length of @src plus initial length of string in @dest


<!-- ##### FUNCTION g_strdup_printf ##### -->
<para>
Similar to the standard C <function>sprintf()</function> function
but safer, since it calculates the maximum space required and allocates
memory to hold the result.
The returned string should be freed when no longer needed.
</para>

@format: the standard <function>sprintf()</function> format string.
@Varargs: the parameters to insert into the format string.
@Returns: a newly-allocated string holding the result.


<!-- ##### FUNCTION g_strdup_vprintf ##### -->
<para>
Similar to the standard C <function>vsprintf()</function> function
but safer, since it calculates the maximum space required and allocates
memory to hold the result.
The returned string should be freed when no longer needed.
</para>

@format: the standard <function>sprintf()</function> format string.
@args: the list of parameters to insert into the format string.
@Returns: a newly-allocated string holding the result.


<!-- ##### FUNCTION g_snprintf ##### -->
<para>
A safer form of the standard <function>sprintf()</function> function.
The output is guaranteed to not exceed @n characters (including the
terminating NULL character), so it is easy to ensure that a buffer overflow
cannot occur.
</para>
<para>
See also g_strdup_printf().
</para>
<note>
<para>
In versions of GLib prior to 1.2.3, this function may return -1 if the output
was truncated, and the truncated string may not be NULL-terminated.
</para>
</note>

@string: the buffer to hold the output.
@n: the maximum number of characters to produce (including the terminating null
character).
@format: the format string. See the <function>sprintf()</function>
documentation.
@Varargs: the arguments to insert in the output.
@Returns: the length of the output string.


<!-- ##### FUNCTION g_vsnprintf ##### -->
<para>
A safer form of the standard <function>vsprintf()</function> function.
The output is guaranteed to not exceed @n characters (including the
terminating NULL character), so it is easy to ensure that a buffer overflow
cannot occur.
</para>
<para>
See also g_strdup_vprintf().
</para>
<note>
<para>
In versions of GLib prior to 1.2.3, this function may return -1 if the output
was truncated, and the truncated string may not be NULL-terminated.
</para>
</note>

@string: the buffer to hold the output.
@n: the maximum number of characters to produce (including the terminating null
character).
@format: the format string. See the <function>sprintf()</function>
documentation.
@args: the list of arguments to insert in the output.
@Returns: the length of the output string.


<!-- ##### FUNCTION g_printf_string_upper_bound ##### -->
<para>
Calculates the maximum space needed to store the output of the
<function>sprintf()</function> function.
</para>

@format: the format string. See the <function>printf()</function>
documentation.
@args: the parameters to be inserted into the format string.
@Returns: the maximum space needed to store the formatted string.


<!-- ##### FUNCTION g_ascii_isalnum ##### -->
<para>
Determines whether a character is alphanumeric.
</para>
<para>
Unlike the standard C library isalnum function, this only
recognizes standard ASCII letters and ignores the locale, returning
%FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a char, not an int, so don't call it
on EOF but no need to cast to guchar before passing a possibly
non-ASCII character in.
</para>

@c: any characted
@Returns: %TRUE if @c is an ASCII alphanumeric character


<!-- ##### FUNCTION g_ascii_isalpha ##### -->
<para>
Determines whether a character is alphabetic (i.e. a letter).
</para>
<para>
Unlike the standard C library isalpha function, this only
recognizes standard ASCII letters and ignores the locale, returning
%FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a char, not an int, so don't call it
on EOF but no need to cast to guchar before passing a possibly
non-ASCII character in.
</para>

@c: any characted
@Returns: %TRUE if @c is an ASCII alphabetic character


<!-- ##### FUNCTION g_ascii_iscntrl ##### -->
<para>
Determines whether a character is a control character.
</para>
<para>
Unlike the standard C library iscntrl function, this only
recognizes standard ASCII control characters and ignores the locale,
returning%FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a char, not an int, so don't call it
on EOF but no need to cast to guchar before passing a possibly
non-ASCII character in.
</para>

@c: any characted
@Returns: %TRUE if @c is an ASCII control character.


<!-- ##### FUNCTION g_ascii_isdigit ##### -->
<para>
Determines whether a character is digit (0-9).
</para>
<para>
Unlike the standard C library isdigit function, this only
recognizes standard ASCII digits and ignores the locale, returning
%FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a char, not an int, so don't call it
on EOF but no need to cast to guchar before passing a possibly
non-ASCII character in.
</para>

@c: any characted
@Returns: %TRUE if @c is an ASCII digit.


<!-- ##### FUNCTION g_ascii_isgraph ##### -->
<para>
Determines whether a character is a printing character and not a space.
</para>
<para>
Unlike the standard C library isgraph function, this only
recognizes standard ASCII characters and ignores the locale, returning
%FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a char, not an int, so don't call it
on EOF but no need to cast to guchar before passing a possibly
non-ASCII character in.
</para>

@c: any characted
@Returns: %TRUE if @c is an ASCII printing character other than space.


<!-- ##### FUNCTION g_ascii_islower ##### -->
<para>
Determines whether a character is an ASCII lower case letter.
</para>
<para>
Unlike the standard C library islower function, this only
recognizes standard ASCII letters and ignores the locale, returning
%FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a char, not an int, so don't call it
on EOF but no need to worry about casting to guchar before passing
a possibly non-ASCII character in.
</para>

@c: any characted
@Returns: %TRUE if @c is an ASCII lower case letter


<!-- ##### FUNCTION g_ascii_isprint ##### -->
<para>
Determines whether a character is a printing character.
</para>
<para>
Unlike the standard C library isprint function, this only
recognizes standard ASCII characters and ignores the locale, returning
%FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a char, not an int, so don't call it
on EOF but no need to cast to guchar before passing a possibly
non-ASCII character in.
</para>

@c: any characted
@Returns: %TRUE if @c is an ASCII printing character.


<!-- ##### FUNCTION g_ascii_ispunct ##### -->
<para>
Determines whether a character is a punctuation character.
</para>
<para>
Unlike the standard C library ispunct function, this only
recognizes standard ASCII letters and ignores the locale, returning
%FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a char, not an int, so don't call it
on EOF but no need to cast to guchar before passing a possibly
non-ASCII character in.
</para>

@c: any characted
@Returns: %TRUE if @c is an ASCII punctuation character.


<!-- ##### FUNCTION g_ascii_isspace ##### -->
<para>
Determines whether a character is a white-space character.
</para>
<para>
Unlike the standard C library isspace function, this only
recognizes standard ASCII white-space and ignores the locale, returning
%FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a char, not an int, so don't call it
on EOF but no need to cast to guchar before passing a possibly
non-ASCII character in.
</para>

@c: any characted
@Returns: %TRUE if @c is an ASCII white-space character


<!-- ##### FUNCTION g_ascii_isupper ##### -->
<para>
Determines whether a character is an ASCII upper case letter.
</para>
<para>
Unlike the standard C library isupper function, this only
recognizes standard ASCII letters and ignores the locale, returning
%FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a char, not an int, so don't call it
on EOF but no need to worry about casting to guchar before passing
a possibly non-ASCII character in.
</para>

@c: any characted
@Returns: %TRUE if @c is an ASCII upper case letter


<!-- ##### FUNCTION g_ascii_isxdigit ##### -->
<para>
Determines whether a character is a hexadecimal-digit character.
</para>
<para>
Unlike the standard C library isxdigit function, this only
recognizes standard ASCII hexadecimal digits and ignores the
locale, returning %FALSE for all non-ASCII characters. Also unlike
the standard library function, this takes a char, not an int, so
don't call it on EOF but no need to cast to guchar before passing a
possibly non-ASCII character in.
</para>

@c: any characted
@Returns: %TRUE if @c is an ASCII hexadecimal-digit character.


<!-- ##### FUNCTION g_ascii_digit_value ##### -->
<para>

</para>

@c: 
@Returns: 


<!-- ##### FUNCTION g_ascii_xdigit_value ##### -->
<para>

</para>

@c: 
@Returns: 


<!-- ##### FUNCTION g_ascii_strcasecmp ##### -->
<para>

</para>

@s1: 
@s2: 
@Returns: 


<!-- ##### FUNCTION g_ascii_strncasecmp ##### -->
<para>

</para>

@s1: 
@s2: 
@n: 
@Returns: 


<!-- ##### FUNCTION g_ascii_strup ##### -->
<para>

</para>

@string: 
@Returns: 


<!-- ##### FUNCTION g_ascii_strdown ##### -->
<para>

</para>

@string: 
@Returns: 


<!-- ##### FUNCTION g_ascii_tolower ##### -->
<para>

</para>

@c: 
@Returns: 


<!-- ##### FUNCTION g_ascii_toupper ##### -->
<para>

</para>

@c: 
@Returns: 


<!-- ##### FUNCTION g_string_ascii_up ##### -->
<para>

</para>

@string: 
@Returns: 


<!-- ##### FUNCTION g_string_ascii_down ##### -->
<para>

</para>

@string: 
@Returns: 


<!-- ##### FUNCTION g_strup ##### -->
<para>
Converts a string to upper case.
</para>

@string: the string to convert.
@Returns: 


<!-- ##### FUNCTION g_strdown ##### -->
<para>
Converts a string to lower case.
</para>

@string: the string to convert.
@Returns: 


<!-- ##### FUNCTION g_strcasecmp ##### -->
<para>
A case-insensitive string comparison, corresponding to the standard
<function>strcasecmp()</function> function on platforms which support it.
</para>

@s1: a string.
@s2: a string to compare with @s1.
@Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
value if @s1 > @s2.


<!-- ##### FUNCTION g_strncasecmp ##### -->
<para>
A case-insensitive string comparison, corresponding to the standard
<function>strncasecmp()</function> function on platforms which support it.
It is similar to g_strcasecmp() except it only compares the first @n characters
of the strings.
</para>

@s1: a string.
@s2: a string to compare with @s1.
@n: the maximum number of characters to compare.
@Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
value if @s1 > @s2.


<!-- ##### FUNCTION g_strreverse ##### -->
<para>
Reverses all of the characters in a string.
For example, g_strreverse ("abcdef") would be "fedcba".
</para>

@string: the string to reverse.
@Returns: 


<!-- ##### FUNCTION g_strtod ##### -->
<para>
Converts a string to a gdouble value.
It calls the standard <function>strtod()</function> function
to handle the conversion, but if the string is not completely converted
it attempts the conversion again in the "C" locale, and returns the best
match.
</para>

@nptr: the string to convert to a numeric value.
@endptr: if non-NULL, it returns the character after the last character used
in the conversion.
@Returns: the gdouble value.


<!-- ##### FUNCTION g_strchug ##### -->
<para>
Removes leading whitespace from a string, by moving the rest of the
characters forward.
</para>

@string: a string to remove the leading whitespace from.
@Returns: @string.


<!-- ##### FUNCTION g_strchomp ##### -->
<para>
Removes trailing whitespace from a string.
</para>

@string: a string to remove the trailing whitespace from.
@Returns: @string.


<!-- ##### MACRO g_strstrip ##### -->
<para>
Removes leading and trailing whitespace from a string.
</para>

@string: a string to remove the leading and trailing whitespace from.


<!-- ##### FUNCTION g_strdelimit ##### -->
<para>
Converts any delimiter characters in @string to @new_delimiter.
Any characters in @string which are found in @delimiters are changed
to the @new_delimiter character.
</para>

@string: the string to convert.
@delimiters: a string containing the current delimiters, or NULL to use the
standard delimiters defined in #G_STR_DELIMITERS.
@new_delimiter: the new delimiter character.
@Returns: 


<!-- ##### MACRO G_STR_DELIMITERS ##### -->
<para>
The standard delimiters, used in #g_strdelimit.
</para>



<!-- ##### FUNCTION g_strescape ##### -->
<para>
Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\' and
'&quot;' in the string @source by inserting a '\' before
them. Additionally all characters in the range 0x01-0x1F (everything
below SPACE) and in the range 0x80-0xFF (all non-ASCII chars) are
replaced with a '\' followed by their octal representation. Characters
supplied in @exceptions are not escaped.
</para>

<para>
g_strcompress() does the reverse conversion.
</para>

@source: a string to escape.
@exceptions: a string of characters not to escape in @source.
@Returns: a newly allocated copy of @source with certain
characters escaped. See above.


<!-- ##### FUNCTION g_strcompress ##### -->
<para>
Replaces all escaped characters with their one byte equivalent. It
does the reverse conversion of g_strescape(). 
</para>

@source: a string to compress.
@Returns: a newly allocated copy of @source with all escaped 
character compressed.


<!-- ##### FUNCTION g_strcanon ##### -->
<para>
For each character in @string, if the character is not in @valid_chars,
replaces the character with @substitutor. Modifies @string in place, 
and return @string itself, not a copy. The return value is to allow
nesting such as g_strup (g_strcanon (str)).
</para>

@string: a nul-terminated array of bytes
@valid_chars: bytes permitted in @string
@substitutor: replacement character for disallowed bytes
@Returns: @string


<!-- ##### FUNCTION g_strsplit ##### -->
<para>
</para>

@string: 
@delimiter: 
@max_tokens: 
@Returns: 


<!-- ##### FUNCTION g_strfreev ##### -->
<para>
Frees a NULL-terminated array of strings, and the array itself.
</para>

@str_array: a NULL-terminated array of strings to free.


<!-- ##### FUNCTION g_strconcat ##### -->
<para>
Concatenates all of the given strings into one long string.  The returned string
should be freed when no longer needed.  WARNING: THE VARIABLE ARGUMENT LIST MUST
END WITH %NULL. If you forget the %NULL, g_strconcat() will start appending
random memory junk to your string.
</para>

@string1: The first string to add, which must not be NULL.
@Varargs: a NULL-terminated list of strings to append to the string.
@Returns: a newly-allocated string containing all the string arguments.


<!-- ##### FUNCTION g_strjoin ##### -->
<para>
Joins a number of strings together to form one long string, with the optional
@separator inserted between each of them.
</para>

@separator: a string to insert between each of the strings, or NULL.
@Varargs: a NULL-terminated list of strings to join.
@Returns: a newly-allocated string containing all of the strings joined
together, with @separator between them.


<!-- ##### FUNCTION g_strjoinv ##### -->
<para>
Joins a number of strings together to form one long string, with the optional
@separator inserted between each of them.
</para>

@separator: a string to insert between each of the strings, or NULL.
@str_array: a NULL-terminated array of strings to join.
@Returns: a newly-allocated string containing all of the strings joined
together, with @separator between them.


<!-- ##### FUNCTION g_strerror ##### -->
<para>
Returns a string corresponding to the given error code, e.g. "no such process".
This function is included since not all platforms support the 
<function>strerror()</function> function.
</para>

@errnum: the system error number. See the standard C %errno
documentation.
@Returns: a string describing the error code.
If the error code is unknown, it returns "unknown error (&lt;code&gt;)".
The string can only be used until the next call to g_strerror.


<!-- ##### FUNCTION g_strsignal ##### -->
<para>
Returns a string describing the given signal, e.g. "Segmentation fault".
This function is included since not all platforms support the
<function>strsignal()</function> function.
</para>

@signum: the signal number. See the <literal>signal</literal>
documentation.
@Returns: a string describing the signal.
If the signal is unknown, it returns "unknown signal (&lt;signum&gt;)".
The string can only be used until the next call to g_strsignal.