<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 a string into a <link linkend="GString">GString</link>, 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 string to copy into <parameter>string</parameter>.
</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>
<refsect2>
<title><anchor id="g-string-append-printf">g_string_append_printf ()</title>
<programlisting>void        g_string_append_printf          (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);</programlisting>
<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-printf">g_string_printf</link>() except that
the text is appended to the <link linkend="GString">GString</link>.
</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>
<refsect2>
<title><anchor id="g-string-append">g_string_append ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_append                 (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *val);</programlisting>
<para>
Adds a string onto the end of a <link linkend="GString">GString</link>, expanding it if necessary.
</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>val</parameter>&nbsp;:</entry>
<entry>the string to append onto the end of the <link linkend="GString">GString</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-append-c">g_string_append_c ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_append_c               (<link linkend="GString">GString</link> *string,
                                             <link linkend="gchar">gchar</link> c);</programlisting>
<para>
Adds a character onto the end of a <link linkend="GString">GString</link>, expanding it if necessary.
</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>c</parameter>&nbsp;:</entry>
<entry>the character to append onto the end of the <link linkend="GString">GString</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-append-unichar">g_string_append_unichar ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_append_unichar         (<link linkend="GString">GString</link> *string,
                                             <link linkend="gunichar">gunichar</link> wc);</programlisting>
<para>
Converts a Unicode character into UTF-8, and appends it
to the string.</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 <link linkend="GString">GString</link>
</entry></row>
<row><entry align="right"><parameter>wc</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <parameter>string</parameter>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-append-len">g_string_append_len ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_append_len             (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *val,
                                             <link linkend="gssize">gssize</link> len);</programlisting>
<para>
Appends <parameter>len</parameter> bytes of <parameter>val</parameter> to <parameter>string</parameter>. Because <parameter>len</parameter> is provided, 
<parameter>val</parameter> may contain embedded nuls and need not be nul-terminated.
</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>val</parameter>&nbsp;:</entry>
<entry>bytes to append.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>number of bytes of <parameter>val</parameter> to use.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-prepend">g_string_prepend ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_prepend                (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *val);</programlisting>
<para>
Adds a string on to the start of a <link linkend="GString">GString</link>, expanding it if necessary.
</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>val</parameter>&nbsp;:</entry>
<entry>the string to prepend on the start of the <link linkend="GString">GString</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-prepend-c">g_string_prepend_c ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_prepend_c              (<link linkend="GString">GString</link> *string,
                                             <link linkend="gchar">gchar</link> c);</programlisting>
<para>
Adds a character onto the start of a <link linkend="GString">GString</link>, expanding it if necessary.
</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>c</parameter>&nbsp;:</entry>
<entry>the character to prepend on the start of the <link linkend="GString">GString</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-prepend-unichar">g_string_prepend_unichar ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_prepend_unichar        (<link linkend="GString">GString</link> *string,
                                             <link linkend="gunichar">gunichar</link> wc);</programlisting>
<para>
Converts a Unicode character into UTF-8, and prepends it
to the string.</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 <link linkend="GString">GString</link>.
</entry></row>
<row><entry align="right"><parameter>wc</parameter>&nbsp;:</entry>
<entry> a Unicode character.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <parameter>string</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-prepend-len">g_string_prepend_len ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_prepend_len            (<link linkend="GString">GString</link> *string,
                                             const <link linkend="gchar">gchar</link> *val,
                                             <link linkend="gssize">gssize</link> len);</programlisting>
<para>
Prepends <parameter>len</parameter> bytes of <parameter>val</parameter> to <parameter>string</parameter>. Because <parameter>len</parameter> is provided, 
<parameter>val</parameter> may contain embedded nuls and need not be nul-terminated.
</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>val</parameter>&nbsp;:</entry>
<entry>bytes to prepend.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>number of bytes in <parameter>val</parameter> to prepend.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GString">GString</link> passed in.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-insert">g_string_insert ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_insert                 (<link linkend="GString">GString</link> *string,
                                             <link linkend="gssize">gssize</link> pos,
                                             const <link linkend="gchar">gchar</link> *val);</programlisting>
<para>
Inserts a copy of a string into a <link linkend="GString">GString</link>, expanding it if necessary.
</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>pos</parameter>&nbsp;:</entry>
<entry>the position to insert the copy of the string.
</entry></row>
<row><entry align="right"><parameter>val</parameter>&nbsp;:</entry>
<entry>the string to insert.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-insert-c">g_string_insert_c ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_insert_c               (<link linkend="GString">GString</link> *string,
                                             <link linkend="gssize">gssize</link> pos,
                                             <link linkend="gchar">gchar</link> c);</programlisting>
<para>
Inserts a character into a <link linkend="GString">GString</link>, expanding it if necessary.
</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>pos</parameter>&nbsp;:</entry>
<entry>the position to insert the character.
</entry></row>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>the character to insert.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-insert-unichar">g_string_insert_unichar ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_insert_unichar         (<link linkend="GString">GString</link> *string,
                                             <link linkend="gssize">gssize</link> pos,
                                             <link linkend="gunichar">gunichar</link> wc);</programlisting>
