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

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

<!-- ##### SECTION Long_Description ##### -->
<para>
These are various functions related to strings.
Some of them are provided because not all platforms include the function.
</para>

<!-- ##### 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_strconcat ##### -->
<para>
Concatenates all of the given strings into one long string.
The returned string should be freed when no longer needed.
</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.

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


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

<!-- ##### 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, and null-terminates it.
If @str is NULL, NULL is returned.
The returned string should be freed when no longer needed.
</para>

@str: the string to duplicate part of.
@n: the number of characters to copy, which must be less than or equal to the
length of @str.
@Returns: a newly-allocated copy of the first @n characters of @str,
null-terminated.

<!-- ##### 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_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 
<citerefentry><refentrytitle>vsprintf</refentrytitle>
<manvolnum>3</manvolnum></citerefentry>
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_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_strreverse ##### -->
<para>
Reverses all of the characters in a string.
For example, g_strreverse ("abcdef") would be "fedcba".
</para>

@string: the string to reverse.

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

<!-- ##### 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_strup ##### -->
<para>
Converts a string to upper case.
</para>

@string: the string to convert.

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

@string: the string to convert.

