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_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>
Splits a string into a maximum of @max_tokens pieces, using the given
@delimiter. If @max_tokens is reached, the final string in the returned
string array contains the remainder of @string.
</para>

@string: a string to split.
@delimiter: a string which specifies the places at which to split the string.
The delimiter is not included in any of the resulting strings, unless
max_tokens is reached.
@max_tokens: the maximum number of strings to split @string into. If this is
less than 1, the string is split completely.
@Returns: a newly-allocated array of strings. Use g_strfreev() to free it.


<!-- ##### 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.