<para>
Converts a Unicode character into UTF-8, and insert it
into the string at the given position.</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 <link linkend="Gstring">Gstring</link>
</entry></row>
<row><entry align="right"><parameter>pos</parameter>&nbsp;:</entry>
<entry> the position at which to insert character, or -1 to
      append at the end of the string.
</entry></row>
<row><entry align="right"><parameter>wc</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <parameter>string</parameter>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-insert-len">g_string_insert_len ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_insert_len             (<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);</programlisting>
<para>
Inserts <parameter>len</parameter> bytes of <parameter>val</parameter> into <parameter>string</parameter> at <parameter>pos</parameter>.  Because <parameter>len</parameter> is provided, <parameter>val</parameter>
 may contain embedded nuls and need not be nul-terminated. If <parameter>pos</parameter> is -1, bytes are inserted at the end of 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>a <link linkend="GString">GString</link>.
</entry></row>
<row><entry align="right"><parameter>pos</parameter>&nbsp;:</entry>
<entry>position in <parameter>string</parameter> where insertion should happen, or -1 for at the end.
</entry></row>
<row><entry align="right"><parameter>val</parameter>&nbsp;:</entry>
<entry>bytes to insert.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>number of bytes of <parameter>val</parameter> to insert.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-erase">g_string_erase ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_erase                  (<link linkend="GString">GString</link> *string,
                                             <link linkend="gssize">gssize</link> pos,
                                             <link linkend="gssize">gssize</link> len);</programlisting>
<para>
Removes <parameter>len</parameter> characters from a <link linkend="GString">GString</link>, starting at position <parameter>pos</parameter>.
The rest of the <link linkend="GString">GString</link> is shifted down to fill the gap.
</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>pos</parameter>&nbsp;:</entry>
<entry>the position of the characters to remove.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>the number of characters to remove, or -1 to remove all
      following characters.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-truncate">g_string_truncate ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_truncate               (<link linkend="GString">GString</link> *string,
                                             <link linkend="gsize">gsize</link> len);</programlisting>
<para>
Cuts off the end of the GString, leaving the first <parameter>len</parameter> characters.
</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>len</parameter>&nbsp;:</entry>
<entry>the new size of the <link linkend="GString">GString</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-set-size">g_string_set_size ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_set_size               (<link linkend="GString">GString</link> *string,
                                             <link linkend="gsize">gsize</link> len);</programlisting>
<para>
Sets the length of a <link linkend="GString">GString</link>. If the length is less than
the current length, the string will be truncated. If the
length is greater than the current length, the contents
of the newly added area are undefined. (However, as
always, string->str[string->len] will be a nul byte.)</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 <link linkend="GString">GString</link>
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> the new length
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <parameter>string</parameter>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-free">g_string_free ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_string_free                   (<link linkend="GString">GString</link> *string,
                                             <link linkend="gboolean">gboolean</link> free_segment);</programlisting>
<para>
Frees the memory allocated for the <link linkend="GString">GString</link>.
If <parameter>free_segment</parameter> is <literal>TRUE</literal> it also frees the character data.
</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>free_segment</parameter>&nbsp;:</entry>
<entry>if <literal>TRUE</literal> the actual character data is freed as well.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-up">g_string_up ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_up                     (<link linkend="GString">GString</link> *string);</programlisting>
<warning>
<para>
<literal>g_string_up</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Converts a <link linkend="GString">GString</link> to upper case.
</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"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-down">g_string_down ()</title>
<programlisting><link linkend="GString">GString</link>*    g_string_down                   (<link linkend="GString">GString</link> *string);</programlisting>
<warning>
<para>
<literal>g_string_down</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Converts a <link linkend="GString">GString</link> to lower case.
</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"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GString">GString</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-hash">g_string_hash ()</title>
<programlisting><link linkend="guint">guint</link>       g_string_hash                   (const <link linkend="GString">GString</link> *str);</programlisting>
<para>
Creates a hash code for <parameter>str</parameter>; for use with <link linkend="GHashTable">GHashTable</link>.
</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 to hash.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>hash code for <parameter>str</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-equal">g_string_equal ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_string_equal                  (const <link linkend="GString">GString</link> *v,
                                             const <link linkend="GString">GString</link> *v2);</programlisting>
<para>
Compares two strings for equality, returning <literal>TRUE</literal> if they are equal. 
For use with <link linkend="GHashTable">GHashTable</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>v</parameter>&nbsp;:</entry>
<entry>a <link linkend="GString">GString</link>.
</entry></row>
<row><entry align="right"><parameter>v2</parameter>&nbsp;:</entry>
<entry>another <link linkend="GString">GString</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if they strings are the same length and contain the same bytes.


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

</refsect1>




</refentry>
