string_utils.sgml

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

<refsect2>
<title><anchor id="g-stpcpy">g_stpcpy ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_stpcpy                        (<link linkend="gchar">gchar</link> *dest,
                                             const char *src);</programlisting>
<para>
Copies a nul-terminated string into the dest buffer, include the
trailing nul, and return a pointer to the trailing nul byte.
This is useful for concatenating multiple strings together
without having to repeatedly scan for the end.</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>dest</parameter>&nbsp;:</entry>
<entry> destination buffer.
</entry></row>
<row><entry align="right"><parameter>src</parameter>&nbsp;:</entry>
<entry> source string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to trailing nul byte.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strstr-len">g_strstr_len ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strstr_len                    (const <link linkend="gchar">gchar</link> *haystack,
                                             <link linkend="gssize">gssize</link> haystack_len,
                                             const <link linkend="gchar">gchar</link> *needle);</programlisting>
<para>
Searches the string <parameter>haystack</parameter> for the first occurrence
of the string <parameter>needle</parameter>, limiting the length of the search
to <parameter>haystack_len</parameter>.</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>haystack</parameter>&nbsp;:</entry>
<entry> a string.
</entry></row>
<row><entry align="right"><parameter>haystack_len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>haystack</parameter>.
</entry></row>
<row><entry align="right"><parameter>needle</parameter>&nbsp;:</entry>
<entry> the string to search for.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to the found occurrence, or
   <literal>NULL</literal> if not found.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strrstr">g_strrstr ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strrstr                       (const <link linkend="gchar">gchar</link> *haystack,
                                             const <link linkend="gchar">gchar</link> *needle);</programlisting>
<para>
Searches the string <parameter>haystack</parameter> for the last occurrence
of the string <parameter>needle</parameter>.</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>haystack</parameter>&nbsp;:</entry>
<entry> a nul-terminated string.
</entry></row>
<row><entry align="right"><parameter>needle</parameter>&nbsp;:</entry>
<entry> the nul-terminated string to search for.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to the found occurrence, or
   <literal>NULL</literal> if not found.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strrstr-len">g_strrstr_len ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strrstr_len                   (const <link linkend="gchar">gchar</link> *haystack,
                                             <link linkend="gssize">gssize</link> haystack_len,
                                             const <link linkend="gchar">gchar</link> *needle);</programlisting>
<para>
Searches the string <parameter>haystack</parameter> for the last occurrence
of the string <parameter>needle</parameter>, limiting the length of the search
to <parameter>haystack_len</parameter>.</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>haystack</parameter>&nbsp;:</entry>
<entry> a nul-terminated string.
</entry></row>
<row><entry align="right"><parameter>haystack_len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>haystack</parameter>.
</entry></row>
<row><entry align="right"><parameter>needle</parameter>&nbsp;:</entry>
<entry> the nul-terminated string to search for.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to the found occurrence, or
   <literal>NULL</literal> if not found.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strlcpy">g_strlcpy ()</title>
<programlisting><link linkend="gsize">gsize</link>       g_strlcpy                       (<link linkend="gchar">gchar</link> *dest,
                                             const <link linkend="gchar">gchar</link> *src,
                                             <link linkend="gsize">gsize</link> dest_size);</programlisting>
<para>
Portability wrapper that calls <link linkend="strlcpy">strlcpy</link>() on systems which have it, and emulates
<link linkend="strlcpy">strlcpy</link>() otherwise. Copies <parameter>src</parameter> to <parameter>dest</parameter>; <parameter>dest</parameter> is guaranteed to be
nul-terminated; <parameter>src</parameter> must be nul-terminated; <parameter>dest_size</parameter> is the buffer size, not
the number of chars to copy. Caveat: <link linkend="strlcpy">strlcpy</link>() is supposedly more secure than
<link linkend="strcpy">strcpy</link>() or <link linkend="strncpy">strncpy</link>(), but if you really want to avoid screwups, <link linkend="g-strdup">g_strdup</link>() is
an even better idea.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dest</parameter>&nbsp;:</entry>
<entry>destination buffer
</entry></row>
<row><entry align="right"><parameter>src</parameter>&nbsp;:</entry>
<entry>source buffer
</entry></row>
<row><entry align="right"><parameter>dest_size</parameter>&nbsp;:</entry>
<entry>length of <parameter>dest</parameter> in bytes
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>length of <parameter>src</parameter>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strlcat">g_strlcat ()</title>
<programlisting><link linkend="gsize">gsize</link>       g_strlcat                       (<link linkend="gchar">gchar</link> *dest,
                                             const <link linkend="gchar">gchar</link> *src,
                                             <link linkend="gsize">gsize</link> dest_size);</programlisting>
<para>
Portability wrapper that calls <function><link linkend="strlcat">strlcat</link>()</function> on systems which have it, and emulates it otherwise. Appends nul-terminated <parameter>src</parameter> string to <parameter>dest</parameter>, guaranteeing
nul-termination for <parameter>dest</parameter>. The total size of <parameter>dest</parameter> won't exceed
<parameter>dest_size</parameter>. Caveat: this is supposedly a more secure alternative to <function><link linkend="strcat">strcat</link>()</function> or
<function><link linkend="strncat">strncat</link>()</function>, but for real security <link linkend="g-strconcat">g_strconcat</link>() is harder to mess up.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dest</parameter>&nbsp;:</entry>
<entry>destination buffer, already containing one nul-terminated string
</entry></row>
<row><entry align="right"><parameter>src</parameter>&nbsp;:</entry>
<entry>source buffer
</entry></row>
<row><entry align="right"><parameter>dest_size</parameter>&nbsp;:</entry>
<entry>length of <parameter>dest</parameter> buffer in bytes (not length of existing string inside <parameter>dest</parameter>)
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>length of <parameter>src</parameter> plus initial length of string in <parameter>dest</parameter>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strdup-printf">g_strdup_printf ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strdup_printf                 (const <link linkend="gchar">gchar</link> *format,
                                             ...);</programlisting>
<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><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 standard <function>sprintf()</function> format string.
</entry></row>
<row><entry align="right"><parameter>...</parameter>&nbsp;:</entry>
<entry>the parameters to insert into the format string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated string holding the result.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strdup-vprintf">g_strdup_vprintf ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strdup_vprintf                (const <link linkend="gchar">gchar</link> *format,
                                             va_list args);</programlisting>
<para>
Similar to the standard C <function><link linkend="vsprintf">vsprintf</link>()</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><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 standard <function>sprintf()</function> format string.
</entry></row>
<row><entry align="right"><parameter>args</parameter>&nbsp;:</entry>
<entry>the list of parameters to insert into the format string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated string holding the result.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-snprintf">g_snprintf ()</title>
<programlisting><link linkend="gint">gint</link>        g_snprintf                      (<link linkend="gchar">gchar</link> *string,
                                             <link linkend="gulong">gulong</link> n,
                                             <link linkend="gchar">gchar</link> const *format,
                                             ...);</programlisting>
<para>
A safer form of the standard <function>sprintf()</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-printf">g_strdup_printf</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-snprintf">g_snprintf</link>() conforms to the <function><link linkend="snprintf">snprintf</link>()</function>
function as standardized in ISO C99. Note that this is different from 
traditional <function><link linkend="snprintf">snprintf</link>()</function>, which returns the length of 
the output string.
</para>
</note><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">