<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 <glib.h>
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>
<link linkend="void">void</link> <link linkend="g-string-printf">g_string_printf</link> (<link linkend="GString">GString</link> *string,
const <link linkend="gchar">gchar</link> *format,
...);
<link linkend="void">void</link> <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"><type>GString</type></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>
<indexterm><primary>GString</primary></indexterm><programlisting>struct GString {
gchar *str;
gsize len;
gsize allocated_len;
};
</programlisting>
<para>
The <link linkend="GString"><type>GString</type></link> struct contains the public fields of a <link linkend="GString"><type>GString</type></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>
<indexterm><primary>g_string_new</primary></indexterm><programlisting><link linkend="GString">GString</link>* g_string_new (const <link linkend="gchar">gchar</link> *init);</programlisting>
<para>
Creates a new <link linkend="GString"><type>GString</type></link>, initialized with the given string.
</para><variablelist role="params">
<varlistentry><term><parameter>init</parameter> :</term>
<listitem><simpara>the initial text to copy into the string.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the new <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-new-len"/>g_string_new_len ()</title>
<indexterm><primary>g_string_new_len</primary></indexterm><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"><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><variablelist role="params">
<varlistentry><term><parameter>init</parameter> :</term>
<listitem><simpara>initial contents of string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter> :</term>
<listitem><simpara>length of <parameter>init</parameter> to use.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-sized-new"/>g_string_sized_new ()</title>
<indexterm><primary>g_string_sized_new</primary></indexterm><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"><type>GString</type></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><variablelist role="params">
<varlistentry><term><parameter>dfl_size</parameter> :</term>
<listitem><simpara>the default size of the space allocated to hold the string.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the new <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-assign"/>g_string_assign ()</title>
<indexterm><primary>g_string_assign</primary></indexterm><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"><type>GString</type></link>, destroying any previous
contents. It is rather like the standard <function><link linkend="strcpy"><function>strcpy()</function></link></function> function, except that
you do not have to worry about having enough space to copy the string.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>the destination <link linkend="GString"><type>GString</type></link>. Its current contents are destroyed.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>rval</parameter> :</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the destination <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-sprintf"/>g_string_sprintf</title>
<indexterm role="deprecated"><primary>g_string_sprintf</primary></indexterm><programlisting>#define g_string_sprintf</programlisting>
<warning><para><literal>g_string_sprintf</literal> is deprecated and should not be used in newly-written code. 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 <function><link linkend="sprintf"><function>sprintf()</function></link></function> 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></refsect2>
<refsect2>
<title><anchor id="g-string-sprintfa"/>g_string_sprintfa</title>
<indexterm role="deprecated"><primary>g_string_sprintfa</primary></indexterm><programlisting>#define g_string_sprintfa</programlisting>
<warning><para><literal>g_string_sprintfa</literal> is deprecated and should not be used in newly-written code. 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 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></refsect2>
<refsect2>
<title><anchor id="g-string-printf"/>g_string_printf ()</title>
<indexterm><primary>g_string_printf</primary></indexterm><programlisting><link linkend="void">void</link> 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"><type>GString</type></link>.
This is similar to the standard <function><link linkend="sprintf"><function>sprintf()</function></link></function> 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><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara>the string format. See the <function><link linkend="printf"><function>printf()</function></link></function>
documentation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara>the parameters to insert into the format string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-append-printf"/>g_string_append_printf ()</title>
<indexterm><primary>g_string_append_printf</primary></indexterm><programlisting><link linkend="void">void</link> 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"><type>GString</type></link>.
This function is 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><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara>the string format. See the <function><link linkend="printf"><function>printf()</function></link></function>
documentation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara>the parameters to insert into the format string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-append"/>g_string_append ()</title>
<indexterm><primary>g_string_append</primary></indexterm><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"><type>GString</type></link>, expanding it if necessary.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>val</parameter> :</term>
<listitem><simpara>the string to append onto the end of the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-append-c"/>g_string_append_c ()</title>
<indexterm><primary>g_string_append_c</primary></indexterm><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"><type>GString</type></link>, expanding it if necessary.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>the character to append onto the end of the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-append-unichar"/>g_string_append_unichar ()</title>
<indexterm><primary>g_string_append_unichar</primary></indexterm><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><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> a <link linkend="GString"><type>GString</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>wc</parameter> :</term>
<listitem><simpara> a Unicode character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>string</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-append-len"/>g_string_append_len ()</title>
<indexterm><primary>g_string_append_len</primary></indexterm><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><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>val</parameter> :</term>
<listitem><simpara>bytes to append.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter> :</term>
<listitem><simpara>number of bytes of <parameter>val</parameter> to use.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-prepend"/>g_string_prepend ()</title>
<indexterm><primary>g_string_prepend</primary></indexterm><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"><type>GString</type></link>, expanding it if necessary.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>val</parameter> :</term>
<listitem><simpara>the string to prepend on the start of the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-prepend-c"/>g_string_prepend_c ()</title>
<indexterm><primary>g_string_prepend_c</primary></indexterm><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"><type>GString</type></link>, expanding it if necessary.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>the character to prepend on the start of the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-prepend-unichar"/>g_string_prepend_unichar ()</title>
<indexterm><primary>g_string_prepend_unichar</primary></indexterm><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><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>wc</parameter> :</term>
<listitem><simpara> a Unicode character.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>string</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-prepend-len"/>g_string_prepend_len ()</title>
<indexterm><primary>g_string_prepend_len</primary></indexterm><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><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>val</parameter> :</term>
<listitem><simpara>bytes to prepend.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter> :</term>
<listitem><simpara>number of bytes in <parameter>val</parameter> to prepend.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GString"><type>GString</type></link> passed in.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-insert"/>g_string_insert ()</title>
<indexterm><primary>g_string_insert</primary></indexterm><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"><type>GString</type></link>, expanding it if necessary.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pos</parameter> :</term>
<listitem><simpara>the position to insert the copy of the string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>val</parameter> :</term>
<listitem><simpara>the string to insert.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-insert-c"/>g_string_insert_c ()</title>
<indexterm><primary>g_string_insert_c</primary></indexterm><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"><type>GString</type></link>, expanding it if necessary.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pos</parameter> :</term>
<listitem><simpara>the position to insert the character.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>the character to insert.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-insert-unichar"/>g_string_insert_unichar ()</title>
<indexterm><primary>g_string_insert_unichar</primary></indexterm><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><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> a <link linkend="GString"><type>GString</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pos</parameter> :</term>
<listitem><simpara> the position at which to insert character, or -1 to
append at the end of the string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>wc</parameter> :</term>
<listitem><simpara> a Unicode character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>string</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-insert-len"/>g_string_insert_len ()</title>
<indexterm><primary>g_string_insert_len</primary></indexterm><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><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pos</parameter> :</term>
<listitem><simpara>position in <parameter>string</parameter> where insertion should happen, or -1 for at the end.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>val</parameter> :</term>
<listitem><simpara>bytes to insert.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter> :</term>
<listitem><simpara>number of bytes of <parameter>val</parameter> to insert.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-erase"/>g_string_erase ()</title>
<indexterm><primary>g_string_erase</primary></indexterm><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"><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><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pos</parameter> :</term>
<listitem><simpara>the position of the characters to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter> :</term>
<listitem><simpara>the number of characters to remove, or -1 to remove all
following characters.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-truncate"/>g_string_truncate ()</title>
<indexterm><primary>g_string_truncate</primary></indexterm><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><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter> :</term>
<listitem><simpara>the new size of the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-set-size"/>g_string_set_size ()</title>
<indexterm><primary>g_string_set_size</primary></indexterm><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"><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>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> a <link linkend="GString"><type>GString</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter> :</term>
<listitem><simpara> the new length
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>string</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-free"/>g_string_free ()</title>
<indexterm><primary>g_string_free</primary></indexterm><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"><type>GString</type></link>.
If <parameter>free_segment</parameter> is <literal>TRUE</literal> it also frees the character data.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>free_segment</parameter> :</term>
<listitem><simpara>if <literal>TRUE</literal> the actual character data is freed as well.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the character data of <parameter>string</parameter> (i.e. <literal>NULL</literal> if <parameter>free_segment</parameter> is <literal>TRUE</literal>)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-up"/>g_string_up ()</title>
<indexterm role="deprecated"><primary>g_string_up</primary></indexterm><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. 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>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> a <link linkend="GString"><type>GString</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="GString"><type>GString</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-down"/>g_string_down ()</title>
<indexterm role="deprecated"><primary>g_string_down</primary></indexterm><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. 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>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> a <link linkend="GString"><type>GString</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-hash"/>g_string_hash ()</title>
<indexterm><primary>g_string_hash</primary></indexterm><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"><type>GHashTable</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter> :</term>
<listitem><simpara>a string to hash.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>hash code for <parameter>str</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-equal"/>g_string_equal ()</title>
<indexterm><primary>g_string_equal</primary></indexterm><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"><type>GHashTable</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>v</parameter> :</term>
<listitem><simpara>a <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>v2</parameter> :</term>
<listitem><simpara>another <link linkend="GString"><type>GString</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if they strings are the same length and contain the same bytes.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
</refentry>