string_utils.sgml

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

<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a string.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> length of <parameter>str</parameter> in bytes, or -1 if <parameter>str</parameter> is nul-terminated.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly allocated string, with all the lower case
              characters in <parameter>str</parameter> converted to upper case, with
              semantics that exactly match <link linkend="g-ascii-toupper">g_ascii_toupper</link>(). (Note
              that this is unlike the old <link linkend="g-strup">g_strup</link>(), which modified
              the string in place.)
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-strdown">g_ascii_strdown ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_ascii_strdown                 (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len);</programlisting>
<para>
Converts all upper case ASCII letters to lower case ASCII letters.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a string.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> length of <parameter>str</parameter> in bytes, or -1 if <parameter>str</parameter> is nul-terminated.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly-allocated string, with all the upper case
              characters in <parameter>str</parameter> converted to lower case, with
              semantics that exactly match <link linkend="g-ascii-tolower">g_ascii_tolower</link>(). (Note
              that this is unlike the old <link linkend="g-strdown">g_strdown</link>(), which modified
              the string in place.)
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-tolower">g_ascii_tolower ()</title>
<programlisting><link linkend="gchar">gchar</link>       g_ascii_tolower                 (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Convert a character to ASCII lower case.
</para>
<para>
Unlike the standard C library <link linkend="tolower">tolower</link>() function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are lower case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, 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>
<para>

</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> the result of converting <parameter>c</parameter> to lower case.
              If <parameter>c</parameter> is not an ASCII upper case letter,
              <parameter>c</parameter> is returned unchanged.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-toupper">g_ascii_toupper ()</title>
<programlisting><link linkend="gchar">gchar</link>       g_ascii_toupper                 (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Convert a character to ASCII upper case.
</para>
<para>
Unlike the standard C library <link linkend="toupper">toupper</link>() function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are upper case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, 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>
<para>

</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> the result of converting <parameter>c</parameter> to upper case.
              If <parameter>c</parameter> is not an ASCII lower case letter,
              <parameter>c</parameter> is returned unchanged.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-ascii-up">g_string_ascii_up ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_ascii_up               (<link linkend="GString">GString</link> *string);</programlisting>
<para>
Converts all lower case ASCII letters to upper case ASCII letters.</para>
<para>

</para><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> a GString
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> passed-in <parameter>string</parameter> pointer, with all the lower case
              characters converted to upper case in place, with
              semantics that exactly match g_ascii_toupper.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-ascii-down">g_string_ascii_down ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_ascii_down             (<link linkend="GString">GString</link> *string);</programlisting>
<para>
Converts all upper case ASCII letters to lower case ASCII letters.</para>
<para>

</para><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> a GString
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> passed-in <parameter>string</parameter> pointer, with all the upper case
              characters converted to lower case in place, with
              semantics that exactly match g_ascii_tolower.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strup">g_strup ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strup                         (<link linkend="gchar">gchar</link> *string);</programlisting>
<warning>
<para>
<literal>g_strup</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Converts a string to upper case. This function is totally broken
for the reasons discussed in the <link linkend="g-strncasecmp">g_strncasecmp</link>() docs - 
use <link linkend="g-ascii-strup">g_ascii_strup</link>() or <link linkend="g-utf8-strup">g_utf8_strup</link>() instead.
</para><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 string to convert.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strdown">g_strdown ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strdown                       (<link linkend="gchar">gchar</link> *string);</programlisting>
<warning>
<para>
<literal>g_strdown</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Converts a string to lower case.  This function is totally broken for
the reasons discussed in the <link linkend="g-strncasecmp">g_strncasecmp</link>() docs - use
<link linkend="g-ascii-strdown">g_ascii_strdown</link>() or <link linkend="g-utf8-strdown">g_utf8_strdown</link>() instead.
</para><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 string to convert.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strcasecmp">g_strcasecmp ()</title>
<programlisting><link linkend="gint">gint</link>        g_strcasecmp                    (const <link linkend="gchar">gchar</link> *s1,
                                             const <link linkend="gchar">gchar</link> *s2);</programlisting>
<warning>
<para>
<literal>g_strcasecmp</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
A case-insensitive string comparison, corresponding to the standard
<function><link linkend="strcasecmp">strcasecmp</link>()</function> function on platforms which support it.
</para>
<para>
See <link linkend="g-strncasecmp">g_strncasecmp</link>() for a discussion of why this is deprecated and
how to replace it.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>s1</parameter>&nbsp;:</entry>
<entry>a string.
</entry></row>
<row><entry align="right"><parameter>s2</parameter>&nbsp;:</entry>
<entry>a string to compare with <parameter>s1</parameter>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>0 if the strings match, a negative value if <parameter>s1</parameter> < <parameter>s2</parameter>, or a positive
value if <parameter>s1</parameter> > <parameter>s2</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strncasecmp">g_strncasecmp ()</title>
<programlisting><link linkend="gint">gint</link>        g_strncasecmp                   (const <link linkend="gchar">gchar</link> *s1,
                                             const <link linkend="gchar">gchar</link> *s2,
                                             <link linkend="guint">guint</link> n);</programlisting>
<warning>
<para>
<literal>g_strncasecmp</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
A case-insensitive string comparison, corresponding to the standard
<function><link linkend="strncasecmp">strncasecmp</link>()</function> function on platforms which support it.
It is similar to <link linkend="g-strcasecmp">g_strcasecmp</link>() except it only compares the first <parameter>n</parameter> characters
of the strings.
</para>
<para>
The problem with <link linkend="g-strncasecmp">g_strncasecmp</link>() is th