string_utils.sgml

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

<refentry id="glib-String-Utility-Functions">
<refmeta>
<refentrytitle>String Utility Functions</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>String Utility Functions</refname><refpurpose>various string-related functions.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


<link linkend="gchar">gchar</link>*      <link linkend="g-strdup">g_strdup</link>                        (const <link linkend="gchar">gchar</link> *str);
<link linkend="gchar">gchar</link>*      <link linkend="g-strndup">g_strndup</link>                       (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gsize">gsize</link> n);
<link linkend="gchar">gchar</link>**     <link linkend="g-strdupv">g_strdupv</link>                       (<link linkend="gchar">gchar</link> **str_array);
<link linkend="gchar">gchar</link>*      <link linkend="g-strnfill">g_strnfill</link>                      (<link linkend="gsize">gsize</link> length,
                                             <link linkend="gchar">gchar</link> fill_char);
<link linkend="gchar">gchar</link>*      <link linkend="g-stpcpy">g_stpcpy</link>                        (<link linkend="gchar">gchar</link> *dest,
                                             const char *src);
<link linkend="gchar">gchar</link>*      <link linkend="g-strstr-len">g_strstr_len</link>                    (const <link linkend="gchar">gchar</link> *haystack,
                                             <link linkend="gssize">gssize</link> haystack_len,
                                             const <link linkend="gchar">gchar</link> *needle);
<link linkend="gchar">gchar</link>*      <link linkend="g-strrstr">g_strrstr</link>                       (const <link linkend="gchar">gchar</link> *haystack,
                                             const <link linkend="gchar">gchar</link> *needle);
<link linkend="gchar">gchar</link>*      <link linkend="g-strrstr-len">g_strrstr_len</link>                   (const <link linkend="gchar">gchar</link> *haystack,
                                             <link linkend="gssize">gssize</link> haystack_len,
                                             const <link linkend="gchar">gchar</link> *needle);

<link linkend="gsize">gsize</link>       <link linkend="g-strlcpy">g_strlcpy</link>                       (<link linkend="gchar">gchar</link> *dest,
                                             const <link linkend="gchar">gchar</link> *src,
                                             <link linkend="gsize">gsize</link> dest_size);
<link linkend="gsize">gsize</link>       <link linkend="g-strlcat">g_strlcat</link>                       (<link linkend="gchar">gchar</link> *dest,
                                             const <link linkend="gchar">gchar</link> *src,
                                             <link linkend="gsize">gsize</link> dest_size);

<link linkend="gchar">gchar</link>*      <link linkend="g-strdup-printf">g_strdup_printf</link>                 (const <link linkend="gchar">gchar</link> *format,
                                             ...);
<link linkend="gchar">gchar</link>*      <link linkend="g-strdup-vprintf">g_strdup_vprintf</link>                (const <link linkend="gchar">gchar</link> *format,
                                             va_list args);
<link linkend="gint">gint</link>        <link linkend="g-snprintf">g_snprintf</link>                      (<link linkend="gchar">gchar</link> *string,
                                             <link linkend="gulong">gulong</link> n,
                                             <link linkend="gchar">gchar</link> const *format,
                                             ...);
<link linkend="gint">gint</link>        <link linkend="g-vsnprintf">g_vsnprintf</link>                     (<link linkend="gchar">gchar</link> *string,
                                             <link linkend="gulong">gulong</link> n,
                                             <link linkend="gchar">gchar</link> const *format,
                                             va_list args);
<link linkend="gsize">gsize</link>       <link linkend="g-printf-string-upper-bound">g_printf_string_upper_bound</link>     (const <link linkend="gchar">gchar</link> *format,
                                             va_list args);

<link linkend="gboolean">gboolean</link>    <link linkend="g-ascii-isalnum">g_ascii_isalnum</link>                 (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-ascii-isalpha">g_ascii_isalpha</link>                 (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-ascii-iscntrl">g_ascii_iscntrl</link>                 (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-ascii-isdigit">g_ascii_isdigit</link>                 (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-ascii-isgraph">g_ascii_isgraph</link>                 (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-ascii-islower">g_ascii_islower</link>                 (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-ascii-isprint">g_ascii_isprint</link>                 (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-ascii-ispunct">g_ascii_ispunct</link>                 (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-ascii-isspace">g_ascii_isspace</link>                 (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-ascii-isupper">g_ascii_isupper</link>                 (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-ascii-isxdigit">g_ascii_isxdigit</link>                (<link linkend="gchar">gchar</link> c);

<link linkend="gint">gint</link>        <link linkend="g-ascii-digit-value">g_ascii_digit_value</link>             (<link linkend="gchar">gchar</link> c);
<link linkend="gint">gint</link>        <link linkend="g-ascii-xdigit-value">g_ascii_xdigit_value</link>            (<link linkend="gchar">gchar</link> c);

<link linkend="gint">gint</link>        <link linkend="g-ascii-strcasecmp">g_ascii_strcasecmp</link>              (const <link linkend="gchar">gchar</link> *s1,
                                             const <link linkend="gchar">gchar</link> *s2);
<link linkend="gint">gint</link>        <link linkend="g-ascii-strncasecmp">g_ascii_strncasecmp</link>             (const <link linkend="gchar">gchar</link> *s1,
                                             const <link linkend="gchar">gchar</link> *s2,
                                             <link linkend="gsize">gsize</link> n);

<link linkend="gchar">gchar</link>*      <link linkend="g-ascii-strup">g_ascii_strup</link>                   (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len);
<link linkend="gchar">gchar</link>*      <link linkend="g-ascii-strdown">g_ascii_strdown</link>                 (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len);

<link linkend="gchar">gchar</link>       <link linkend="g-ascii-tolower">g_ascii_tolower</link>                 (<link linkend="gchar">gchar</link> c);
<link linkend="gchar">gchar</link>       <link linkend="g-ascii-toupper">g_ascii_toupper</link>                 (<link linkend="gchar">gchar</link> c);

<link linkend="GString">GString</link>*    <link linkend="g-string-ascii-up">g_string_ascii_up</link>               (<link linkend="GString">GString</link> *string);
<link linkend="GString">GString</link>*    <link linkend="g-string-ascii-down">g_string_ascii_down</link>             (<link linkend="GString">GString</link> *string);

<link linkend="gchar">gchar</link>*      <link linkend="g-strup">g_strup</link>                         (<link linkend="gchar">gchar</link> *string);
<link linkend="gchar">gchar</link>*      <link linkend="g-strdown">g_strdown</link>                       (<link linkend="gchar">gchar</link> *string);

<link linkend="gint">gint</link>        <link linkend="g-strcasecmp">g_strcasecmp</link>                    (const <link linkend="gchar">gchar</link> *s1,
                                             const <link linkend="gchar">gchar</link> *s2);
<link linkend="gint">gint</link>        <link linkend="g-strncasecmp">g_strncasecmp</link>                   (const <link linkend="gchar">gchar</link> *s1,
                                             const <link linkend="gchar">gchar</link> *s2,
                                             <link linkend="guint">guint</link> n);

<link linkend="gchar">gchar</link>*      <link linkend="g-strreverse">g_strreverse</link>                    (<link linkend="gchar">gchar</link> *string);

#define     <link linkend="G-ASCII-DTOSTR-BUF-SIZE-CAPS">G_ASCII_DTOSTR_BUF_SIZE</link>
<link linkend="gdouble">gdouble</link>     <link linkend="g-ascii-strtod">g_ascii_strtod</link>                  (const <link linkend="gchar">gchar</link> *nptr,
                                             <link linkend="gchar">gchar</link> **endptr);
<link linkend="gchar">gchar</link>*      <link linkend="g-ascii-dtostr">g_ascii_dtostr</link>                  (<link linkend="gchar">gchar</link> *buffer,
                                             <link linkend="gint">gint</link> buf_len,
                                             <link linkend="gdouble">gdouble</link> d);
<link linkend="gchar">gchar</link>*      <link linkend="g-ascii-formatd">g_ascii_formatd</link>                 (<link linkend="gchar">gchar</link> *buffer,
                                             <link linkend="gint">gint</link> buf_len,
                                             const <link linkend="gchar">gchar</link> *format,
                                             <link linkend="gdouble">gdouble</link> d);
<link linkend="gdouble">gdouble</link>     <link linkend="g-strtod">g_strtod</link>                        (const <link linkend="gchar">gchar</link> *nptr,
                                             <link linkend="gchar">gchar</link> **endptr);

<link linkend="gchar">gchar</link>*      <link linkend="g-strchug">g_strchug</link>                       (<link linkend="gchar">gchar</link> *string);
<link linkend="gchar">gchar</link>*      <link linkend="g-strchomp">g_strchomp</link>                      (<link linkend="gchar">gchar</link> *string);
#define     <link linkend="g-strstrip">g_strstrip</link>                      ( string )

<link linkend="gchar">gchar</link>*      <link linkend="g-strdelimit">g_strdelimit</link>                    (<link linkend="gchar">gchar</link> *string,
                                             const <link linkend="gchar">gchar</link> *delimiters,
                                             <link linkend="gchar">gchar</link> new_delimiter);
#define     <link linkend="G-STR-DELIMITERS-CAPS">G_STR_DELIMITERS</link>
<link linkend="gchar">gchar</link>*      <link linkend="g-strescape">g_strescape</link>                     (const <link linkend="gchar">gchar</link> *source,
                                             const <link linkend="gchar">gchar</link> *exceptions);
<link linkend="gchar">gchar</link>*      <link linkend="g-strcompress">g_strcompress</link>                   (const <link linkend="gchar">gchar</link> *source);
<link linkend="gchar">gchar</link>*      <link linkend="g-strcanon">g_strcanon</link>                      (<link linkend="gchar">gchar</link> *string,
                                             const <link linkend="gchar">gchar</link> *valid_chars,
                                             <link linkend="gchar">gchar</link> substitutor);
<link linkend="gchar">gchar</link>**     <link linkend="g-strsplit">g_strsplit</link>                      (const <link linkend="gchar">gchar</link> *string,
                                             const <link linkend="gchar">gchar</link> *delimiter,
                                             <link linkend="gint">gint</link> max_tokens);
void        <link linkend="g-strfreev">g_strfreev</link>                      (<link linkend="gchar">gchar</link> **str_array);
<link linkend="gchar">gchar</link>*      <link linkend="g-strconcat">g_strconcat</link>                     (const <link linkend="gchar">gchar</link> *string1,
                                             ...);
<link linkend="gchar">gchar</link>*      <link linkend="g-strjoin">g_strjoin</link>                       (const <link linkend="gchar">gchar</link> *separator,
                                             ...);
<link linkend="gchar">gchar</link>*      <link linkend="g-strjoinv">g_strjoinv</link>                      (const <link linkend="gchar">gchar</link> *separator,
                                             <link linkend="gchar">gchar</link> **str_array);

G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-strerror">g_strerror</link>            (<link linkend="gint">gint</link> errnum);
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-strsignal">g_strsignal</link>           (<link linkend="gint">gint</link> signum);

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
This section describes a number of utility functions for creating,
duplicating, and manipulating strings.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="g-strdup">g_strdup ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strdup                        (const <link linkend="gchar">gchar</link> *str);</programlisting>
<para>
Duplicates a string.
The returned string should be freed when no longer needed.
</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>the string to duplicate.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated copy of <parameter>str</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strndup">g_strndup ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strndup                       (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gsize">gsize</link> n);</programlisting>
<para>
Duplicates the first <parameter>n</parameter> characters of a string, returning a newly-allocated
buffer <parameter>n</parameter> + 1 characters long which will always be nul-terminated.
If <parameter>str</parameter> is less than <parameter>n</parameter> characters long the buffer is padded with nuls.
The returned value should be freed when no longer needed.
</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>the string to duplicate part of.
</entry></row>
<row><entry align="right"><parameter>n</parameter>&nbsp;:</entry>
<entry>the maximum number of characters to copy from <parameter>str</parameter>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated buffer containing the first <parameter>n</parameter> characters of <parameter>str</parameter>,
nul-terminated.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strdupv">g_strdupv ()</title>
<programlisting><link linkend="gchar">gchar</link>**     g_strdupv                       (<link linkend="gchar">gchar</link> **str_array);</programlisting>
<para>
Copies <literal>NULL</literal>-terminated array of strings. The copy is a deep copy;
the new array should be freed by first freeing each string, then
the array itself. <link linkend="g-strfreev">g_strfreev</link>() does this for you. If called
on a <literal>NULL</literal> value, <link linkend="g-strdupv">g_strdupv</link>() simply returns <literal>NULL</literal>.</para>
<para>
Copies a <literal>NULL</literal>-terminated array of strings. The result consists of a
<literal>NULL</literal>-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
<link linkend="g-strfreev">g_strfreev</link>() which frees each string in a vector, then the vector itself.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str_array</parameter>&nbsp;:</entry>
<entry> <literal>NULL</literal>-terminated array of strings.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new <literal>NULL</literal>-terminated array of strings.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strnfill">g_strnfill ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strnfill                      (<link linkend="gsize">gsize</link> length,
                                             <link linkend="gchar">gchar</link> fill_char);</programlisting>
<para>
Creates a new string <parameter>length</parameter> characters long filled with <parameter>fill_char</parameter>.
The returned string should be freed when no longer needed.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>length</parameter>&nbsp;:</entry>
<entry>the length of the new string.
</entry></row>
<row><entry align="right"><parameter>fill_char</parameter>&nbsp;:</entry>
<entry>the character to fill the string with.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated string filled the <parameter>fill_char</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>