string_utils.sgml

This GLib version 2.16.1. GLib is the low-level core library that forms the basis for projects such

returning %FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
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 character
@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 takes a <type>char</type>, not an <type>int</type>, 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 character
@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>

@str: 
@len: 
@Returns: 


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

</para>

@str: 
@len: 
@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>
</para>

@string: 
@Returns: 


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

@string: 
@Returns: 


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

@s1: 
@s2: 
@Returns: 


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

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


<!-- ##### FUNCTION g_strreverse ##### -->
<para>
Reverses all of the bytes in a string.
For example, <literal>g_strreverse ("abcdef")</literal> will result in "fedcba".
</para>
<para>
Note that g_strreverse() doesn't work on UTF-8 strings containing multibyte characters. 
For that purpose, use g_utf8_strreverse().
</para>

@string: the string to reverse.
@Returns: the same pointer passed in as @string.


<!-- ##### FUNCTION g_ascii_strtoll ##### -->
<para>

</para>

@nptr: 
@endptr: 
@base: 
@Returns: 


<!-- ##### FUNCTION g_ascii_strtoull ##### -->
<para>

</para>

@nptr: 
@endptr: 
@base: 
@Returns: 


<!-- ##### MACRO G_ASCII_DTOSTR_BUF_SIZE ##### -->
<para>
A good size for a buffer to be passed into g_ascii_dtostr().
It is guaranteed to be enough for all output of that function on systems with
 64bit IEEE-compatible doubles.
</para>
<para>
The typical usage would be something like:
<informalexample><programlisting>
  char buf[G_ASCII_DTOSTR_BUF_SIZE];

  fprintf (out, "value=&percnt;s\n", g_ascii_dtostr (buf, sizeof (buf), value));
</programlisting></informalexample>
</para>



<!-- ##### FUNCTION g_ascii_strtod ##### -->
<para>

</para>

@nptr: 
@endptr: 
@Returns: 


<!-- ##### FUNCTION g_ascii_dtostr ##### -->
<para>

</para>

@buffer: 
@buf_len: 
@d: 
@Returns: 


<!-- ##### FUNCTION g_ascii_formatd ##### -->
<para>

</para>

@buffer: 
@buf_len: 
@format: 
@d: 
@Returns: 


<!-- ##### FUNCTION g_strtod ##### -->
<para>

</para>

@nptr: 
@endptr: 
@Returns: 


<!-- ##### FUNCTION g_strchug ##### -->
<para>
Removes leading whitespace from a string, by moving the rest of the
characters forward.
</para>
<para>
This function doesn't allocate or reallocate any memory; it modifies @string
in place. The pointer to @string is returned to allow the nesting of functions.
</para>
<para>
Also see g_strchomp() and g_strstrip().
</para>

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


<!-- ##### FUNCTION g_strchomp ##### -->
<para>
Removes trailing whitespace from a string.
</para>
<para>
This function doesn't allocate or reallocate any memory; it modifies @string in
place. The pointer to @string is returned to allow the nesting of functions.
</para>
<para>
Also see g_strchug() and g_strstrip().
</para>

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


<!-- ##### MACRO g_strstrip ##### -->
<para>
Removes leading and trailing whitespace from a string. See g_strchomp() and
g_strchug().
</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. Modifies @string in place, and returns 
@string itself, not a copy. The return value is to allow nesting such as
<literal>g_ascii_strup (g_strdelimit (str, "abc", '?'))</literal>.
</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: @string.


<!-- ##### 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 0x7F-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 <literal>g_ascii_strup (g_strcanon (str, "abc", '?'))</literal>.
</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_strsplit_set ##### -->
<para>

</para>

@string: 
@delimiters: 
@max_tokens: 
@Returns: 


<!-- ##### FUNCTION g_strfreev ##### -->
<para>

</para>

@str_array: 


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

<warning><para>
The variable argument list <emphasis>must</emphasis> end with %NULL. 
If you forget the %NULL, g_strconcat() will start appending
random memory junk to your string.
</para></warning>

@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_strv_length ##### -->
<para>

</para>

@str_array: 
@Returns: 


<!-- ##### FUNCTION g_strerror ##### -->
<para>
Returns a string corresponding to the given error code, e.g. "no such process".
You should use this function in preference to strerror(), because it returns a
string in UTF-8 encoding, and since not all platforms support the 
strerror() function.
</para>

@errnum: the system error number. See the standard C %errno
documentation.
@Returns: a UTF-8 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".
You should use this function in preference to strsignal(), because it returns a
string in UTF-8 encoding, and since not all platforms support the
strsignal() function.
</para>

@signum: the signal number. See the <literal>signal</literal>
documentation.
@Returns: a UTF-8 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().