<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="glib-Strings">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Strings.top_of_page">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>

<refsect1 id="glib-Strings.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-new">g_string_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-new-len">g_string_new_len</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-sized-new">g_string_sized_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-assign">g_string_assign</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-string-vprintf">g_string_vprintf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-string-append-vprintf">g_string_append_vprintf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-string-printf">g_string_printf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-string-append-printf">g_string_append_printf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-append">g_string_append</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-append-c">g_string_append_c</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-append-unichar">g_string_append_unichar</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-append-len">g_string_append_len</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-append-uri-escaped">g_string_append_uri_escaped</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-prepend">g_string_prepend</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-prepend-c">g_string_prepend_c</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-prepend-unichar">g_string_prepend_unichar</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-prepend-len">g_string_prepend_len</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-insert">g_string_insert</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-insert-c">g_string_insert_c</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-insert-unichar">g_string_insert_unichar</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-insert-len">g_string_insert_len</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-overwrite">g_string_overwrite</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-overwrite-len">g_string_overwrite_len</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-erase">g_string_erase</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-truncate">g_string_truncate</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-set-size">g_string_set_size</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-free">g_string_free</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GBytes"><returnvalue>GBytes</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-free-to-bytes">g_string_free_to_bytes</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-up">g_string_up</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-string-down">g_string_down</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-string-hash">g_string_hash</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-string-equal">g_string_equal</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="glib-Strings.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GString">GString</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-string-sprintf">g_string_sprintf</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-string-sprintfa">g_string_sprintfa</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="glib-Strings.includes"><title>Includes</title><synopsis>#include &lt;gmodule.h&gt;
</synopsis></refsect1>

<refsect1 id="glib-Strings.description" role="desc">
<title role="desc.title">Description</title>
<para>A <link linkend="GString"><type>GString</type></link> is an object that handles the memory management of a C
string for you.  The emphasis of <link linkend="GString"><type>GString</type></link> is on text, typically
UTF-8.  Crucially, the "str" member of a <link linkend="GString"><type>GString</type></link> is guaranteed to
have a trailing nul character, and it is therefore always safe to
call functions such as <link linkend="strchr"><function>strchr()</function></link> or <link linkend="g-strdup"><function>g_strdup()</function></link> on it.</para>
<para>However, a <link linkend="GString"><type>GString</type></link> can also hold arbitrary binary data, because it
has a "len" member, which includes any possible embedded nul
characters in the data.  Conceptually then, <link linkend="GString"><type>GString</type></link> is like a
<link linkend="GByteArray"><type>GByteArray</type></link> with the addition of many convenience methods for text,
and a guaranteed nul terminator.</para>

</refsect1>
<refsect1 id="glib-Strings.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="g-string-new" role="function">
<title>g_string_new&#160;()</title>
<indexterm zone="g-string-new"><primary sortas="string_new">g_string_new</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_new (<parameter>const <link linkend="gchar"><type>gchar</type></link> *init</parameter>);</programlisting>
<para>Creates a new <link linkend="GString"><type>GString</type></link>, initialized with the given string.</para>
<refsect3 id="g-string-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>init</para></entry>
<entry role="parameter_description"><para>the initial text to copy into the string, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to
start with an empty string. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-new.returns" role="returns">
<title>Returns</title>
<para> the new <link linkend="GString"><type>GString</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-string-new-len" role="function">
<title>g_string_new_len&#160;()</title>
<indexterm zone="g-string-new-len"><primary sortas="string_new_len">g_string_new_len</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_new_len (<parameter>const <link linkend="gchar"><type>gchar</type></link> *init</parameter>,
                  <parameter><link linkend="gssize"><type>gssize</type></link> len</parameter>);</programlisting>
<para>Creates a new <link linkend="GString"><type>GString</type></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>
<para>Since this function does not stop at nul bytes, it is the caller's
responsibility to ensure that <parameter>init</parameter>
 has at least <parameter>len</parameter>
 addressable
