string_utils.sgml

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

<!-- ##### 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 nul-terminated.
If @str is less than @n characters long the buffer is padded with nuls.
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,
nul-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_strstr_len ##### -->
<para>

</para>

@haystack: 
@haystack_len: 
@needle: 
@Returns: 


<!-- ##### FUNCTION g_strrstr ##### -->
<para>

</para>

@haystack: 
@needle: 
@Returns: 


<!-- ##### FUNCTION g_strrstr_len ##### -->
<para>

</para>

@haystack: 
@haystack_len: 
@needle: 
@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 <function>strlcat()</function> on systems which have it, and emulates it 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 <function>strcat()</function> or
<function>strncat()</function>, 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 nul 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 nul-terminated. 
In versions prior to 1.3.12, this function returns the length of the output 
string.
</para>
</note>
<note>
<para>
The return value of g_snprintf() conforms to the <function>snprintf()</function>
function as standardized in ISO C99. Note that this is different from 
traditional <function>snprintf()</function>, which returns the length of 
the output string.
</para>
</note>

@string: the buffer to hold the output.
@n: the maximum number of characters to produce (including the terminating nul
character).
@format: the format string. See the <function>sprintf()</function>.
documentation.
@Varargs: the arguments to insert in the output.
@Returns: the number of characters which would be produced if the buffer was
large enough.


<!-- ##### 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 nul 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 nul-terminated.
In versions prior to 1.3.12, this function returns the length of the output 
string.
</para>
</note>
<note>
<para>
The return value of g_vsnprintf() conforms to the <function>vsnprintf()</function>
function as standardized in ISO C99. Note that this is different from 
traditional <function>vsnprintf()</function>, which returns the length of 
the output string.
</para>
</note>

@string: the buffer to hold the output.
@n: the maximum number of characters to produce (including the terminating nul
character).
@format: the format string. See the <function>sprintf()</function>
documentation.
@args: the list of arguments to insert in the output.
@Returns: the number of characters which would be produced if the buffer was
large enough.


<!-- ##### 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 <function>isalnum()</function> 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 <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 alphanumeric character


<!-- ##### FUNCTION g_ascii_isalpha ##### -->
<para>
Determines whether a character is alphabetic (i.e. a letter).
</para>
<para>
Unlike the standard C library <function>isalpha()</function> 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 <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 alphabetic character


<!-- ##### FUNCTION g_ascii_iscntrl ##### -->
<para>
Determines whether a character is a control character.
</para>
<para>
Unlike the standard C library <function>iscntrl()</function> 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 <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 control character.


<!-- ##### FUNCTION g_ascii_isdigit ##### -->
<para>
Determines whether a character is digit (0-9).
</para>
<para>
Unlike the standard C library <function>isdigit()</function> 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 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 <function>isgraph()</function> 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 <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 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 <function>islower()</function> 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 <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 lower case letter


<!-- ##### FUNCTION g_ascii_isprint ##### -->
<para>
Determines whether a character is a printing character.
</para>
<para>
Unlike the standard C library <function>isprint()</function> 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 <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 printing character.


<!-- ##### FUNCTION g_ascii_ispunct ##### -->
<para>
Determines whether a character is a punctuation character.
</para>
<para>
Unlike the standard C library <function>ispunct()</function> 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 <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 punctuation character.


<!-- ##### FUNCTION g_ascii_isspace ##### -->
<para>
Determines whether a character is a white-space character.
</para>
<para>
Unlike the standard C library <function>isspace()</function> 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 <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 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 <function>isupper()</function> 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 <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 <function>isxdigit()</function> 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.