strings.sgml

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

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

<refnamediv>
<refname>Strings</refname><refpurpose>text buffers which grow automatically as text is added.</refpurpose>
</refnamediv>

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

#include &lt;glib.h&gt;


struct      <link linkend="GString">GString</link>;
<link linkend="GString">GString</link>*    <link linkend="g-string-new">g_string_new</link>                    (const <link linkend="gchar">gchar</link> *init);
<link linkend="GString">GString</link>*    <link linkend="g-string-new-len">g_string_new_len</link>                (const <link linkend="gchar">gchar</link> *init,
                                             <link linkend="gssize">gssize</link> len);
<link linkend="GString">GString</link>*    <link linkend="g-string-sized-new">g_string_sized_new</link>              (<link linkend="gsize">gsize</link> dfl_size);
<link linkend="GString">GString</link>*    <link linkend="g-string-assign">g_string_assign</link>                 (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *rval);
#define     <link linkend="g-string-sprintf">g_string_sprintf</link>
#define     <link linkend="g-string-sprintfa">g_string_sprintfa</link>
void        <link linkend="g-string-printf">g_string_printf</link>                 (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);
void        <link linkend="g-string-append-printf">g_string_append_printf</link>          (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);
<link linkend="GString">GString</link>*    <link linkend="g-string-append">g_string_append</link>                 (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *val);
<link linkend="GString">GString</link>*    <link linkend="g-string-append-c">g_string_append_c</link>               (<link linkend="GString">GString</link> *string,
                                             <link linkend="gchar">gchar</link> c);
<link linkend="GString">GString</link>*    <link linkend="g-string-append-unichar">g_string_append_unichar</link>         (<link linkend="GString">GString</link> *string,
                                             <link linkend="gunichar">gunichar</link> wc);
<link linkend="GString">GString</link>*    <link linkend="g-string-append-len">g_string_append_len</link>             (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *val,
                                             <link linkend="gssize">gssize</link> len);
<link linkend="GString">GString</link>*    <link linkend="g-string-prepend">g_string_prepend</link>                (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *val);
<link linkend="GString">GString</link>*    <link linkend="g-string-prepend-c">g_string_prepend_c</link>              (<link linkend="GString">GString</link> *string,
                                             <link linkend="gchar">gchar</link> c);
<link linkend="GString">GString</link>*    <link linkend="g-string-prepend-unichar">g_string_prepend_unichar</link>        (<link linkend="GString">GString</link> *string,
                                             <link linkend="gunichar">gunichar</link> wc);
<link linkend="GString">GString</link>*    <link linkend="g-string-prepend-len">g_string_prepend_len</link>            (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *val,
                                             <link linkend="gssize">gssize</link> len);
<link linkend="GString">GString</link>*    <link linkend="g-string-insert">g_string_insert</link>                 (<link linkend="GString">GString</link> *string,
                                             <link linkend="gssize">gssize</link> pos,
                                             const <link linkend="gchar">gchar</link> *val);
<link linkend="GString">GString</link>*    <link linkend="g-string-insert-c">g_string_insert_c</link>               (<link linkend="GString">GString</link> *string,
                                             <link linkend="gssize">gssize</link> pos,
                                             <link linkend="gchar">gchar</link> c);
<link linkend="GString">GString</link>*    <link linkend="g-string-insert-unichar">g_string_insert_unichar</link>         (<link linkend="GString">GString</link> *string,
                                             <link linkend="gssize">gssize</link> pos,
                                             <link linkend="gunichar">gunichar</link> wc);
<link linkend="GString">GString</link>*    <link linkend="g-string-insert-len">g_string_insert_len</link>             (<link linkend="GString">GString</link> *string,
                                             <link linkend="gssize">gssize</link> pos,
                                             const <link linkend="gchar">gchar</link> *val,
                                             <link linkend="gssize">gssize</link> len);
<link linkend="GString">GString</link>*    <link linkend="g-string-erase">g_string_erase</link>                  (<link linkend="GString">GString</link> *string,
                                             <link linkend="gssize">gssize</link> pos,
                                             <link linkend="gssize">gssize</link> len);
<link linkend="GString">GString</link>*    <link linkend="g-string-truncate">g_string_truncate</link>               (<link linkend="GString">GString</link> *string,
                                             <link linkend="gsize">gsize</link> len);
<link linkend="GString">GString</link>*    <link linkend="g-string-set-size">g_string_set_size</link>               (<link linkend="GString">GString</link> *string,
                                             <link linkend="gsize">gsize</link> len);
<link linkend="gchar">gchar</link>*      <link linkend="g-string-free">g_string_free</link>                   (<link linkend="GString">GString</link> *string,
                                             <link linkend="gboolean">gboolean</link> free_segment);

<link linkend="GString">GString</link>*    <link linkend="g-string-up">g_string_up</link>                     (<link linkend="GString">GString</link> *string);
<link linkend="GString">GString</link>*    <link linkend="g-string-down">g_string_down</link>                   (<link linkend="GString">GString</link> *string);

