<refentry id="glib-String-Utility-Functions">
<refmeta>
<refentrytitle>String Utility Functions</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>String Utility Functions</refname><refpurpose>various string-related functions.</refpurpose>
</refnamediv>
<refsynopsisdiv><title>Synopsis</title>
<synopsis>
#include <glib.h>
#include <glib/gprintf.h>
<link linkend="gchar">gchar</link>* <link linkend="g-strdup">g_strdup</link> (const <link linkend="gchar">gchar</link> *str);
<link linkend="gchar">gchar</link>* <link linkend="g-strndup">g_strndup</link> (const <link linkend="gchar">gchar</link> *str,
<link linkend="gsize">gsize</link> n);
<link linkend="gchar">gchar</link>** <link linkend="g-strdupv">g_strdupv</link> (<link linkend="gchar">gchar</link> **str_array);
<link linkend="gchar">gchar</link>* <link linkend="g-strnfill">g_strnfill</link> (<link linkend="gsize">gsize</link> length,
<link linkend="gchar">gchar</link> fill_char);
<link linkend="gchar">gchar</link>* <link linkend="g-stpcpy">g_stpcpy</link> (<link linkend="gchar">gchar</link> *dest,
const <link linkend="char">char</link> *src);
<link linkend="gchar">gchar</link>* <link linkend="g-strstr-len">g_strstr_len</link> (const <link linkend="gchar">gchar</link> *haystack,
<link linkend="gssize">gssize</link> haystack_len,
const <link linkend="gchar">gchar</link> *needle);
<link linkend="gchar">gchar</link>* <link linkend="g-strrstr">g_strrstr</link> (const <link linkend="gchar">gchar</link> *haystack,
const <link linkend="gchar">gchar</link> *needle);
<link linkend="gchar">gchar</link>* <link linkend="g-strrstr-len">g_strrstr_len</link> (const <link linkend="gchar">gchar</link> *haystack,
<link linkend="gssize">gssize</link> haystack_len,
const <link linkend="gchar">gchar</link> *needle);
<link linkend="gboolean">gboolean</link> <link linkend="g-str-has-prefix">g_str_has_prefix</link> (const <link linkend="gchar">gchar</link> *str,
const <link linkend="gchar">gchar</link> *prefix);
<link linkend="gboolean">gboolean</link> <link linkend="g-str-has-suffix">g_str_has_suffix</link> (const <link linkend="gchar">gchar</link> *str,
const <link linkend="gchar">gchar</link> *suffix);
<link linkend="gsize">gsize</link> <link linkend="g-strlcpy">g_strlcpy</link> (<link linkend="gchar">gchar</link> *dest,
const <link linkend="gchar">gchar</link> *src,
<link linkend="gsize">gsize</link> dest_size);
<link linkend="gsize">gsize</link> <link linkend="g-strlcat">g_strlcat</link> (<link linkend="gchar">gchar</link> *dest,
const <link linkend="gchar">gchar</link> *src,
<link linkend="gsize">gsize</link> dest_size);
<link linkend="gchar">gchar</link>* <link linkend="g-strdup-printf">g_strdup_printf</link> (const <link linkend="gchar">gchar</link> *format,
...);
<link linkend="gchar">gchar</link>* <link linkend="g-strdup-vprintf">g_strdup_vprintf</link> (const <link linkend="gchar">gchar</link> *format,
<link linkend="va-list">va_list</link> args);
<link linkend="gint">gint</link> <link linkend="g-printf">g_printf</link> (<link linkend="gchar">gchar</link> const *format,
...);
<link linkend="gint">gint</link> <link linkend="g-vprintf">g_vprintf</link> (<link linkend="gchar">gchar</link> const *format,
<link linkend="va-list">va_list</link> args);
<link linkend="gint">gint</link> <link linkend="g-fprintf">g_fprintf</link> (<link linkend="FILE-CAPS">FILE</link> *file,
<link linkend="gchar">gchar</link> const *format,
...);
<link linkend="gint">gint</link> <link linkend="g-vfprintf">g_vfprintf</link> (<link linkend="FILE-CAPS">FILE</link> *file,
<link linkend="gchar">gchar</link> const *format,
<link linkend="va-list">va_list</link> args);
<link linkend="gint">gint</link> <link linkend="g-sprintf">g_sprintf</link> (<link linkend="gchar">gchar</link> *string,
<link linkend="gchar">gchar</link> const *format,
...);
<link linkend="gint">gint</link> <link linkend="g-vsprintf">g_vsprintf</link> (<link linkend="gchar">gchar</link> *string,
<link linkend="gchar">gchar</link> const *format,
<link linkend="va-list">va_list</link> args);
<link linkend="gint">gint</link> <link linkend="g-snprintf">g_snprintf</link> (<link linkend="gchar">gchar</link> *string,
<link linkend="gulong">gulong</link> n,
<link linkend="gchar">gchar</link> const *format,
...);
<link linkend="gint">gint</link> <link linkend="g-vsnprintf">g_vsnprintf</link> (<link linkend="gchar">gchar</link> *string,
<link linkend="gulong">gulong</link> n,
<link linkend="gchar">gchar</link> const *format,
<link linkend="va-list">va_list</link> args);
<link linkend="gint">gint</link> <link linkend="g-vasprintf">g_vasprintf</link> (<link linkend="gchar">gchar</link> **string,
<link linkend="gchar">gchar</link> const *format,
<link linkend="va-list">va_list</link> args);
<link linkend="gsize">gsize</link> <link linkend="g-printf-string-upper-bound">g_printf_string_upper_bound</link> (const <link linkend="gchar">gchar</link> *format,
<link linkend="va-list">va_list</link> args);
<link linkend="gboolean">gboolean</link> <link linkend="g-ascii-isalnum">g_ascii_isalnum</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link> <link linkend="g-ascii-isalpha">g_ascii_isalpha</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link> <link linkend="g-ascii-iscntrl">g_ascii_iscntrl</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link> <link linkend="g-ascii-isdigit">g_ascii_isdigit</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link> <link linkend="g-ascii-isgraph">g_ascii_isgraph</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link> <link linkend="g-ascii-islower">g_ascii_islower</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link> <link linkend="g-ascii-isprint">g_ascii_isprint</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link> <link linkend="g-ascii-ispunct">g_ascii_ispunct</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link> <link linkend="g-ascii-isspace">g_ascii_isspace</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link> <link linkend="g-ascii-isupper">g_ascii_isupper</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gboolean">gboolean</link> <link linkend="g-ascii-isxdigit">g_ascii_isxdigit</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gint">gint</link> <link linkend="g-ascii-digit-value">g_ascii_digit_value</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gint">gint</link> <link linkend="g-ascii-xdigit-value">g_ascii_xdigit_value</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gint">gint</link> <link linkend="g-ascii-strcasecmp">g_ascii_strcasecmp</link> (const <link linkend="gchar">gchar</link> *s1,
const <link linkend="gchar">gchar</link> *s2);
<link linkend="gint">gint</link> <link linkend="g-ascii-strncasecmp">g_ascii_strncasecmp</link> (const <link linkend="gchar">gchar</link> *s1,
const <link linkend="gchar">gchar</link> *s2,
<link linkend="gsize">gsize</link> n);
<link linkend="gchar">gchar</link>* <link linkend="g-ascii-strup">g_ascii_strup</link> (const <link linkend="gchar">gchar</link> *str,
<link linkend="gssize">gssize</link> len);
<link linkend="gchar">gchar</link>* <link linkend="g-ascii-strdown">g_ascii_strdown</link> (const <link linkend="gchar">gchar</link> *str,
<link linkend="gssize">gssize</link> len);
<link linkend="gchar">gchar</link> <link linkend="g-ascii-tolower">g_ascii_tolower</link> (<link linkend="gchar">gchar</link> c);
<link linkend="gchar">gchar</link> <link linkend="g-ascii-toupper">g_ascii_toupper</link> (<link linkend="gchar">gchar</link> c);
<link linkend="GString">GString</link>* <link linkend="g-string-ascii-up">g_string_ascii_up</link> (<link linkend="GString">GString</link> *string);
<link linkend="GString">GString</link>* <link linkend="g-string-ascii-down">g_string_ascii_down</link> (<link linkend="GString">GString</link> *string);
<link linkend="gchar">gchar</link>* <link linkend="g-strup">g_strup</link> (<link linkend="gchar">gchar</link> *string);
<link linkend="gchar">gchar</link>* <link linkend="g-strdown">g_strdown</link> (<link linkend="gchar">gchar</link> *string);
<link linkend="gint">gint</link> <link linkend="g-strcasecmp">g_strcasecmp</link> (const <link linkend="gchar">gchar</link> *s1,
const <link linkend="gchar">gchar</link> *s2);
<link linkend="gint">gint</link> <link linkend="g-strncasecmp">g_strncasecmp</link> (const <link linkend="gchar">gchar</link> *s1,
const <link linkend="gchar">gchar</link> *s2,
<link linkend="guint">guint</link> n);
<link linkend="gchar">gchar</link>* <link linkend="g-strreverse">g_strreverse</link> (<link linkend="gchar">gchar</link> *string);
<link linkend="guint64">guint64</link> <link linkend="g-ascii-strtoull">g_ascii_strtoull</link> (const <link linkend="gchar">gchar</link> *nptr,
<link linkend="gchar">gchar</link> **endptr,
<link linkend="guint">guint</link> base);
#define <link linkend="G-ASCII-DTOSTR-BUF-SIZE-CAPS">G_ASCII_DTOSTR_BUF_SIZE</link>
<link linkend="gdouble">gdouble</link> <link linkend="g-ascii-strtod">g_ascii_strtod</link> (const <link linkend="gchar">gchar</link> *nptr,
<link linkend="gchar">gchar</link> **endptr);
<link linkend="gchar">gchar</link>* <link linkend="g-ascii-dtostr">g_ascii_dtostr</link> (<link linkend="gchar">gchar</link> *buffer,
<link linkend="gint">gint</link> buf_len,
<link linkend="gdouble">gdouble</link> d);
<link linkend="gchar">gchar</link>* <link linkend="g-ascii-formatd">g_ascii_formatd</link> (<link linkend="gchar">gchar</link> *buffer,
<link linkend="gint">gint</link> buf_len,
const <link linkend="gchar">gchar</link> *format,
<link linkend="gdouble">gdouble</link> d);
<link linkend="gdouble">gdouble</link> <link linkend="g-strtod">g_strtod</link> (const <link linkend="gchar">gchar</link> *nptr,
<link linkend="gchar">gchar</link> **endptr);
<link linkend="gchar">gchar</link>* <link linkend="g-strchug">g_strchug</link> (<link linkend="gchar">gchar</link> *string);
<link linkend="gchar">gchar</link>* <link linkend="g-strchomp">g_strchomp</link> (<link linkend="gchar">gchar</link> *string);
#define <link linkend="g-strstrip">g_strstrip</link> ( string )
<link linkend="gchar">gchar</link>* <link linkend="g-strdelimit">g_strdelimit</link> (<link linkend="gchar">gchar</link> *string,
const <link linkend="gchar">gchar</link> *delimiters,
<link linkend="gchar">gchar</link> new_delimiter);
#define <link linkend="G-STR-DELIMITERS-CAPS">G_STR_DELIMITERS</link>
<link linkend="gchar">gchar</link>* <link linkend="g-strescape">g_strescape</link> (const <link linkend="gchar">gchar</link> *source,
const <link linkend="gchar">gchar</link> *exceptions);
<link linkend="gchar">gchar</link>* <link linkend="g-strcompress">g_strcompress</link> (const <link linkend="gchar">gchar</link> *source);
<link linkend="gchar">gchar</link>* <link linkend="g-strcanon">g_strcanon</link> (<link linkend="gchar">gchar</link> *string,
const <link linkend="gchar">gchar</link> *valid_chars,
<link linkend="gchar">gchar</link> substitutor);
<link linkend="gchar">gchar</link>** <link linkend="g-strsplit">g_strsplit</link> (const <link linkend="gchar">gchar</link> *string,
const <link linkend="gchar">gchar</link> *delimiter,
<link linkend="gint">gint</link> max_tokens);
<link linkend="gchar">gchar</link>** <link linkend="g-strsplit-set">g_strsplit_set</link> (const <link linkend="gchar">gchar</link> *string,
const <link linkend="gchar">gchar</link> *delimiters,
<link linkend="gint">gint</link> max_tokens);
<link linkend="void">void</link> <link linkend="g-strfreev">g_strfreev</link> (<link linkend="gchar">gchar</link> **str_array);
<link linkend="gchar">gchar</link>* <link linkend="g-strconcat">g_strconcat</link> (const <link linkend="gchar">gchar</link> *string1,
...);
<link linkend="gchar">gchar</link>* <link linkend="g-strjoin">g_strjoin</link> (const <link linkend="gchar">gchar</link> *separator,
...);
<link linkend="gchar">gchar</link>* <link linkend="g-strjoinv">g_strjoinv</link> (const <link linkend="gchar">gchar</link> *separator,
<link linkend="gchar">gchar</link> **str_array);
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-strerror">g_strerror</link> (<link linkend="gint">gint</link> errnum);
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-strsignal">g_strsignal</link> (<link linkend="gint">gint</link> signum);
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
This section describes a number of utility functions for creating,
duplicating, and manipulating strings.
</para>
<para>
Note that the functions <link linkend="g-printf"><function>g_printf()</function></link>, <link linkend="g-fprintf"><function>g_fprintf()</function></link>, <link linkend="g-sprintf"><function>g_sprintf()</function></link>, <link linkend="g-snprintf"><function>g_snprintf()</function></link>,
<link linkend="g-vprintf"><function>g_vprintf()</function></link>, <link linkend="g-vfprintf"><function>g_vfprintf()</function></link>, <link linkend="g-vsprintf"><function>g_vsprintf()</function></link> and <link linkend="g-vsnprintf"><function>g_vsnprintf()</function></link> are declared in
the header <filename>gprintf.h</filename> which is <emphasis>not</emphasis>
included in <filename>glib.h</filename> (otherwise using
<filename>glib.h</filename> would drag in <filename>stdio.h</filename>), so
you'll have to explicitly include <literal><glib/gprintf.h></literal>
in order to use the GLib <link linkend="printf"><function>printf()</function></link> functions.
</para>
<para id="string-precision">
While you may use the <link linkend="printf"><function>printf()</function></link> functions to format UTF-8 strings, notice that
the precision of a <literal>%Ns</literal> parameter is interpreted as the
number of <emphasis>bytes</emphasis>, not <emphasis>characters</emphasis> to print.
On top of that, the GNU libc implementation of the <link linkend="printf"><function>printf()</function></link> functions has the "feature"
that it checks that the string given for the <literal>%Ns</literal> parameter
consists of a whole number of characters in the current encoding. So, unless you
are sure you are always going to be in an UTF-8 locale or your know your text is restricted
to ASCII, avoid using <literal>%Ns</literal>.
If your intention is to format strings for a certain number of columns, then
<literal>%Ns</literal> is not a correct solution anyway, since it fails to take
wide characters (see <link linkend="g-unichar-iswide"><function>g_unichar_iswide()</function></link>) into account.
</para>
</refsect1>
<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="g-strdup"/>g_strdup ()</title>
<indexterm><primary>g_strdup</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strdup (const <link linkend="gchar">gchar</link> *str);</programlisting>
<para>
Duplicates a string.
If <parameter>str</parameter> is <literal>NULL</literal> it returns <literal>NULL</literal>.
The returned string should be freed when no longer needed.
</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter> :</term>
<listitem><simpara>the string to duplicate.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a newly-allocated copy of <parameter>str</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strndup"/>g_strndup ()</title>
<indexterm><primary>g_strndup</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strndup (const <link linkend="gchar">gchar</link> *str,
<link linkend="gsize">gsize</link> n);</programlisting>
<para>
Duplicates the first <parameter>n</parameter> characters of a string, returning a newly-allocated
buffer <parameter>n</parameter> + 1 characters long which will always be nul-terminated.
If <parameter>str</parameter> is less than <parameter>n</parameter> characters long the buffer is padded with nuls.
If <parameter>str</parameter> is <literal>NULL</literal> it returns <literal>NULL</literal>.
The returned value should be freed when no longer needed.
</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter> :</term>
<listitem><simpara>the string to duplicate part of.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n</parameter> :</term>
<listitem><simpara>the maximum number of characters to copy from <parameter>str</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a newly-allocated buffer containing the first <parameter>n</parameter> characters of <parameter>str</parameter>,
nul-terminated.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strdupv"/>g_strdupv ()</title>
<indexterm><primary>g_strdupv</primary></indexterm><programlisting><link linkend="gchar">gchar</link>** g_strdupv (<link linkend="gchar">gchar</link> **str_array);</programlisting>
<para>
Copies <literal>NULL</literal>-terminated array of strings. The copy is a deep copy;
the new array should be freed by first freeing each string, then
the array itself. <link linkend="g-strfreev"><function>g_strfreev()</function></link> does this for you. If called
on a <literal>NULL</literal> value, <link linkend="g-strdupv"><function>g_strdupv()</function></link> simply returns <literal>NULL</literal>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str_array</parameter> :</term>
<listitem><simpara> <literal>NULL</literal>-terminated array of strings.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new <literal>NULL</literal>-terminated array of strings.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strnfill"/>g_strnfill ()</title>
<indexterm><primary>g_strnfill</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strnfill (<link linkend="gsize">gsize</link> length,
<link linkend="gchar">gchar</link> fill_char);</programlisting>
<para>
Creates a new string <parameter>length</parameter> characters long filled with <parameter>fill_char</parameter>.
The returned string should be freed when no longer needed.
</para><variablelist role="params">
<varlistentry><term><parameter>length</parameter> :</term>
<listitem><simpara>the length of the new string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fill_char</parameter> :</term>
<listitem><simpara>the character to fill the string with.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a newly-allocated string filled the <parameter>fill_char</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-stpcpy"/>g_stpcpy ()</title>
<indexterm><primary>g_stpcpy</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_stpcpy (<link linkend="gchar">gchar</link> *dest,
const <link linkend="char">char</link> *src);</programlisting>
<para>
Copies a nul-terminated string into the dest buffer, include the
trailing nul, and return a pointer to the trailing nul byte.
This is useful for concatenating multiple strings together
without having to repeatedly scan for the end.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>dest</parameter> :</term>
<listitem><simpara> destination buffer.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>src</parameter> :</term>
<listitem><simpara> source string.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to trailing nul byte.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strstr-len"/>g_strstr_len ()</title>
<indexterm><primary>g_strstr_len</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strstr_len (const <link linkend="gchar">gchar</link> *haystack,
<link linkend="gssize">gssize</link> haystack_len,
const <link linkend="gchar">gchar</link> *needle);</programlisting>
<para>
Searches the string <parameter>haystack</parameter> for the first occurrence
of the string <parameter>needle</parameter>, limiting the length of the search
to <parameter>haystack_len</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>haystack</parameter> :</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>haystack_len</parameter> :</term>
<listitem><simpara> the maximum length of <parameter>haystack</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>needle</parameter> :</term>
<listitem><simpara> the string to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to the found occurrence, or
<literal>NULL</literal> if not found.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strrstr"/>g_strrstr ()</title>
<indexterm><primary>g_strrstr</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strrstr (const <link linkend="gchar">gchar</link> *haystack,
const <link linkend="gchar">gchar</link> *needle);</programlisting>
<para>
Searches the string <parameter>haystack</parameter> for the last occurrence
of the string <parameter>needle</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>haystack</parameter> :</term>
<listitem><simpara> a nul-terminated string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>needle</parameter> :</term>
<listitem><simpara> the nul-terminated string to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to the found occurrence, or
<literal>NULL</literal> if not found.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strrstr-len"/>g_strrstr_len ()</title>
<indexterm><primary>g_strrstr_len</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strrstr_len (const <link linkend="gchar">gchar</link> *haystack,
<link linkend="gssize">gssize</link> haystack_len,
const <link linkend="gchar">gchar</link> *needle);</programlisting>
<para>
Searches the string <parameter>haystack</parameter> for the last occurrence
of the string <parameter>needle</parameter>, limiting the length of the search
to <parameter>haystack_len</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>haystack</parameter> :</term>
<listitem><simpara> a nul-terminated string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>haystack_len</parameter> :</term>
<listitem><simpara> the maximum length of <parameter>haystack</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>needle</parameter> :</term>
<listitem><simpara> the nul-terminated string to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to the found occurrence, or
<literal>NULL</literal> if not found.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-str-has-prefix"/>g_str_has_prefix ()</title>
<indexterm role="2.2"><primary>g_str_has_prefix</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_str_has_prefix (const <link linkend="gchar">gchar</link> *str,
const <link linkend="gchar">gchar</link> *prefix);</programlisting>
<para>
Looks whether the string <parameter>str</parameter> begins with <parameter>prefix</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter> :</term>
<listitem><simpara> a nul-terminated string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>prefix</parameter> :</term>
<listitem><simpara> the nul-terminated prefix to look for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if <parameter>str</parameter> begins with <parameter>prefix</parameter>, <literal>FALSE</literal> otherwise.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.2
</para></refsect2>
<refsect2>
<title><anchor id="g-str-has-suffix"/>g_str_has_suffix ()</title>
<indexterm role="2.2"><primary>g_str_has_suffix</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_str_has_suffix (const <link linkend="gchar">gchar</link> *str,
const <link linkend="gchar">gchar</link> *suffix);</programlisting>
<para>
Looks whether the string <parameter>str</parameter> ends with <parameter>suffix</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter> :</term>
<listitem><simpara> a nul-terminated string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>suffix</parameter> :</term>
<listitem><simpara> the nul-terminated suffix to look for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if <parameter>str</parameter> end with <parameter>suffix</parameter>, <literal>FALSE</literal> otherwise.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.2
</para></refsect2>
<refsect2>
<title><anchor id="g-strlcpy"/>g_strlcpy ()</title>
<indexterm><primary>g_strlcpy</primary></indexterm><programlisting><link linkend="gsize">gsize</link> g_strlcpy (<link linkend="gchar">gchar</link> *dest,
const <link linkend="gchar">gchar</link> *src,
<link linkend="gsize">gsize</link> dest_size);</programlisting>
<para>
Portability wrapper that calls <link linkend="strlcpy"><function>strlcpy()</function></link> on systems which have it, and emulates
<link linkend="strlcpy"><function>strlcpy()</function></link> otherwise. Copies <parameter>src</parameter> to <parameter>dest</parameter>; <parameter>dest</parameter> is guaranteed to be
nul-terminated; <parameter>src</parameter> must be nul-terminated; <parameter>dest_size</parameter> is the buffer size, not
the number of chars to copy. Caveat: <link linkend="strlcpy"><function>strlcpy()</function></link> is supposedly more secure than
<link linkend="strcpy"><function>strcpy()</function></link> or <link linkend="strncpy"><function>strncpy()</function></link>, but if you really want to avoid screwups, <link linkend="g-strdup"><function>g_strdup()</function></link> is
an even better idea.
</para><variablelist role="params">
<varlistentry><term><parameter>dest</parameter> :</term>
<listitem><simpara>destination buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>src</parameter> :</term>
<listitem><simpara>source buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dest_size</parameter> :</term>
<listitem><simpara>length of <parameter>dest</parameter> in bytes
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>length of <parameter>src</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strlcat"/>g_strlcat ()</title>
<indexterm><primary>g_strlcat</primary></indexterm><programlisting><link linkend="gsize">gsize</link> g_strlcat (<link linkend="gchar">gchar</link> *dest,
const <link linkend="gchar">gchar</link> *src,
<link linkend="gsize">gsize</link> dest_size);</programlisting>
<para>
Portability wrapper that calls <link linkend="strlcat"><function>strlcat()</function></link> on systems which have it, and emulates it otherwise.
Appends nul-terminated <parameter>src</parameter> string to <parameter>dest</parameter>, guaranteeing
nul-termination for <parameter>dest</parameter>. The total size of <parameter>dest</parameter> won't exceed
<parameter>dest_size</parameter>. Caveat: this is supposedly a more secure alternative to <link linkend="strcat"><function>strcat()</function></link> or
<link linkend="strncat"><function>strncat()</function></link>, but for real security <link linkend="g-strconcat"><function>g_strconcat()</function></link> is harder to mess up.
</para><variablelist role="params">
<varlistentry><term><parameter>dest</parameter> :</term>
<listitem><simpara>destination buffer, already containing one nul-terminated string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>src</parameter> :</term>
<listitem><simpara>source buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dest_size</parameter> :</term>
<listitem><simpara>length of <parameter>dest</parameter> buffer in bytes (not length of existing string inside <parameter>dest</parameter>)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>length of <parameter>src</parameter> plus initial length of string in <parameter>dest</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strdup-printf"/>g_strdup_printf ()</title>
<indexterm><primary>g_strdup_printf</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strdup_printf (const <link linkend="gchar">gchar</link> *format,
...);</programlisting>
<para>
Similar to the standard C <link linkend="sprintf"><function>sprintf()</function></link> function
but safer, since it calculates the maximum space required and allocates
memory to hold the result.
The returned string should be freed when no longer needed.
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara>a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara>the parameters to insert into the format string.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a newly-allocated string holding the result.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strdup-vprintf"/>g_strdup_vprintf ()</title>
<indexterm><primary>g_strdup_vprintf</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strdup_vprintf (const <link linkend="gchar">gchar</link> *format,
<link linkend="va-list">va_list</link> args);</programlisting>
<para>
Similar to the standard C <link linkend="vsprintf"><function>vsprintf()</function></link> function
but safer, since it calculates the maximum space required and allocates
memory to hold the result.
The returned string should be freed when no longer needed.
</para>
<para>
See also <link linkend="g-vasprintf"><function>g_vasprintf()</function></link>, which offers the same functionality, but additionally
returns the length of the allocated string.
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara>a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter> :</term>
<listitem><simpara>the list of parameters to insert into the format string.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a newly-allocated string holding the result.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-printf"/>g_printf ()</title>
<indexterm role="2.2"><primary>g_printf</primary></indexterm><programlisting><link linkend="gint">gint</link> g_printf (<link linkend="gchar">gchar</link> const *format,
...);</programlisting>
<para>
An implementation of the standard <link linkend="printf"><function>printf()</function></link> function which supports
positional parameters, as specified in the Single Unix Specification.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara> the arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of characters printed.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.2
</para></refsect2>
<refsect2>
<title><anchor id="g-vprintf"/>g_vprintf ()</title>
<indexterm role="2.2"><primary>g_vprintf</primary></indexterm><programlisting><link linkend="gint">gint</link> g_vprintf (<link linkend="gchar">gchar</link> const *format,
<link linkend="va-list">va_list</link> args);</programlisting>
<para>
An implementation of the standard <link linkend="vprintf"><function>vprintf()</function></link> function which supports
positional parameters, as specified in the Single Unix Specification.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter> :</term>
<listitem><simpara> the list of arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of characters printed.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.2
</para></refsect2>
<refsect2>
<title><anchor id="g-fprintf"/>g_fprintf ()</title>
<indexterm role="2.2"><primary>g_fprintf</primary></indexterm><programlisting><link linkend="gint">gint</link> g_fprintf (<link linkend="FILE-CAPS">FILE</link> *file,
<link linkend="gchar">gchar</link> const *format,
...);</programlisting>
<para>
An implementation of the standard <link linkend="fprintf"><function>fprintf()</function></link> function which supports
positional parameters, as specified in the Single Unix Specification.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>file</parameter> :</term>
<listitem><simpara> the stream to write to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara> the arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of characters printed.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.2
</para></refsect2>
<refsect2>
<title><anchor id="g-vfprintf"/>g_vfprintf ()</title>
<indexterm role="2.2"><primary>g_vfprintf</primary></indexterm><programlisting><link linkend="gint">gint</link> g_vfprintf (<link linkend="FILE-CAPS">FILE</link> *file,
<link linkend="gchar">gchar</link> const *format,
<link linkend="va-list">va_list</link> args);</programlisting>
<para>
An implementation of the standard <link linkend="fprintf"><function>fprintf()</function></link> function which supports
positional parameters, as specified in the Single Unix Specification.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>file</parameter> :</term>
<listitem><simpara> the stream to write to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter> :</term>
<listitem><simpara> the list of arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of characters printed.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.2
</para></refsect2>
<refsect2>
<title><anchor id="g-sprintf"/>g_sprintf ()</title>
<indexterm role="2.2"><primary>g_sprintf</primary></indexterm><programlisting><link linkend="gint">gint</link> g_sprintf (<link linkend="gchar">gchar</link> *string,
<link linkend="gchar">gchar</link> const *format,
...);</programlisting>
<para>
An implementation of the standard <link linkend="sprintf"><function>sprintf()</function></link> function which supports
positional parameters, as specified in the Single Unix Specification.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> the buffer to hold the output.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara> the arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of characters printed.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.2
</para></refsect2>
<refsect2>
<title><anchor id="g-vsprintf"/>g_vsprintf ()</title>
<indexterm role="2.2"><primary>g_vsprintf</primary></indexterm><programlisting><link linkend="gint">gint</link> g_vsprintf (<link linkend="gchar">gchar</link> *string,
<link linkend="gchar">gchar</link> const *format,
<link linkend="va-list">va_list</link> args);</programlisting>
<para>
An implementation of the standard <link linkend="vsprintf"><function>vsprintf()</function></link> function which supports
positional parameters, as specified in the Single Unix Specification.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> the buffer to hold the output.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter> :</term>
<listitem><simpara> the list of arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of characters printed.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.2
</para></refsect2>
<refsect2>
<title><anchor id="g-snprintf"/>g_snprintf ()</title>
<indexterm><primary>g_snprintf</primary></indexterm><programlisting><link linkend="gint">gint</link> g_snprintf (<link linkend="gchar">gchar</link> *string,
<link linkend="gulong">gulong</link> n,
<link linkend="gchar">gchar</link> const *format,
...);</programlisting>
<para>
A safer form of the standard <link linkend="sprintf"><function>sprintf()</function></link> function. The output is guaranteed
to not exceed <parameter>n</parameter> characters (including the terminating nul character), so
it is easy to ensure that a buffer overflow cannot occur.
</para>
<para>
See also <link linkend="g-strdup-printf"><function>g_strdup_printf()</function></link>.
</para>
<para>
In versions of GLib prior to 1.2.3, this function may return -1 if the
output was truncated, and the truncated string may not be nul-terminated.
In versions prior to 1.3.12, this function returns the length of the output
string.
</para>
<para>
The return value of <link linkend="g-snprintf"><function>g_snprintf()</function></link> conforms to the <link linkend="snprintf"><function>snprintf()</function></link>
function as standardized in ISO C99. Note that this is different from
traditional <link linkend="snprintf"><function>snprintf()</function></link>, which returns the length of the output string.
</para>
<para>
The format string may contain positional parameters, as specified in
the Single Unix Specification.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> the buffer to hold the output.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n</parameter> :</term>
<listitem><simpara> the maximum number of characters to produce (including the
terminating nul character).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara> the arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of characters which would be produced if the buffer
was large enough.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-vsnprintf"/>g_vsnprintf ()</title>
<indexterm><primary>g_vsnprintf</primary></indexterm><programlisting><link linkend="gint">gint</link> g_vsnprintf (<link linkend="gchar">gchar</link> *string,
<link linkend="gulong">gulong</link> n,
<link linkend="gchar">gchar</link> const *format,
<link linkend="va-list">va_list</link> args);</programlisting>
<para>
A safer form of the standard <link linkend="vsprintf"><function>vsprintf()</function></link> function. The output is guaranteed
to not exceed <parameter>n</parameter> characters (including the terminating nul character), so
it is easy to ensure that a buffer overflow cannot occur.
</para>
<para>
See also <link linkend="g-strdup-vprintf"><function>g_strdup_vprintf()</function></link>.
</para>
<para>
In versions of GLib prior to 1.2.3, this function may return -1 if the
output was truncated, and the truncated string may not be nul-terminated.
In versions prior to 1.3.12, this function returns the length of the output
string.
</para>
<para>
The return value of <link linkend="g-vsnprintf"><function>g_vsnprintf()</function></link> conforms to the <link linkend="vsnprintf"><function>vsnprintf()</function></link> function
as standardized in ISO C99. Note that this is different from traditional
<link linkend="vsnprintf"><function>vsnprintf()</function></link>, which returns the length of the output string.
</para>
<para>
The format string may contain positional parameters, as specified in
the Single Unix Specification.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> the buffer to hold the output.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n</parameter> :</term>
<listitem><simpara> the maximum number of characters to produce (including the
terminating nul character).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter> :</term>
<listitem><simpara> the list of arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of characters which would be produced if the buffer
was large enough.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-vasprintf"/>g_vasprintf ()</title>
<indexterm role="2.4"><primary>g_vasprintf</primary></indexterm><programlisting><link linkend="gint">gint</link> g_vasprintf (<link linkend="gchar">gchar</link> **string,
<link linkend="gchar">gchar</link> const *format,
<link linkend="va-list">va_list</link> args);</programlisting>
<para>
An implementation of the GNU <link linkend="vasprintf"><function>vasprintf()</function></link> function which supports
positional parameters, as specified in the Single Unix Specification.
This function is similar to <link linkend="g-vsprintf"><function>g_vsprintf()</function></link>, except that it allocates a
string to hold the output, instead of putting the output in a buffer
you allocate in advance.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> the return location for the newly-allocated string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter> :</term>
<listitem><simpara> the list of arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of characters printed.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
<refsect2>
<title><anchor id="g-printf-string-upper-bound"/>g_printf_string_upper_bound ()</title>
<indexterm><primary>g_printf_string_upper_bound</primary></indexterm><programlisting><link linkend="gsize">gsize</link> g_printf_string_upper_bound (const <link linkend="gchar">gchar</link> *format,
<link linkend="va-list">va_list</link> args);</programlisting>
<para>
Calculates the maximum space needed to store the output of the <link linkend="sprintf"><function>sprintf()</function></link> function.
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara>the format string. See the <link linkend="printf"><function>printf()</function></link> documentation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter> :</term>
<listitem><simpara>the parameters to be inserted into the format string.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the maximum space needed to store the formatted string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-isalnum"/>g_ascii_isalnum ()</title>
<indexterm><primary>g_ascii_isalnum</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_ascii_isalnum (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is alphanumeric.
</para>
<para>
Unlike the standard C library <link linkend="isalnum"><function>isalnum()</function></link> function, this only
recognizes standard ASCII letters and ignores the locale, returning
<literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>,
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar"><type>guchar</type></link> before passing a
possibly non-ASCII character in.
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII alphanumeric character
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-isalpha"/>g_ascii_isalpha ()</title>
<indexterm><primary>g_ascii_isalpha</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_ascii_isalpha (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is alphabetic (i.e. a letter).
</para>
<para>
Unlike the standard C library <link linkend="isalpha"><function>isalpha()</function></link> function, this only
recognizes standard ASCII letters and ignores the locale, returning
<literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>,
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar"><type>guchar</type></link> before passing a
possibly non-ASCII character in.
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII alphabetic character
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-iscntrl"/>g_ascii_iscntrl ()</title>
<indexterm><primary>g_ascii_iscntrl</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_ascii_iscntrl (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is a control character.
</para>
<para>
Unlike the standard C library <link linkend="iscntrl"><function>iscntrl()</function></link> function, this only
recognizes standard ASCII control characters and ignores the locale,
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>,
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar"><type>guchar</type></link> before passing a
possibly non-ASCII character in.
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII control character.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-isdigit"/>g_ascii_isdigit ()</title>
<indexterm><primary>g_ascii_isdigit</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_ascii_isdigit (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is digit (0-9).
</para>
<para>
Unlike the standard C library <link linkend="isdigit"><function>isdigit()</function></link> function,
this takes a <type>char</type>, not an <type>int</type>, so don't call it
on <literal>EOF</literal> but no need to cast to <link linkend="guchar"><type>guchar</type></link> before passing a possibly
non-ASCII character in.
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII digit.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-isgraph"/>g_ascii_isgraph ()</title>
<indexterm><primary>g_ascii_isgraph</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_ascii_isgraph (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is a printing character and not a space.
</para>
<para>
Unlike the standard C library <link linkend="isgraph"><function>isgraph()</function></link> function,
this only recognizes standard ASCII characters and ignores the locale,
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>,
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar"><type>guchar</type></link> before passing a
possibly non-ASCII character in.
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII printing character other than space.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-islower"/>g_ascii_islower ()</title>
<indexterm><primary>g_ascii_islower</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_ascii_islower (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is an ASCII lower case letter.
</para>
<para>
Unlike the standard C library <link linkend="islower"><function>islower()</function></link> function,
this only recognizes standard ASCII letters and ignores the locale,
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>,
so don't call it on <literal>EOF</literal> but no need to worry about casting to <link linkend="guchar"><type>guchar</type></link>
before passing a possibly non-ASCII character in.
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII lower case letter
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-isprint"/>g_ascii_isprint ()</title>
<indexterm><primary>g_ascii_isprint</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_ascii_isprint (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is a printing character.
</para>
<para>
Unlike the standard C library <link linkend="isprint"><function>isprint()</function></link> function,
this only recognizes standard ASCII characters and ignores the locale,
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>,
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar"><type>guchar</type></link> before passing a
possibly non-ASCII character in.
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII printing character.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-ispunct"/>g_ascii_ispunct ()</title>
<indexterm><primary>g_ascii_ispunct</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_ascii_ispunct (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is a punctuation character.
</para>
<para>
Unlike the standard C library <link linkend="ispunct"><function>ispunct()</function></link> function,
this only recognizes standard ASCII letters and ignores the locale,
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>,
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar"><type>guchar</type></link> before passing a
possibly non-ASCII character in.
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII punctuation character.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-isspace"/>g_ascii_isspace ()</title>
<indexterm><primary>g_ascii_isspace</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_ascii_isspace (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is a white-space character.
</para>
<para>
Unlike the standard C library <link linkend="isspace"><function>isspace()</function></link> function,
this only recognizes standard ASCII white-space and ignores the locale,
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>,
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar"><type>guchar</type></link> before passing a
possibly non-ASCII character in.
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII white-space character
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-isupper"/>g_ascii_isupper ()</title>
<indexterm><primary>g_ascii_isupper</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_ascii_isupper (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is an ASCII upper case letter.
</para>
<para>
Unlike the standard C library <link linkend="isupper"><function>isupper()</function></link> function,
this only recognizes standard ASCII letters and ignores the locale,
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>,
so don't call it on <literal>EOF</literal> but no need to worry about casting to <link linkend="guchar"><type>guchar</type></link>
before passing a possibly non-ASCII character in.
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII upper case letter
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-isxdigit"/>g_ascii_isxdigit ()</title>
<indexterm><primary>g_ascii_isxdigit</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_ascii_isxdigit (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines whether a character is a hexadecimal-digit character.
</para>
<para>
Unlike the standard C library <link linkend="isxdigit"><function>isxdigit()</function></link> function,
this takes a <type>char</type>, not an <type>int</type>, so
don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar"><type>guchar</type></link> before passing a
possibly non-ASCII character in.
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII hexadecimal-digit character.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-digit-value"/>g_ascii_digit_value ()</title>
<indexterm><primary>g_ascii_digit_value</primary></indexterm><programlisting><link linkend="gint">gint</link> g_ascii_digit_value (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines the numeric value of a character as a decimal
digit. Differs from <link linkend="g-unichar-digit-value"><function>g_unichar_digit_value()</function></link> because it takes
a char, so there's no worry about sign extension if characters
are signed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara> an ASCII character.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> If <parameter>c</parameter> is a decimal digit (according to
<link linkend="g-ascii-isdigit"><function>g_ascii_isdigit()</function></link>), its numeric value. Otherwise, -1.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-xdigit-value"/>g_ascii_xdigit_value ()</title>
<indexterm><primary>g_ascii_xdigit_value</primary></indexterm><programlisting><link linkend="gint">gint</link> g_ascii_xdigit_value (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Determines the numeric value of a character as a hexidecimal
digit. Differs from <link linkend="g-unichar-xdigit-value"><function>g_unichar_xdigit_value()</function></link> because it takes
a char, so there's no worry about sign extension if characters
are signed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara> an ASCII character.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> If <parameter>c</parameter> is a hex digit (according to
<link linkend="g-ascii-isxdigit"><function>g_ascii_isxdigit()</function></link>), its numeric value. Otherwise, -1.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-strcasecmp"/>g_ascii_strcasecmp ()</title>
<indexterm><primary>g_ascii_strcasecmp</primary></indexterm><programlisting><link linkend="gint">gint</link> g_ascii_strcasecmp (const <link linkend="gchar">gchar</link> *s1,
const <link linkend="gchar">gchar</link> *s2);</programlisting>
<para>
Compare two strings, ignoring the case of ASCII characters.
</para>
<para>
Unlike the BSD <link linkend="strcasecmp"><function>strcasecmp()</function></link> function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
characters as if they are not letters.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>s1</parameter> :</term>
<listitem><simpara> string to compare with <parameter>s2</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>s2</parameter> :</term>
<listitem><simpara> string to compare with <parameter>s1</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> an integer less than, equal to, or greater than
zero if <parameter>s1</parameter> is found, respectively, to be less than,
to match, or to be greater than <parameter>s2</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-strncasecmp"/>g_ascii_strncasecmp ()</title>
<indexterm><primary>g_ascii_strncasecmp</primary></indexterm><programlisting><link linkend="gint">gint</link> g_ascii_strncasecmp (const <link linkend="gchar">gchar</link> *s1,
const <link linkend="gchar">gchar</link> *s2,
<link linkend="gsize">gsize</link> n);</programlisting>
<para>
Compare <parameter>s1</parameter> and <parameter>s2</parameter>, ignoring the case of ASCII characters and any
characters after the first <parameter>n</parameter> in each string.
</para>
<para>
Unlike the BSD <link linkend="strcasecmp"><function>strcasecmp()</function></link> function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
characters as if they are not letters.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>s1</parameter> :</term>
<listitem><simpara> string to compare with <parameter>s2</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>s2</parameter> :</term>
<listitem><simpara> string to compare with <parameter>s1</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n</parameter> :</term>
<listitem><simpara> number of characters to compare.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> an integer less than, equal to, or greater than zero
if the first <parameter>n</parameter> bytes of <parameter>s1</parameter> is found, respectively,
to be less than, to match, or to be greater than the
first <parameter>n</parameter> bytes of <parameter>s2</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-strup"/>g_ascii_strup ()</title>
<indexterm><primary>g_ascii_strup</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_ascii_strup (const <link linkend="gchar">gchar</link> *str,
<link linkend="gssize">gssize</link> len);</programlisting>
<para>
Converts all lower case ASCII letters to upper case ASCII letters.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter> :</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter> :</term>
<listitem><simpara> length of <parameter>str</parameter> in bytes, or -1 if <parameter>str</parameter> is nul-terminated.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string, with all the lower case
characters in <parameter>str</parameter> converted to upper case, with
semantics that exactly match <link linkend="g-ascii-toupper"><function>g_ascii_toupper()</function></link>. (Note
that this is unlike the old <link linkend="g-strup"><function>g_strup()</function></link>, which modified
the string in place.)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-strdown"/>g_ascii_strdown ()</title>
<indexterm><primary>g_ascii_strdown</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_ascii_strdown (const <link linkend="gchar">gchar</link> *str,
<link linkend="gssize">gssize</link> len);</programlisting>
<para>
Converts all upper case ASCII letters to lower case ASCII letters.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter> :</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter> :</term>
<listitem><simpara> length of <parameter>str</parameter> in bytes, or -1 if <parameter>str</parameter> is nul-terminated.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly-allocated string, with all the upper case
characters in <parameter>str</parameter> converted to lower case, with
semantics that exactly match <link linkend="g-ascii-tolower"><function>g_ascii_tolower()</function></link>. (Note
that this is unlike the old <link linkend="g-strdown"><function>g_strdown()</function></link>, which modified
the string in place.)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-tolower"/>g_ascii_tolower ()</title>
<indexterm><primary>g_ascii_tolower</primary></indexterm><programlisting><link linkend="gchar">gchar</link> g_ascii_tolower (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Convert a character to ASCII lower case.
</para>
<para>
Unlike the standard C library <link linkend="tolower"><function>tolower()</function></link> function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are lower case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
don't call it on <literal>EOF</literal> but no need to worry about casting to <link linkend="guchar"><type>guchar</type></link>
before passing a possibly non-ASCII character in.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara> any character.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the result of converting <parameter>c</parameter> to lower case.
If <parameter>c</parameter> is not an ASCII upper case letter,
<parameter>c</parameter> is returned unchanged.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-toupper"/>g_ascii_toupper ()</title>
<indexterm><primary>g_ascii_toupper</primary></indexterm><programlisting><link linkend="gchar">gchar</link> g_ascii_toupper (<link linkend="gchar">gchar</link> c);</programlisting>
<para>
Convert a character to ASCII upper case.
</para>
<para>
Unlike the standard C library <link linkend="toupper"><function>toupper()</function></link> function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are upper case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
don't call it on <literal>EOF</literal> but no need to worry about casting to <link linkend="guchar"><type>guchar</type></link>
before passing a possibly non-ASCII character in.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>c</parameter> :</term>
<listitem><simpara> any character.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the result of converting <parameter>c</parameter> to upper case.
If <parameter>c</parameter> is not an ASCII lower case letter,
<parameter>c</parameter> is returned unchanged.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-ascii-up"/>g_string_ascii_up ()</title>
<indexterm><primary>g_string_ascii_up</primary></indexterm><programlisting><link linkend="GString">GString</link>* g_string_ascii_up (<link linkend="GString">GString</link> *string);</programlisting>
<para>
Converts all lower case ASCII letters to upper case ASCII letters.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> a GString
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> passed-in <parameter>string</parameter> pointer, with all the lower case
characters converted to upper case in place, with
semantics that exactly match g_ascii_toupper.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-string-ascii-down"/>g_string_ascii_down ()</title>
<indexterm><primary>g_string_ascii_down</primary></indexterm><programlisting><link linkend="GString">GString</link>* g_string_ascii_down (<link linkend="GString">GString</link> *string);</programlisting>
<para>
Converts all upper case ASCII letters to lower case ASCII letters.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> a GString
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> passed-in <parameter>string</parameter> pointer, with all the upper case
characters converted to lower case in place, with
semantics that exactly match g_ascii_tolower.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strup"/>g_strup ()</title>
<indexterm role="deprecated"><primary>g_strup</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strup (<link linkend="gchar">gchar</link> *string);</programlisting>
<warning><para><literal>g_strup</literal> is deprecated and should not be used in newly-written code. This function is totally broken for the reasons discussed in
the <link linkend="g-strncasecmp"><function>g_strncasecmp()</function></link> docs - use <link linkend="g-ascii-strup"><function>g_ascii_strup()</function></link> or <link linkend="g-utf8-strup"><function>g_utf8_strup()</function></link> instead.</para></warning>
<para>
Converts a string to upper case.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> the string to convert.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the string
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strdown"/>g_strdown ()</title>
<indexterm role="deprecated"><primary>g_strdown</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strdown (<link linkend="gchar">gchar</link> *string);</programlisting>
<warning><para><literal>g_strdown</literal> is deprecated and should not be used in newly-written code. This function is totally broken for the reasons discussed in
the <link linkend="g-strncasecmp"><function>g_strncasecmp()</function></link> docs - use <link linkend="g-ascii-strdown"><function>g_ascii_strdown()</function></link> or <link linkend="g-utf8-strdown"><function>g_utf8_strdown()</function></link>
instead.</para></warning>
<para>
Converts a string to lower case.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> the string to convert.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the string
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strcasecmp"/>g_strcasecmp ()</title>
<indexterm role="deprecated"><primary>g_strcasecmp</primary></indexterm><programlisting><link linkend="gint">gint</link> g_strcasecmp (const <link linkend="gchar">gchar</link> *s1,
const <link linkend="gchar">gchar</link> *s2);</programlisting>
<warning><para><literal>g_strcasecmp</literal> is deprecated and should not be used in newly-written code. See <link linkend="g-strncasecmp"><function>g_strncasecmp()</function></link> for a discussion of why this function is
deprecated and how to replace it.</para></warning>
<para>
A case-insensitive string comparison, corresponding to the standard
<link linkend="strcasecmp"><function>strcasecmp()</function></link> function on platforms which support it.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>s1</parameter> :</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>s2</parameter> :</term>
<listitem><simpara> a string to compare with <parameter>s1</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 if the strings match, a negative value if <parameter>s1</parameter> < <parameter>s2</parameter>,
or a positive value if <parameter>s1</parameter> > <parameter>s2</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strncasecmp"/>g_strncasecmp ()</title>
<indexterm role="deprecated"><primary>g_strncasecmp</primary></indexterm><programlisting><link linkend="gint">gint</link> g_strncasecmp (const <link linkend="gchar">gchar</link> *s1,
const <link linkend="gchar">gchar</link> *s2,
<link linkend="guint">guint</link> n);</programlisting>
<warning><para><literal>g_strncasecmp</literal> is deprecated and should not be used in newly-written code. The problem with <link linkend="g-strncasecmp"><function>g_strncasecmp()</function></link> is that it does the
comparison by calling <link linkend="toupper"><function>toupper()</function></link>/<link linkend="tolower"><function>tolower()</function></link>. These functions are
locale-specific and operate on single bytes. However, it is impossible
to handle things correctly from an I18N standpoint by operating on
bytes, since characters may be multibyte. Thus <link linkend="g-strncasecmp"><function>g_strncasecmp()</function></link> is
broken if your string is guaranteed to be ASCII, since it's
locale-sensitive, and it's broken if your string is localized, since
it doesn't work on many encodings at all, including UTF-8, EUC-JP,
etc.
</para>
<para>
There are therefore two replacement functions: <link linkend="g-ascii-strncasecmp"><function>g_ascii_strncasecmp()</function></link>,
which only works on ASCII and is not locale-sensitive, and
<link linkend="g-utf8-casefold"><function>g_utf8_casefold()</function></link>, which is good for case-insensitive sorting of UTF-8.</para></warning>
<para>
A case-insensitive string comparison, corresponding to the standard
<link linkend="strncasecmp"><function>strncasecmp()</function></link> function on platforms which support it.
It is similar to <link linkend="g-strcasecmp"><function>g_strcasecmp()</function></link> except it only compares the first <parameter>n</parameter>
characters of the strings.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>s1</parameter> :</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>s2</parameter> :</term>
<listitem><simpara> a string to compare with <parameter>s1</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n</parameter> :</term>
<listitem><simpara> the maximum number of characters to compare.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 if the strings match, a negative value if <parameter>s1</parameter> < <parameter>s2</parameter>,
or a positive value if <parameter>s1</parameter> > <parameter>s2</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strreverse"/>g_strreverse ()</title>
<indexterm><primary>g_strreverse</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strreverse (<link linkend="gchar">gchar</link> *string);</programlisting>
<para>
Reverses all of the bytes in a string.
For example, <literal>g_strreverse ("abcdef")</literal> will result in "fedcba".
</para>
<para>
Note that <link linkend="g-strreverse"><function>g_strreverse()</function></link> doesn't work on UTF-8 strings containing multibyte characters.
For that purpose, use <link linkend="g-utf8-strreverse"><function>g_utf8_strreverse()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>the string to reverse.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the same pointer passed in as <parameter>string</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-strtoull"/>g_ascii_strtoull ()</title>
<indexterm role="2.2"><primary>g_ascii_strtoull</primary></indexterm><programlisting><link linkend="guint64">guint64</link> g_ascii_strtoull (const <link linkend="gchar">gchar</link> *nptr,
<link linkend="gchar">gchar</link> **endptr,
<link linkend="guint">guint</link> base);</programlisting>
<para>
Converts a string to a <link linkend="guint64"><type>guint64</type></link> value.
This function behaves like the standard <link linkend="strtoull"><function>strtoull()</function></link> function
does in the C locale. It does this without actually
changing the current locale, since that would not be
thread-safe.
</para>
<para>
This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system <link linkend="strtoull"><function>strtoull()</function></link> function.
</para>
<para>
If the correct value would cause overflow, <literal>G_MAXUINT64</literal>
is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>nptr</parameter> :</term>
<listitem><simpara> the string to convert to a numeric value.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>endptr</parameter> :</term>
<listitem><simpara> if non-<literal>NULL</literal>, it returns the character after
the last character used in the conversion.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>base</parameter> :</term>
<listitem><simpara> to be used for the conversion, 2..36 or 0
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="guint64"><type>guint64</type></link> value.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.2
</para></refsect2>
<refsect2>
<title><anchor id="G-ASCII-DTOSTR-BUF-SIZE-CAPS"/>G_ASCII_DTOSTR_BUF_SIZE</title>
<indexterm><primary>G_ASCII_DTOSTR_BUF_SIZE</primary></indexterm><programlisting>#define G_ASCII_DTOSTR_BUF_SIZE (29 + 10)
</programlisting>
<para>
A good size for a buffer to be passed into <link linkend="g-ascii-dtostr"><function>g_ascii_dtostr()</function></link>.
It is guaranteed to be enough for all output of that function on systems with
64bit IEEE-compatible doubles.
</para>
<para>
The typical usage would be something like:
<informalexample><programlisting>
char buf[G_ASCII_DTOSTR_BUF_SIZE];
fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
</programlisting></informalexample>
</para></refsect2>
<refsect2>
<title><anchor id="g-ascii-strtod"/>g_ascii_strtod ()</title>
<indexterm><primary>g_ascii_strtod</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link> g_ascii_strtod (const <link linkend="gchar">gchar</link> *nptr,
<link linkend="gchar">gchar</link> **endptr);</programlisting>
<para>
Converts a string to a <link linkend="gdouble"><type>gdouble</type></link> value.
This function behaves like the standard <link linkend="strtod"><function>strtod()</function></link> function
does in the C locale. It does this without actually
changing the current locale, since that would not be
thread-safe.
</para>
<para>
This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system <link linkend="strtod"><function>strtod()</function></link> function.
</para>
<para>
To convert from a <link linkend="gdouble"><type>gdouble</type></link> to a string in a locale-insensitive
way, use <link linkend="g-ascii-dtostr"><function>g_ascii_dtostr()</function></link>.
</para>
<para>
If the correct value would cause overflow, plus or minus <literal>HUGE_VAL</literal>
is returned (according to the sign of the value), and <literal>ERANGE</literal> is
stored in <literal>errno</literal>. If the correct value would cause underflow,
zero is returned and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
</para>
<para>
This function resets <literal>errno</literal> before calling <link linkend="strtod"><function>strtod()</function></link> so that
you can reliably detect overflow and underflow.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>nptr</parameter> :</term>
<listitem><simpara> the string to convert to a numeric value.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>endptr</parameter> :</term>
<listitem><simpara> if non-<literal>NULL</literal>, it returns the character after
the last character used in the conversion.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="gdouble"><type>gdouble</type></link> value.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-dtostr"/>g_ascii_dtostr ()</title>
<indexterm><primary>g_ascii_dtostr</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_ascii_dtostr (<link linkend="gchar">gchar</link> *buffer,
<link linkend="gint">gint</link> buf_len,
<link linkend="gdouble">gdouble</link> d);</programlisting>
<para>
Converts a <link linkend="gdouble"><type>gdouble</type></link> to a string, using the '.' as
decimal point.
</para>
<para>
This functions generates enough precision that converting
the string back using <link linkend="g-ascii-strtod"><function>g_ascii_strtod()</function></link> gives the same machine-number
(on machines with IEEE compatible 64bit doubles). It is
guaranteed that the size of the resulting string will never
be larger than <parameter>G_ASCII_DTOSTR_BUF_SIZE</parameter> bytes.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>buffer</parameter> :</term>
<listitem><simpara> A buffer to place the resulting string in
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf_len</parameter> :</term>
<listitem><simpara> The length of the buffer.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>d</parameter> :</term>
<listitem><simpara> The <link linkend="gdouble"><type>gdouble</type></link> to convert
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The pointer to the buffer with the converted string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ascii-formatd"/>g_ascii_formatd ()</title>
<indexterm><primary>g_ascii_formatd</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_ascii_formatd (<link linkend="gchar">gchar</link> *buffer,
<link linkend="gint">gint</link> buf_len,
const <link linkend="gchar">gchar</link> *format,
<link linkend="gdouble">gdouble</link> d);</programlisting>
<para>
Converts a <link linkend="gdouble"><type>gdouble</type></link> to a string, using the '.' as
decimal point. To format the number you pass in
a <link linkend="printf"><function>printf()</function></link>-style format string. Allowed conversion
specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
</para>
<para>
If you just want to want to serialize the value into a
string, use <link linkend="g-ascii-dtostr"><function>g_ascii_dtostr()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>buffer</parameter> :</term>
<listitem><simpara> A buffer to place the resulting string in
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf_len</parameter> :</term>
<listitem><simpara> The length of the buffer.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara> The <link linkend="printf"><function>printf()</function></link>-style format to use for the
code to use for converting.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>d</parameter> :</term>
<listitem><simpara> The <link linkend="gdouble"><type>gdouble</type></link> to convert
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The pointer to the buffer with the converted string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strtod"/>g_strtod ()</title>
<indexterm><primary>g_strtod</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link> g_strtod (const <link linkend="gchar">gchar</link> *nptr,
<link linkend="gchar">gchar</link> **endptr);</programlisting>
<para>
Converts a string to a <link linkend="gdouble"><type>gdouble</type></link> value.
It calls the standard <link linkend="strtod"><function>strtod()</function></link> function to handle the conversion, but
if the string is not completely converted it attempts the conversion
again with <link linkend="g-ascii-strtod"><function>g_ascii_strtod()</function></link>, and returns the best match.
</para>
<para>
This function should seldomly be used. The normal situation when reading
numbers not for human consumption is to use <link linkend="g-ascii-strtod"><function>g_ascii_strtod()</function></link>. Only when
you know that you must expect both locale formatted and C formatted numbers
should you use this. Make sure that you don't pass strings such as comma
separated lists of values, since the commas may be interpreted as a decimal
point in some locales, causing unexpected results.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>nptr</parameter> :</term>
<listitem><simpara> the string to convert to a numeric value.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>endptr</parameter> :</term>
<listitem><simpara> if non-<literal>NULL</literal>, it returns the character after
the last character used in the conversion.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="gdouble"><type>gdouble</type></link> value.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strchug"/>g_strchug ()</title>
<indexterm><primary>g_strchug</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strchug (<link linkend="gchar">gchar</link> *string);</programlisting>
<para>
Removes leading whitespace from a string, by moving the rest of the
characters forward.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a string to remove the leading whitespace from.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><parameter>string</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strchomp"/>g_strchomp ()</title>
<indexterm><primary>g_strchomp</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strchomp (<link linkend="gchar">gchar</link> *string);</programlisting>
<para>
Removes trailing whitespace from a string.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a string to remove the trailing whitespace from.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><parameter>string</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strstrip"/>g_strstrip()</title>
<indexterm><primary>g_strstrip</primary></indexterm><programlisting>#define g_strstrip( string )</programlisting>
<para>
Removes leading and trailing whitespace from a string.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a string to remove the leading and trailing whitespace from.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strdelimit"/>g_strdelimit ()</title>
<indexterm><primary>g_strdelimit</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strdelimit (<link linkend="gchar">gchar</link> *string,
const <link linkend="gchar">gchar</link> *delimiters,
<link linkend="gchar">gchar</link> new_delimiter);</programlisting>
<para>
Converts any delimiter characters in <parameter>string</parameter> to <parameter>new_delimiter</parameter>.
Any characters in <parameter>string</parameter> which are found in <parameter>delimiters</parameter> are changed
to the <parameter>new_delimiter</parameter> character. Modifies <parameter>string</parameter> in place, and returns
<parameter>string</parameter> itself, not a copy. The return value is to allow nesting such as
<literal>g_ascii_strup (g_strdelimit (str, "abc", '?'))</literal>.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>the string to convert.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>delimiters</parameter> :</term>
<listitem><simpara>a string containing the current delimiters, or <literal>NULL</literal> to use the
standard delimiters defined in <link linkend="G-STR-DELIMITERS-CAPS"><type>G_STR_DELIMITERS</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>new_delimiter</parameter> :</term>
<listitem><simpara>the new delimiter 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-STR-DELIMITERS-CAPS"/>G_STR_DELIMITERS</title>
<indexterm><primary>G_STR_DELIMITERS</primary></indexterm><programlisting>#define G_STR_DELIMITERS "_-|> <."
</programlisting>
<para>
The standard delimiters, used in <link linkend="g-strdelimit"><function>g_strdelimit()</function></link>.
</para></refsect2>
<refsect2>
<title><anchor id="g-strescape"/>g_strescape ()</title>
<indexterm><primary>g_strescape</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strescape (const <link linkend="gchar">gchar</link> *source,
const <link linkend="gchar">gchar</link> *exceptions);</programlisting>
<para>
Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\' and
'"' in the string <parameter>source</parameter> by inserting a '\' before
them. Additionally all characters in the range 0x01-0x1F (everything
below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
replaced with a '\' followed by their octal representation. Characters
supplied in <parameter>exceptions</parameter> are not escaped.
</para>
<para>
<link linkend="g-strcompress"><function>g_strcompress()</function></link> does the reverse conversion.
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara>a string to escape.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>exceptions</parameter> :</term>
<listitem><simpara>a string of characters not to escape in <parameter>source</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a newly-allocated copy of <parameter>source</parameter> with certain
characters escaped. See above.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strcompress"/>g_strcompress ()</title>
<indexterm><primary>g_strcompress</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strcompress (const <link linkend="gchar">gchar</link> *source);</programlisting>
<para>
Replaces all escaped characters with their one byte equivalent. It
does the reverse conversion of <link linkend="g-strescape"><function>g_strescape()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>source</parameter> :</term>
<listitem><simpara>a string to compress.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a newly-allocated copy of <parameter>source</parameter> with all escaped
character compressed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strcanon"/>g_strcanon ()</title>
<indexterm><primary>g_strcanon</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strcanon (<link linkend="gchar">gchar</link> *string,
const <link linkend="gchar">gchar</link> *valid_chars,
<link linkend="gchar">gchar</link> substitutor);</programlisting>
<para>
For each character in <parameter>string</parameter>, if the character is not in <parameter>valid_chars</parameter>,
replaces the character with <parameter>substitutor</parameter>. Modifies <parameter>string</parameter> in place,
and return <parameter>string</parameter> itself, not a copy. The return value is to allow
nesting such as <literal>g_ascii_strup (g_strcanon (str, "abc", '?'))</literal>.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara>a nul-terminated array of bytes.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>valid_chars</parameter> :</term>
<listitem><simpara>bytes permitted in <parameter>string</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>substitutor</parameter> :</term>
<listitem><simpara>replacement character for disallowed bytes.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><parameter>string</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strsplit"/>g_strsplit ()</title>
<indexterm><primary>g_strsplit</primary></indexterm><programlisting><link linkend="gchar">gchar</link>** g_strsplit (const <link linkend="gchar">gchar</link> *string,
const <link linkend="gchar">gchar</link> *delimiter,
<link linkend="gint">gint</link> max_tokens);</programlisting>
<para>
Splits a string into a maximum of <parameter>max_tokens</parameter> pieces, using the given
<parameter>delimiter</parameter>. If <parameter>max_tokens</parameter> is reached, the remainder of <parameter>string</parameter> is appended
to the last token.
</para>
<para>
As a special case, the result of splitting the empty string "" is an empty
vector, not a vector containing a single string. The reason for this
special case is that being able to represent a empty vector is typically
more useful than consistent handling of empty elements. If you do need
to represent empty elements, you'll need to check for the empty string
before calling <link linkend="g-strsplit"><function>g_strsplit()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> a string to split.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>delimiter</parameter> :</term>
<listitem><simpara> a string which specifies the places at which to split the string.
The delimiter is not included in any of the resulting strings, unless
<parameter>max_tokens</parameter> is reached.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max_tokens</parameter> :</term>
<listitem><simpara> the maximum number of pieces to split <parameter>string</parameter> into. If this is
less than 1, the string is split completely.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly-allocated <literal>NULL</literal>-terminated array of strings. Use
<link linkend="g-strfreev"><function>g_strfreev()</function></link> to free it.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strsplit-set"/>g_strsplit_set ()</title>
<indexterm role="2.4"><primary>g_strsplit_set</primary></indexterm><programlisting><link linkend="gchar">gchar</link>** g_strsplit_set (const <link linkend="gchar">gchar</link> *string,
const <link linkend="gchar">gchar</link> *delimiters,
<link linkend="gint">gint</link> max_tokens);</programlisting>
<para>
Splits <parameter>string</parameter> into a number of tokens not containing any of the characters
in <parameter>delimiter</parameter>. A token is the (possibly empty) longest string that does not
contain any of the characters in <parameter>delimiters</parameter>. If <parameter>max_tokens</parameter> is reached, the
remainder is appended to the last token.
</para>
<para>
For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
<literal>NULL</literal>-terminated vector containing the three strings "abc", "def",
and "ghi".
</para>
<para>
The result if g_strsplit_set (":def/ghi:", ":/", -1) is a <literal>NULL</literal>-terminated
vector containing the four strings "", "def", "ghi", and "".
</para>
<para>
As a special case, the result of splitting the empty string "" is an empty
vector, not a vector containing a single string. The reason for this
special case is that being able to represent a empty vector is typically
more useful than consistent handling of empty elements. If you do need
to represent empty elements, you'll need to check for the empty string
before calling <link linkend="g-strsplit"><function>g_strsplit()</function></link>.
</para>
<para>
Note that this function works on bytes not characters, so it can't be used
to delimit UTF-8 strings for anything but ASCII characters.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter> :</term>
<listitem><simpara> The string to be tokenized
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>delimiters</parameter> :</term>
<listitem><simpara> A nul-terminated string containing bytes that are used
to split the string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max_tokens</parameter> :</term>
<listitem><simpara> The maximum number of tokens to split <parameter>string</parameter> into.
If this is less than 1, the string is split completely
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly-allocated <literal>NULL</literal>-terminated array of strings. Use
<link linkend="g-strfreev"><function>g_strfreev()</function></link> to free it.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
<refsect2>
<title><anchor id="g-strfreev"/>g_strfreev ()</title>
<indexterm><primary>g_strfreev</primary></indexterm><programlisting><link linkend="void">void</link> g_strfreev (<link linkend="gchar">gchar</link> **str_array);</programlisting>
<para>
Frees a <literal>NULL</literal>-terminated array of strings, and the array itself.
If called on a <literal>NULL</literal> value, <link linkend="g-strfreev"><function>g_strfreev()</function></link> simply returns.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str_array</parameter> :</term>
<listitem><simpara> a <literal>NULL</literal>-terminated array of strings to free.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strconcat"/>g_strconcat ()</title>
<indexterm><primary>g_strconcat</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strconcat (const <link linkend="gchar">gchar</link> *string1,
...);</programlisting>
<para>
Concatenates all of the given strings into one long string. The returned string
should be freed when no longer needed.
</para>
<warning><para>
The variable argument list <emphasis>must</emphasis> end with <literal>NULL</literal>.
If you forget the <literal>NULL</literal>, <link linkend="g-strconcat"><function>g_strconcat()</function></link> will start appending
random memory junk to your string.
</para></warning><variablelist role="params">
<varlistentry><term><parameter>string1</parameter> :</term>
<listitem><simpara>The first string to add, which must not be <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara>a <literal>NULL</literal>-terminated list of strings to append to the string.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a newly-allocated string containing all the string arguments.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strjoin"/>g_strjoin ()</title>
<indexterm><primary>g_strjoin</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strjoin (const <link linkend="gchar">gchar</link> *separator,
...);</programlisting>
<para>
Joins a number of strings together to form one long string, with the optional
<parameter>separator</parameter> inserted between each of them.
</para><variablelist role="params">
<varlistentry><term><parameter>separator</parameter> :</term>
<listitem><simpara>a string to insert between each of the strings, or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara>a <literal>NULL</literal>-terminated list of strings to join.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a newly-allocated string containing all of the strings joined
together, with <parameter>separator</parameter> between them.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strjoinv"/>g_strjoinv ()</title>
<indexterm><primary>g_strjoinv</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strjoinv (const <link linkend="gchar">gchar</link> *separator,
<link linkend="gchar">gchar</link> **str_array);</programlisting>
<para>
Joins a number of strings together to form one long string, with the optional
<parameter>separator</parameter> inserted between each of them.
</para><variablelist role="params">
<varlistentry><term><parameter>separator</parameter> :</term>
<listitem><simpara>a string to insert between each of the strings, or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str_array</parameter> :</term>
<listitem><simpara>a <literal>NULL</literal>-terminated array of strings to join.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a newly-allocated string containing all of the strings joined
together, with <parameter>separator</parameter> between them.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strerror"/>g_strerror ()</title>
<indexterm><primary>g_strerror</primary></indexterm><programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_strerror (<link linkend="gint">gint</link> errnum);</programlisting>
<para>
Returns a string corresponding to the given error code, e.g. "no such process".
This function is included since not all platforms support the
<link linkend="strerror"><function>strerror()</function></link> function.
</para><variablelist role="params">
<varlistentry><term><parameter>errnum</parameter> :</term>
<listitem><simpara>the system error number. See the standard C <literal>errno</literal>
documentation.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a string describing the error code.
If the error code is unknown, it returns "unknown error (<code>)".
The string can only be used until the next call to <link linkend="g-strerror"><function>g_strerror()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-strsignal"/>g_strsignal ()</title>
<indexterm><primary>g_strsignal</primary></indexterm><programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_strsignal (<link linkend="gint">gint</link> signum);</programlisting>
<para>
Returns a string describing the given signal, e.g. "Segmentation fault".
This function is included since not all platforms support the
<link linkend="strsignal"><function>strsignal()</function></link> function.
</para><variablelist role="params">
<varlistentry><term><parameter>signum</parameter> :</term>
<listitem><simpara>the signal number. See the <literal>signal</literal>
documentation.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a string describing the signal.
If the signal is unknown, it returns "unknown signal (<signum>)".
The string can only be used until the next call to <link linkend="g-strsignal"><function>g_strsignal()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
</refentry>