bytes.</para>
<refsect3 id="g-string-new-len.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>init</para></entry>
<entry role="parameter_description"><para>initial contents of the string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>length of <parameter>init</parameter>
to use</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-new-len.returns" role="returns">
<title>Returns</title>
<para> a new <link linkend="GString"><type>GString</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-string-sized-new" role="function">
<title>g_string_sized_new&#160;()</title>
<indexterm zone="g-string-sized-new"><primary sortas="string_sized_new">g_string_sized_new</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_sized_new (<parameter><link linkend="gsize"><type>gsize</type></link> dfl_size</parameter>);</programlisting>
<para>Creates a new <link linkend="GString"><type>GString</type></link>, with enough space for <parameter>dfl_size</parameter>

bytes. 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>
<refsect3 id="g-string-sized-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>dfl_size</para></entry>
<entry role="parameter_description"><para>the default size of the space allocated to
hold the string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-sized-new.returns" role="returns">
<title>Returns</title>
<para> the new <link linkend="GString"><type>GString</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-string-assign" role="function">
<title>g_string_assign&#160;()</title>
<indexterm zone="g-string-assign"><primary sortas="string_assign">g_string_assign</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_assign (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                 <parameter>const <link linkend="gchar"><type>gchar</type></link> *rval</parameter>);</programlisting>
<para>Copies the bytes from a string into a <link linkend="GString"><type>GString</type></link>,
destroying any previous contents. It is rather like
the standard <link linkend="strcpy"><function>strcpy()</function></link> function, except that you do not
have to worry about having enough space to copy the string.</para>
<refsect3 id="g-string-assign.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the destination <link linkend="GString"><type>GString</type></link>. Its current contents
are destroyed.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>rval</para></entry>
<entry role="parameter_description"><para>the string to copy into <parameter>string</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-assign.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-vprintf" role="function" condition="since:2.14">
<title>g_string_vprintf&#160;()</title>
<indexterm zone="g-string-vprintf" role="2.14"><primary sortas="string_vprintf">g_string_vprintf</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_string_vprintf (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                  <parameter>const <link linkend="gchar"><type>gchar</type></link> *format</parameter>,
                  <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);</programlisting>
<para>Writes a formatted string into a <link linkend="GString"><type>GString</type></link>.
This function is similar to <link linkend="g-string-printf"><function>g_string_printf()</function></link> except that
the arguments to the format string are passed as a va_list.</para>
<refsect3 id="g-string-vprintf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>the string format. See the <link linkend="printf"><function>printf()</function></link> documentation. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>args</para></entry>
<entry role="parameter_description"><para>the parameters to insert into the format string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.14">2.14</link></para></refsect2>
<refsect2 id="g-string-append-vprintf" role="function" condition="since:2.14">
<title>g_string_append_vprintf&#160;()</title>
<indexterm zone="g-string-append-vprintf" role="2.14"><primary sortas="string_append_vprintf">g_string_append_vprintf</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_string_append_vprintf (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *format</parameter>,
                         <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);</programlisting>
<para>Appends a formatted string onto the end of a <link linkend="GString"><type>GString</type></link>.
This function is similar to <link linkend="g-string-append-printf"><function>g_string_append_printf()</function></link>
except that the arguments to the format string are passed
as a va_list.</para>
<refsect3 id="g-string-append-vprintf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>the string format. See the <link linkend="printf"><function>printf()</function></link> documentation. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>args</para></entry>
<entry role="parameter_description"><para>the list of arguments to insert in the output</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.14">2.14</link></para></refsect2>
<refsect2 id="g-string-printf" role="function">
<title>g_string_printf&#160;()</title>
<indexterm zone="g-string-printf"><primary sortas="string_printf">g_string_printf</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_string_printf (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                 <parameter>const <link linkend="gchar"><type>gchar</type></link> *format</parameter>,
                 <parameter>...</parameter>);</programlisting>
