string_utils.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

</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: 
<!-- # Unused Parameters # -->
@string: 


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

</para>

@str: 
@len: 
@Returns: 
<!-- # Unused Parameters # -->
@string: 


<!-- ##### 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. This function is totally broken
for the reasons discussed in the g_strncasecmp() docs - 
use g_ascii_strup() or g_utf8_strup() instead.
</para>

@string: the string to convert.
@Returns: 


<!-- ##### FUNCTION g_strdown ##### -->
<para>
Converts a string to lower case.  This function is totally broken for
the reasons discussed in the g_strncasecmp() docs - use
g_ascii_strdown() or g_utf8_strdown() instead.
</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>
<para>
See g_strncasecmp() for a discussion of why this is deprecated and
how to replace 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>
<para>
The problem with g_strncasecmp() is that it does the comparison by
calling <function>toupper()</function>/<function>tolower()</function> 
on each byte. <function>toupper()</function>/<function>tolower()</function> are
locale-specific and operate on single bytes. However, it is impossible
to handle things correctly from an i18n standpoint by operating on
bytes, since characters may be multibyte. Thus g_strncasecmp() is
broken if your string is guaranteed to be ASCII, since it's
locale-sensitive, and it's broken if your string is localized, since
it doesn't work on many encodings at all, including UTF-8, EUC-JP,
etc.
</para>
<para>
There are therefore two replacement functions: g_ascii_strncasecmp(),
which only works on ASCII and is not locale-sensitive, and
g_utf8_casefold(), which is good for case-insensitive sorting of
UTF-8.
</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, <literal>g_strreverse ("abcdef")</literal> will result in "fedcba".
</para>

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


<!-- ##### 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=%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: 
<!-- # Unused Parameters # -->
@format: 


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

@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 <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_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.