<link linkend="guint">guint</link>       <link linkend="g-string-hash">g_string_hash</link>                   (const <link linkend="GString">GString</link> *str);
<link linkend="gboolean">gboolean</link>    <link linkend="g-string-equal">g_string_equal</link>                  (const <link linkend="GString">GString</link> *v,
                                             const <link linkend="GString">GString</link> *v2);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
A <link linkend="GString">GString</link> is similar to a standard C string, except that it grows automatically
as text is appended or inserted. Also, it stores the length of the string, so
can be used for binary data with embedded nul bytes.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GString">struct GString</title>
<programlisting>struct GString
{
  gchar  *str;
  gsize len;    
  gsize allocated_len;
};
</programlisting>
<para>
The <link linkend="GString">GString</link> struct contains the public fields of a <link linkend="GString">GString</link>.
The <structfield>str</structfield> field points to the character data.
It may move as text is added.
The <structfield>len</structfield> field contains the length of the string,
not including the terminating nul character.
</para>
<para>
The <structfield>str</structfield> field is nul-terminated and so can be used as an ordinary C
string. But it may be moved when text is appended or inserted into the
string.
</para></refsect2>
<refsect2>
<title><anchor id="g-string-new">g_string_new ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_new                    (const <link linkend="gchar">gchar</link> *init);</programlisting>
<para>
Creates a new <link linkend="GString">GString</link>, initialized with the given string.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>init</parameter>&nbsp;:</entry>
<entry>the initial text to copy into the string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-new-len">g_string_new_len ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_new_len                (const <link linkend="gchar">gchar</link> *init,
                                             <link linkend="gssize">gssize</link> len);</programlisting>
<para>
Creates a new <link linkend="GString">GString</link> with <parameter>len</parameter> bytes of the <parameter>init</parameter> buffer.  Because a length is
provided, <parameter>init</parameter> need not be nul-terminated, and can contain embedded nul bytes.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>init</parameter>&nbsp;:</entry>
<entry>initial contents of string.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>length of <parameter>init</parameter> to use.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a new <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-sized-new">g_string_sized_new ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_sized_new              (<link linkend="gsize">gsize</link> dfl_size);</programlisting>
<para>
Creates a new <link linkend="GString">GString</link>, with enough space for <parameter>dfl_size</parameter> characters.
This is useful if you are going to add a lot of text to the string and
don't want it to be reallocated too often.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dfl_size</parameter>&nbsp;:</entry>
<entry>the default size of the space allocated to hold the string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-assign">g_string_assign ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_assign                 (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *rval);</programlisting>
<para>
Copies the characters from one <link linkend="GString">GString</link> into another, destroying any previous
contents. It is rather like the standard <function><link linkend="strcpy">strcpy</link>()</function> function, except that
you do not have to worry about having enough space to copy the string.
</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 destination <link linkend="GString">GString</link>. Its current contents are destroyed.
</entry></row>
<row><entry align="right"><parameter>rval</parameter>&nbsp;:</entry>
<entry>the source <link linkend="GString">GString</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the destination <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-sprintf">g_string_sprintf</title>
<programlisting>#define     g_string_sprintf</programlisting>
<warning>
<para>
<literal>g_string_sprintf</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Writes a formatted string into a <link linkend="GString">GString</link>.
This is similar to the standard <function>sprintf()</function> function,
except that the <link linkend="GString">GString</link> buffer automatically expands to contain the results.
The previous contents of the <link linkend="GString">GString</link> are destroyed. This
function has been renamaed to <link linkend="g-string-printf">g_string_printf</link>().
</para></refsect2>
<refsect2>
<title><anchor id="g-string-sprintfa">g_string_sprintfa</title>
<programlisting>#define     g_string_sprintfa</programlisting>
<warning>
<para>
<literal>g_string_sprintfa</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Appends a formatted string onto the end of a <link linkend="GString">GString</link>.
This function is is similar to <link linkend="g-string-sprintf">g_string_sprintf</link>() except that
the text is appended to the <link linkend="GString">GString</link>. The function has been
renamed to <link linkend="g-string-append-printf">g_string_append_printf</link>().
</para></refsect2>
<refsect2>
<title><anchor id="g-string-printf">g_string_printf ()</title>
<programlisting>void        g_string_printf                 (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);</programlisting>
<para>
Writes a formatted string into a <link linkend="GString">GString</link>.
This is similar to the standard <function>sprintf()</function> function,
except that the <link linkend="GString">GString</link> buffer automatically expands to contain the results.
The previous contents of the <link linkend="GString">GString</link> are destroyed.
</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 <link linkend="GString">GString</link>.
</entry></row>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry>the string format. See the <function>printf()</function>
documentation.
</entry></row>
<row><entry align="right"><parameter>...</parameter>&nbsp;:</entry>
<entry>the parameters to insert into the format string.


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