<para>Writes a formatted string into a <link linkend="GString"><type>GString</type></link>.
This is similar to the standard <link linkend="sprintf"><function>sprintf()</function></link> function,
except that the <link linkend="GString"><type>GString</type></link> buffer automatically expands
to contain the results. The previous contents of the
<link linkend="GString"><type>GString</type></link> are destroyed.</para>
<refsect3 id="g-string-printf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>the string format. See the <link linkend="printf"><function>printf()</function></link> documentation</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>the parameters to insert into the format string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-string-append-printf" role="function">
<title>g_string_append_printf&#160;()</title>
<indexterm zone="g-string-append-printf"><primary sortas="string_append_printf">g_string_append_printf</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_string_append_printf (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                        <parameter>const <link linkend="gchar"><type>gchar</type></link> *format</parameter>,
                        <parameter>...</parameter>);</programlisting>
<para>Appends a formatted string onto the end of a <link linkend="GString"><type>GString</type></link>.
This function is similar to <link linkend="g-string-printf"><function>g_string_printf()</function></link> except
that the text is appended to the <link linkend="GString"><type>GString</type></link>.</para>
<refsect3 id="g-string-append-printf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>the string format. See the <link linkend="printf"><function>printf()</function></link> documentation</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>the parameters to insert into the format string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-string-append" role="function">
<title>g_string_append&#160;()</title>
<indexterm zone="g-string-append"><primary sortas="string_append">g_string_append</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_append (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                 <parameter>const <link linkend="gchar"><type>gchar</type></link> *val</parameter>);</programlisting>
<para>Adds a string onto the end of a <link linkend="GString"><type>GString</type></link>, expanding
it if necessary.</para>
<refsect3 id="g-string-append.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the string to append onto the end of <parameter>string</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-append.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-append-c" role="function">
<title>g_string_append_c&#160;()</title>
<indexterm zone="g-string-append-c"><primary sortas="string_append_c">g_string_append_c</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_append_c (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                   <parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Adds a byte onto the end of a <link linkend="GString"><type>GString</type></link>, expanding
it if necessary.</para>
<refsect3 id="g-string-append-c.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>the byte to append onto the end of <parameter>string</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-append-c.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-append-unichar" role="function">
<title>g_string_append_unichar&#160;()</title>
<indexterm zone="g-string-append-unichar"><primary sortas="string_append_unichar">g_string_append_unichar</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_append_unichar (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                         <parameter><link linkend="gunichar"><type>gunichar</type></link> wc</parameter>);</programlisting>
<para>Converts a Unicode character into UTF-8, and appends it
to the string.</para>
<refsect3 id="g-string-append-unichar.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>wc</para></entry>
<entry role="parameter_description"><para>a Unicode character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-append-unichar.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-append-len" role="function">
<title>g_string_append_len&#160;()</title>
<indexterm zone="g-string-append-len"><primary sortas="string_append_len">g_string_append_len</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_append_len (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                     <parameter>const <link linkend="gchar"><type>gchar</type></link> *val</parameter>,
                     <parameter><link linkend="gssize"><type>gssize</type></link> len</parameter>);</programlisting>
<para>Appends <parameter>len</parameter>
 bytes of <parameter>val</parameter>
 to <parameter>string</parameter>
.</para>
<para>If <parameter>len</parameter>
 is positive, <parameter>val</parameter>
 may contain embedded nuls and need
not be nul-terminated. It is the caller's responsibility to
ensure that <parameter>val</parameter>
 has at least <parameter>len</parameter>
 addressable bytes.</para>
<para>If <parameter>len</parameter>
 is negative, <parameter>val</parameter>
 must be nul-terminated and <parameter>len</parameter>

is considered to request the entire string length. This
makes <link linkend="g-string-append-len"><function>g_string_append_len()</function></link> equivalent to <link linkend="g-string-append"><function>g_string_append()</function></link>.</para>
<refsect3 id="g-string-append-len.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>bytes to append</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>number of bytes of <parameter>val</parameter>
to use, or -1 for all of <parameter>val</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-append-len.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-append-uri-escaped" role="function" condition="since:2.16">
<title>g_string_append_uri_escaped&#160;()</title>
<indexterm zone="g-string-append-uri-escaped" role="2.16"><primary sortas="string_append_uri_escaped">g_string_append_uri_escaped</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_append_uri_escaped (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                             <parameter>const <link linkend="gchar"><type>gchar</type></link> *unescaped</parameter>,
                             <parameter>const <link linkend="gchar"><type>gchar</type></link> *reserved_chars_allowed</parameter>,
                             <parameter><link linkend="gboolean"><type>gboolean</type></link> allow_utf8</parameter>);</programlisting>
<para>Appends <parameter>unescaped</parameter>
 to <parameter>string</parameter>
, escaping any characters that
are reserved in URIs using URI-style escape sequences.</para>
<refsect3 id="g-string-append-uri-escaped.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>unescaped</para></entry>
<entry role="parameter_description"><para>a string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>reserved_chars_allowed</para></entry>
<entry role="parameter_description"><para>a string of reserved characters allowed
to be used, or <link linkend="NULL:CAPS"><literal>NULL</literal></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>allow_utf8</para></entry>
<entry role="parameter_description"><para>set <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the escaped string may include UTF8 characters</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-append-uri-escaped.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.16">2.16</link></para></refsect2>
<refsect2 id="g-string-prepend" role="function">
<title>g_string_prepend&#160;()</title>
<indexterm zone="g-string-prepend"><primary sortas="string_prepend">g_string_prepend</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_prepend (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                  <parameter>const <link linkend="gchar"><type>gchar</type></link> *val</parameter>);</programlisting>
<para>Adds a string on to the start of a <link linkend="GString"><type>GString</type></link>,
expanding it if necessary.</para>
<refsect3 id="g-string-prepend.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the string to prepend on the start of <parameter>string</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-prepend.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-prepend-c" role="function">
<title>g_string_prepend_c&#160;()</title>
<indexterm zone="g-string-prepend-c"><primary sortas="string_prepend_c">g_string_prepend_c</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_prepend_c (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                    <parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Adds a byte onto the start of a <link linkend="GString"><type>GString</type></link>,
expanding it if necessary.</para>
<refsect3 id="g-string-prepend-c.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>the byte to prepend on the start of the <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-prepend-c.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-prepend-unichar" role="function">
<title>g_string_prepend_unichar&#160;()</title>
<indexterm zone="g-string-prepend-unichar"><primary sortas="string_prepend_unichar">g_string_prepend_unichar</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_prepend_unichar (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                          <parameter><link linkend="gunichar"><type>gunichar</type></link> wc</parameter>);</programlisting>
<para>Converts a Unicode character into UTF-8, and prepends it
to the string.</para>
<refsect3 id="g-string-prepend-unichar.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>wc</para></entry>
<entry role="parameter_description"><para>a Unicode character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-prepend-unichar.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-prepend-len" role="function">
<title>g_string_prepend_len&#160;()</title>
<indexterm zone="g-string-prepend-len"><primary sortas="string_prepend_len">g_string_prepend_len</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_prepend_len (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                      <parameter>const <link linkend="gchar"><type>gchar</type></link> *val</parameter>,
                      <parameter><link linkend="gssize"><type>gssize</type></link> len</parameter>);</programlisting>
<para>Prepends <parameter>len</parameter>
 bytes of <parameter>val</parameter>
 to <parameter>string</parameter>
.</para>
<para>If <parameter>len</parameter>
 is positive, <parameter>val</parameter>
 may contain embedded nuls and need
not be nul-terminated. It is the caller's responsibility to
ensure that <parameter>val</parameter>
 has at least <parameter>len</parameter>
 addressable bytes.</para>
<para>If <parameter>len</parameter>
 is negative, <parameter>val</parameter>
 must be nul-terminated and <parameter>len</parameter>

is considered to request the entire string length. This
makes <link linkend="g-string-prepend-len"><function>g_string_prepend_len()</function></link> equivalent to <link linkend="g-string-prepend"><function>g_string_prepend()</function></link>.</para>
<refsect3 id="g-string-prepend-len.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>bytes to prepend</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>number of bytes in <parameter>val</parameter>
to prepend, or -1 for all of <parameter>val</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-prepend-len.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-insert" role="function">
<title>g_string_insert&#160;()</title>
<indexterm zone="g-string-insert"><primary sortas="string_insert">g_string_insert</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_insert (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                 <parameter><link linkend="gssize"><type>gssize</type></link> pos</parameter>,
                 <parameter>const <link linkend="gchar"><type>gchar</type></link> *val</parameter>);</programlisting>
<para>Inserts a copy of a string into a <link linkend="GString"><type>GString</type></link>,
expanding it if necessary.</para>
<refsect3 id="g-string-insert.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pos</para></entry>
<entry role="parameter_description"><para>the position to insert the copy of the string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the string to insert</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-insert.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-insert-c" role="function">
<title>g_string_insert_c&#160;()</title>
<indexterm zone="g-string-insert-c"><primary sortas="string_insert_c">g_string_insert_c</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_insert_c (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                   <parameter><link linkend="gssize"><type>gssize</type></link> pos</parameter>,
                   <parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Inserts a byte into a <link linkend="GString"><type>GString</type></link>, expanding it if necessary.</para>
<refsect3 id="g-string-insert-c.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pos</para></entry>
<entry role="parameter_description"><para>the position to insert the byte</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>the byte to insert</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-insert-c.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-insert-unichar" role="function">
<title>g_string_insert_unichar&#160;()</title>
<indexterm zone="g-string-insert-unichar"><primary sortas="string_insert_unichar">g_string_insert_unichar</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_insert_unichar (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                         <parameter><link linkend="gssize"><type>gssize</type></link> pos</parameter>,
                         <parameter><link linkend="gunichar"><type>gunichar</type></link> wc</parameter>);</programlisting>
<para>Converts a Unicode character into UTF-8, and insert it
into the string at the given position.</para>
<refsect3 id="g-string-insert-unichar.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pos</para></entry>
<entry role="parameter_description"><para>the position at which to insert character, or -1
to append at the end of the string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>wc</para></entry>
<entry role="parameter_description"><para>a Unicode character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-insert-unichar.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-insert-len" role="function">
<title>g_string_insert_len&#160;()</title>
<indexterm zone="g-string-insert-len"><primary sortas="string_insert_len">g_string_insert_len</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_insert_len (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                     <parameter><link linkend="gssize"><type>gssize</type></link> pos</parameter>,
                     <parameter>const <link linkend="gchar"><type>gchar</type></link> *val</parameter>,
                     <parameter><link linkend="gssize"><type>gssize</type></link> len</parameter>);</programlisting>
<para>Inserts <parameter>len</parameter>
 bytes of <parameter>val</parameter>
 into <parameter>string</parameter>
 at <parameter>pos</parameter>
.</para>
<para>If <parameter>len</parameter>
 is positive, <parameter>val</parameter>
 may contain embedded nuls and need
not be nul-terminated. It is the caller's responsibility to
ensure that <parameter>val</parameter>
 has at least <parameter>len</parameter>
 addressable bytes.</para>
<para>If <parameter>len</parameter>
 is negative, <parameter>val</parameter>
 must be nul-terminated and <parameter>len</parameter>

is considered to request the entire string length.</para>
<para>If <parameter>pos</parameter>
 is -1, bytes are inserted at the end of the string.</para>
<refsect3 id="g-string-insert-len.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pos</para></entry>
<entry role="parameter_description"><para>position in <parameter>string</parameter>
where insertion should
happen, or -1 for at the end</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>bytes to insert</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>number of bytes of <parameter>val</parameter>
to insert, or -1 for all of <parameter>val</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-insert-len.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-overwrite" role="function" condition="since:2.14">
<title>g_string_overwrite&#160;()</title>
<indexterm zone="g-string-overwrite" role="2.14"><primary sortas="string_overwrite">g_string_overwrite</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_overwrite (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                    <parameter><link linkend="gsize"><type>gsize</type></link> pos</parameter>,
                    <parameter>const <link linkend="gchar"><type>gchar</type></link> *val</parameter>);</programlisting>
<para>Overwrites part of a string, lengthening it if necessary.</para>
<refsect3 id="g-string-overwrite.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pos</para></entry>
<entry role="parameter_description"><para>the position at which to start overwriting</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the string that will overwrite the <parameter>string</parameter>
starting at <parameter>pos</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-overwrite.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.14">2.14</link></para></refsect2>
<refsect2 id="g-string-overwrite-len" role="function" condition="since:2.14">
<title>g_string_overwrite_len&#160;()</title>
<indexterm zone="g-string-overwrite-len" role="2.14"><primary sortas="string_overwrite_len">g_string_overwrite_len</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_overwrite_len (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                        <parameter><link linkend="gsize"><type>gsize</type></link> pos</parameter>,
                        <parameter>const <link linkend="gchar"><type>gchar</type></link> *val</parameter>,
                        <parameter><link linkend="gssize"><type>gssize</type></link> len</parameter>);</programlisting>
<para>Overwrites part of a string, lengthening it if necessary.
This function will work with embedded nuls.</para>
<refsect3 id="g-string-overwrite-len.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pos</para></entry>
<entry role="parameter_description"><para>the position at which to start overwriting</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the string that will overwrite the <parameter>string</parameter>
starting at <parameter>pos</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>the number of bytes to write from <parameter>val</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-overwrite-len.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.14">2.14</link></para></refsect2>
<refsect2 id="g-string-erase" role="function">
<title>g_string_erase&#160;()</title>
<indexterm zone="g-string-erase"><primary sortas="string_erase">g_string_erase</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_erase (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                <parameter><link linkend="gssize"><type>gssize</type></link> pos</parameter>,
                <parameter><link linkend="gssize"><type>gssize</type></link> len</parameter>);</programlisting>
<para>Removes <parameter>len</parameter>
 bytes from a <link linkend="GString"><type>GString</type></link>, starting at position <parameter>pos</parameter>
.
The rest of the <link linkend="GString"><type>GString</type></link> is shifted down to fill the gap.</para>
<refsect3 id="g-string-erase.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pos</para></entry>
<entry role="parameter_description"><para>the position of the content to remove</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>the number of bytes to remove, or -1 to remove all
following bytes</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-erase.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-truncate" role="function">
<title>g_string_truncate&#160;()</title>
<indexterm zone="g-string-truncate"><primary sortas="string_truncate">g_string_truncate</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_truncate (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                   <parameter><link linkend="gsize"><type>gsize</type></link> len</parameter>);</programlisting>
<para>Cuts off the end of the GString, leaving the first <parameter>len</parameter>
 bytes.</para>
<refsect3 id="g-string-truncate.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>the new size of <parameter>string</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-truncate.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-set-size" role="function">
<title>g_string_set_size&#160;()</title>
<indexterm zone="g-string-set-size"><primary sortas="string_set_size">g_string_set_size</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_set_size (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
                   <parameter><link linkend="gsize"><type>gsize</type></link> len</parameter>);</programlisting>
<para>Sets the length of a <link linkend="GString"><type>GString</type></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>
<refsect3 id="g-string-set-size.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>the new length</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-set-size.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-free" role="function">
<title>g_string_free&#160;()</title>
<indexterm zone="g-string-free"><primary sortas="string_free">g_string_free</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_string_free (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>,
               <parameter><link linkend="gboolean"><type>gboolean</type></link> free_segment</parameter>);</programlisting>
<para>Frees the memory allocated for the <link linkend="GString"><type>GString</type></link>.
If <parameter>free_segment</parameter>
 is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> it also frees the character data.  If
it's <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>, the caller gains ownership of the buffer and must
free it after use with <link linkend="g-free"><function>g_free()</function></link>.</para>
<refsect3 id="g-string-free.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>free_segment</para></entry>
<entry role="parameter_description"><para>if <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, the actual character data is freed as well</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-free.returns" role="returns">
<title>Returns</title>
<para>the character data of <parameter>string</parameter>
(i.e. <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>free_segment</parameter>
is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>). </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-free-to-bytes" role="function" condition="since:2.34">
<title>g_string_free_to_bytes&#160;()</title>
<indexterm zone="g-string-free-to-bytes" role="2.34"><primary sortas="string_free_to_bytes">g_string_free_to_bytes</primary></indexterm>
<programlisting language="C"><link linkend="GBytes"><returnvalue>GBytes</returnvalue></link>&#160;*
g_string_free_to_bytes (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>);</programlisting>
<para>Transfers ownership of the contents of <parameter>string</parameter>
 to a newly allocated
<link linkend="GBytes"><type>GBytes</type></link>.  The <link linkend="GString"><type>GString</type></link> structure itself is deallocated, and it is
therefore invalid to use <parameter>string</parameter>
 after invoking this function.</para>
<para>Note that while <link linkend="GString"><type>GString</type></link> ensures that its buffer always has a
trailing nul character (not reflected in its "len"), the returned
<link linkend="GBytes"><type>GBytes</type></link> does not include this extra nul; i.e. it has length exactly
equal to the "len" member.</para>
<refsect3 id="g-string-free-to-bytes.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-free-to-bytes.returns" role="returns">
<title>Returns</title>
<para>A newly allocated <link linkend="GBytes"><type>GBytes</type></link> containing contents of <parameter>string</parameter>
; <parameter>string</parameter>
itself is freed. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.34">2.34</link></para></refsect2>
<refsect2 id="g-string-up" role="function" condition="deprecated">
<title>g_string_up&#160;()</title>
<indexterm zone="g-string-up" role="deprecated"><primary sortas="string_up">g_string_up</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_up (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>);</programlisting>
<warning><para><literal>g_string_up</literal> has been deprecated since version 2.2 and should not be used in newly-written code.</para> <para>This function uses the locale-specific
    <link linkend="toupper"><function>toupper()</function></link> function, which is almost never the right thing.
    Use <link linkend="g-string-ascii-up"><function>g_string_ascii_up()</function></link> or <link linkend="g-utf8-strup"><function>g_utf8_strup()</function></link> instead.</para>
</warning>
<para>Converts a <link linkend="GString"><type>GString</type></link> to uppercase.</para>
<refsect3 id="g-string-up.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-up.returns" role="returns">
<title>Returns</title>
<para><parameter>string</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-down" role="function" condition="deprecated">
<title>g_string_down&#160;()</title>
<indexterm zone="g-string-down" role="deprecated"><primary sortas="string_down">g_string_down</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_down (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>);</programlisting>
<warning><para><literal>g_string_down</literal> has been deprecated since version 2.2 and should not be used in newly-written code.</para> <para>This function uses the locale-specific
    <link linkend="tolower"><function>tolower()</function></link> function, which is almost never the right thing.
    Use <link linkend="g-string-ascii-down"><function>g_string_ascii_down()</function></link> or <link linkend="g-utf8-strdown"><function>g_utf8_strdown()</function></link> instead.</para>
</warning>
<para>Converts a <link linkend="GString"><type>GString</type></link> to lowercase.</para>
<refsect3 id="g-string-down.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-down.returns" role="returns">
<title>Returns</title>
<para>the <link linkend="GString"><type>GString</type></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-hash" role="function">
<title>g_string_hash&#160;()</title>
<indexterm zone="g-string-hash"><primary sortas="string_hash">g_string_hash</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_string_hash (<parameter>const <link linkend="GString"><type>GString</type></link> *str</parameter>);</programlisting>
<para>Creates a hash code for <parameter>str</parameter>
; for use with <link linkend="GHashTable"><type>GHashTable</type></link>.</para>
<refsect3 id="g-string-hash.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str</para></entry>
<entry role="parameter_description"><para>a string to hash</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-hash.returns" role="returns">
<title>Returns</title>
<para> hash code for <parameter>str</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-string-equal" role="function">
<title>g_string_equal&#160;()</title>
<indexterm zone="g-string-equal"><primary sortas="string_equal">g_string_equal</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_string_equal (<parameter>const <link linkend="GString"><type>GString</type></link> *v</parameter>,
                <parameter>const <link linkend="GString"><type>GString</type></link> *v2</parameter>);</programlisting>
<para>Compares two strings for equality, returning <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if they are equal.
For use with <link linkend="GHashTable"><type>GHashTable</type></link>.</para>
<refsect3 id="g-string-equal.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>v</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>v2</para></entry>
<entry role="parameter_description"><para>another <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-equal.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the strings are the same length and contain the
same bytes</para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="glib-Strings.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GString" role="struct">
<title>struct GString</title>
<indexterm zone="GString"><primary sortas="String">GString</primary></indexterm>
<programlisting language="C">struct GString {
  gchar  *str;
  gsize len;
  gsize allocated_len;
};
</programlisting>
<para>The GString struct contains the public fields of a GString.</para>
<refsect3 id="GString.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><link linkend="gchar"><type>gchar</type></link>&#160;*<structfield id="GString.str">str</structfield>;</para></entry>
<entry role="struct_member_description"><para>points to the character data. It may move as text is added.
The <parameter>str</parameter>
field is null-terminated and so
can be used as an ordinary C string.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="gsize"><type>gsize</type></link>&#160;<structfield id="GString.len">len</structfield>;</para></entry>
<entry role="struct_member_description"><para>contains the length of the string, not including the
terminating nul byte.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="gsize"><type>gsize</type></link>&#160;<structfield id="GString.allocated-len">allocated_len</structfield>;</para></entry>
<entry role="struct_member_description"><para>the number of bytes that can be stored in the
string before it needs to be reallocated. May be larger than <parameter>len</parameter>
.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>
<refsect2 id="g-string-sprintf" role="macro" condition="deprecated:This function has been renamed to g_string_printf().">
<title>g_string_sprintf</title>
<indexterm zone="g-string-sprintf" role="deprecated"><primary sortas="string_sprintf">g_string_sprintf</primary></indexterm>
<programlisting language="C">#define             g_string_sprintf</programlisting>
<warning><para><literal>g_string_sprintf</literal> is deprecated and should not be used in newly-written code.</para> <para>This function has been renamed to <link linkend="g-string-printf"><function>g_string_printf()</function></link>.</para>
</warning>
<para>Writes a formatted string into a <link linkend="GString"><type>GString</type></link>.
This is similar to the standard <link linkend="sprintf"><function>sprintf()</function></link> function,
except that the <link linkend="GString"><type>GString</type></link> buffer automatically expands
to contain the results. The previous contents of the
<link linkend="GString"><type>GString</type></link> are destroyed.</para>
<refsect3 id="g-string-sprintf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>the string format. See the <link linkend="sprintf"><function>sprintf()</function></link> documentation</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>the parameters to insert into the format string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-string-sprintfa" role="macro" condition="deprecated:This function has been renamed to g_string_append_printf()">
<title>g_string_sprintfa</title>
<indexterm zone="g-string-sprintfa" role="deprecated"><primary sortas="string_sprintfa">g_string_sprintfa</primary></indexterm>
<programlisting language="C">#define             g_string_sprintfa</programlisting>
<warning><para><literal>g_string_sprintfa</literal> is deprecated and should not be used in newly-written code.</para> <para>This function has been renamed to <link linkend="g-string-append-printf"><function>g_string_append_printf()</function></link></para>
</warning>
<para>Appends a formatted string onto the end of a <link linkend="GString"><type>GString</type></link>.
This function is similar to <link linkend="g-string-sprintf"><function>g_string_sprintf()</function></link> except that
the text is appended to the <link linkend="GString"><type>GString</type></link>.</para>
<refsect3 id="g-string-sprintfa.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a <link linkend="GString"><type>GString</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>the string format. See the <link linkend="sprintf"><function>sprintf()</function></link> documentation</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>the parameters to insert into the format string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>

</refentry>
