string_utils.sgml

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

<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>the buffer to hold the output.
</entry></row>
<row><entry align="right"><parameter>n</parameter>&nbsp;:</entry>
<entry>the maximum number of characters to produce (including the terminating nul
character).
</entry></row>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry>the format string. See the <function>sprintf()</function>.
documentation.
</entry></row>
<row><entry align="right"><parameter>...</parameter>&nbsp;:</entry>
<entry>the arguments to insert in the output.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the number of characters which would be produced if the buffer was
large enough.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-vsnprintf">g_vsnprintf ()</title>
<programlisting><link linkend="gint">gint</link>        g_vsnprintf                     (<link linkend="gchar">gchar</link> *string,
                                             <link linkend="gulong">gulong</link> n,
                                             <link linkend="gchar">gchar</link> const *format,
                                             va_list args);</programlisting>
<para>
A safer form of the standard <function><link linkend="vsprintf">vsprintf</link>()</function> function.
The output is guaranteed to not exceed <parameter>n</parameter> characters (including the
terminating nul character), so it is easy to ensure that a buffer overflow
cannot occur.
</para>
<para>
See also <link linkend="g-strdup-vprintf">g_strdup_vprintf</link>().
</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 <link linkend="g-vsnprintf">g_vsnprintf</link>() conforms to the <function><link linkend="vsnprintf">vsnprintf</link>()</function>
function as standardized in ISO C99. Note that this is different from 
traditional <function><link linkend="vsnprintf">vsnprintf</link>()</function>, which returns the length of 
the output string.
</para>
</note><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>the buffer to hold the output.
</entry></row>
<row><entry align="right"><parameter>n</parameter>&nbsp;:</entry>
<entry>the maximum number of characters to produce (including the terminating nul
character).
</entry></row>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry>the format string. See the <function>sprintf()</function>
documentation.
</entry></row>
<row><entry align="right"><parameter>args</parameter>&nbsp;:</entry>
<entry>the list of arguments to insert in the output.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the number of characters which would be produced if the buffer was
large enough.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-printf-string-upper-bound">g_printf_string_upper_bound ()</title>
<programlisting><link linkend="gsize">gsize</link>       g_printf_string_upper_bound     (const <link linkend="gchar">gchar</link> *format,
                                             va_list args);</programlisting>
<para>
Calculates the maximum space needed to store the output of the
<function>sprintf()</function> function.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry>the format string. See the <function>printf()</function>
documentation.
</entry></row>
<row><entry align="right"><parameter>args</parameter>&nbsp;:</entry>
<entry>the parameters to be inserted into the format string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the maximum space needed to store the formatted string.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-isalnum">g_ascii_isalnum ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_ascii_isalnum                 (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is alphanumeric.
</para>
<para>
Unlike the standard C library <function><link linkend="isalnum">isalnum</link>()</function> function, this only
recognizes standard ASCII letters and ignores the locale, returning
<literal>FALSE</literal> 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 <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a 
possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII alphanumeric character


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-isalpha">g_ascii_isalpha ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_ascii_isalpha                 (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is alphabetic (i.e. a letter).
</para>
<para>
Unlike the standard C library <function><link linkend="isalpha">isalpha</link>()</function> function, this only
recognizes standard ASCII letters and ignores the locale, returning
<literal>FALSE</literal> 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 <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a 
possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII alphabetic character


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-iscntrl">g_ascii_iscntrl ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_ascii_iscntrl                 (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is a control character.
</para>
<para>
Unlike the standard C library <function><link linkend="iscntrl">iscntrl</link>()</function> function, this only
recognizes standard ASCII control characters and ignores the locale,
returning <literal>FALSE</literal> 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 <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a 
possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII control character.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-isdigit">g_ascii_isdigit ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_ascii_isdigit                 (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is digit (0-9).
</para>
<para>
Unlike the standard C library <function><link linkend="isdigit">isdigit</link>()</function> function,
this takes a <type>char</type>, not an <type>int</type>, so don't call it
on <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a possibly
non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII digit.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-isgraph">g_ascii_isgraph ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_ascii_isgraph                 (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is a printing character and not a space.
</para>
<para>
Unlike the standard C library <function><link linkend="isgraph">isgraph</link>()</function> function, 
this only recognizes standard ASCII characters and ignores the locale, 
returning <literal>FALSE</literal> 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 <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a 
possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII printing character other than space.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-islower">g_ascii_islower ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_ascii_islower                 (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is an ASCII lower case letter.
</para>
<para>
Unlike the standard C library <function><link linkend="islower">islower</link>()</function> function, 
this only recognizes standard ASCII letters and ignores the locale,
returning <literal>FALSE</literal> 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 <literal>EOF</literal> but no need to worry about casting to <link linkend="guchar">guchar</link> 
before passing a possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>