<refentry id="glib-String-Utility-Functions">
<refmeta>
<refentrytitle role="top_of_page" id="glib-String-Utility-Functions.top_of_page">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 id="glib-String-Utility-Functions.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;
#include &lt;glib/gprintf.h&gt;

<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="int">int</link>                 <link linkend="g-strcmp0">g_strcmp0</link>                           (const <link linkend="char">char</link> *str1,
                                                         const <link linkend="char">char</link> *str2);

<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="gint64">gint64</link>              <link linkend="g-ascii-strtoll">g_ascii_strtoll</link>                     (const <link linkend="gchar">gchar</link> *nptr,
                                                         <link linkend="gchar">gchar</link> **endptr,
                                                         <link linkend="guint">guint</link> base);
<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);
<link linkend="guint">guint</link>               <link linkend="g-strv-length">g_strv_length</link>                       (<link linkend="gchar">gchar</link> **str_array);

const <link linkend="gchar">gchar</link>*        <link linkend="g-strerror">g_strerror</link>                          (<link linkend="gint">gint</link> errnum);
const <link linkend="gchar">gchar</link>*        <link linkend="g-strsignal">g_strsignal</link>                         (<link linkend="gint">gint</link> signum);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-String-Utility-Functions.description" role="desc">
<title role="desc.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>&lt;glib/gprintf.h&gt;</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>&percnt;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>&percnt;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>&percnt;Ns</literal>.
If your intention is to format strings for a certain number of columns, then
<literal>&percnt;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 id="glib-String-Utility-Functions.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="g-strdup" role="function">
<title>g_strdup ()</title>
<indexterm zone="g-strdup"><primary sortas="strdup">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 <link linkend="NULL--CAPS"><literal>NULL</literal></link> it returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
The returned string should be freed with <link linkend="g-free"><function>g_free()</function></link> 
when no longer needed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter>&#160;:</term>
<listitem><simpara> the string to duplicate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated copy of <parameter>str</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strndup" role="function">
<title>g_strndup ()</title>
<indexterm zone="g-strndup"><primary sortas="strndup">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> bytes of a string, returning a newly-allocated
buffer <parameter>n</parameter> + 1 bytes long which will always be nul-terminated.
If <parameter>str</parameter> is less than <parameter>n</parameter> bytes long the buffer is padded with nuls.
If <parameter>str</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link> it returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
The returned value should be freed when no longer needed.
</para>
<para>
<note><para>
To copy a number of characters from a UTF-8 encoded string, use
<link linkend="g-utf8-strncpy"><function>g_utf8_strncpy()</function></link> instead.
</para></note></para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter>&#160;:</term>
<listitem><simpara> the string to duplicate
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n</parameter>&#160;:</term>
<listitem><simpara> the maximum number of bytes to copy from <parameter>str</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated buffer containing the first <parameter>n</parameter> bytes 
         of <parameter>str</parameter>, nul-terminated 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strdupv" role="function">
<title>g_strdupv ()</title>
<indexterm zone="g-strdupv"><primary sortas="strdupv">g_strdupv</primary></indexterm><programlisting><link linkend="gchar">gchar</link>**             g_strdupv                           (<link linkend="gchar">gchar</link> **str_array);</programlisting>
<para>
Copies <link linkend="NULL--CAPS"><literal>NULL</literal></link>-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 <link linkend="NULL--CAPS"><literal>NULL</literal></link> value, <link linkend="g-strdupv"><function>g_strdupv()</function></link> simply returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str_array</parameter>&#160;:</term>
<listitem><simpara> <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strnfill" role="function">
<title>g_strnfill ()</title>
<indexterm zone="g-strnfill"><primary sortas="strnfill">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> bytes long filled with <parameter>fill_char</parameter>.
The returned string should be freed when no longer needed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara> the length of the new string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fill_char</parameter>&#160;:</term>
<listitem><simpara> the byte to fill the string with
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string filled the <parameter>fill_char</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-stpcpy" role="function">
<title>g_stpcpy ()</title>
<indexterm zone="g-stpcpy"><primary sortas="stpcpy">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>&#160;:</term>
<listitem><simpara> destination buffer.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>src</parameter>&#160;:</term>
<listitem><simpara> source string.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a pointer to trailing nul byte.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strstr-len" role="function">
<title>g_strstr_len ()</title>
<indexterm zone="g-strstr-len"><primary sortas="strstr_len">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>&#160;:</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>haystack_len</parameter>&#160;:</term>
<listitem><simpara> the maximum length of <parameter>haystack</parameter>. Note that -1 is
a valid length, if <parameter>haystack</parameter> is nul-terminated, meaning it will
search through the whole string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>needle</parameter>&#160;:</term>
<listitem><simpara> the string to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a pointer to the found occurrence, or
   <link linkend="NULL--CAPS"><literal>NULL</literal></link> if not found.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strrstr" role="function">
<title>g_strrstr ()</title>
<indexterm zone="g-strrstr"><primary sortas="strrstr">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>&#160;:</term>
<listitem><simpara> a nul-terminated string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>needle</parameter>&#160;:</term>
<listitem><simpara> the nul-terminated string to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a pointer to the found occurrence, or
   <link linkend="NULL--CAPS"><literal>NULL</literal></link> if not found.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strrstr-len" role="function">
<title>g_strrstr_len ()</title>
<indexterm zone="g-strrstr-len"><primary sortas="strrstr_len">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>&#160;:</term>
<listitem><simpara> a nul-terminated string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>haystack_len</parameter>&#160;:</term>
<listitem><simpara> the maximum length of <parameter>haystack</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>needle</parameter>&#160;:</term>
<listitem><simpara> the nul-terminated string to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a pointer to the found occurrence, or
   <link linkend="NULL--CAPS"><literal>NULL</literal></link> if not found.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-str-has-prefix" role="function" condition="since:2.2">
<title>g_str_has_prefix ()</title>
<indexterm zone="g-str-has-prefix" role="2.2"><primary sortas="str_has_prefix">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>&#160;:</term>
<listitem><simpara> a nul-terminated string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>prefix</parameter>&#160;:</term>
<listitem><simpara> the nul-terminated prefix to look for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter> begins with <parameter>prefix</parameter>, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="g-str-has-suffix" role="function" condition="since:2.2">
<title>g_str_has_suffix ()</title>
<indexterm zone="g-str-has-suffix" role="2.2"><primary sortas="str_has_suffix">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>&#160;:</term>
<listitem><simpara> a nul-terminated string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>suffix</parameter>&#160;:</term>
<listitem><simpara> the nul-terminated suffix to look for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter> end with <parameter>suffix</parameter>, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="g-strcmp0" role="function" condition="since:2.16">
<title>g_strcmp0 ()</title>
<indexterm zone="g-strcmp0" role="2.16"><primary sortas="strcmp0">g_strcmp0</primary></indexterm><programlisting><link linkend="int">int</link>                 g_strcmp0                           (const <link linkend="char">char</link> *str1,
                                                         const <link linkend="char">char</link> *str2);</programlisting>
<para>
Compares <parameter>str1</parameter> and <parameter>str2</parameter> like <link linkend="strcmp"><function>strcmp()</function></link>. Handles <link linkend="NULL--CAPS"><literal>NULL</literal></link> 
gracefully by sorting it before non-<link linkend="NULL--CAPS"><literal>NULL</literal></link> strings.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str1</parameter>&#160;:</term>
<listitem><simpara> a C string or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str2</parameter>&#160;:</term>
<listitem><simpara> another C string or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> -1, 0 or 1, if <parameter>str1</parameter> is &lt;, == or &gt; than <parameter>str2</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-strlcpy" role="function">
<title>g_strlcpy ()</title>
<indexterm zone="g-strlcpy"><primary sortas="strlcpy">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. 
</para>
<para>
At most dest_size - 1 characters will be copied. Always nul-terminates
(unless dest_size == 0). This function does <emphasis>not</emphasis> 
allocate memory. Unlike <link linkend="strncpy"><function>strncpy()</function></link>, this function doesn't pad dest (so 
it's often faster). It returns the size of the attempted result, 
strlen (src), so if <parameter>retval</parameter> &gt;= <parameter>dest_size</parameter>, truncation occurred.
</para>
<para>
<note><para>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></note></para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>dest</parameter>&#160;:</term>
<listitem><simpara> destination buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>src</parameter>&#160;:</term>
<listitem><simpara> source buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dest_size</parameter>&#160;:</term>
<listitem><simpara> length of <parameter>dest</parameter> in bytes
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> length of <parameter>src</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strlcat" role="function">
<title>g_strlcat ()</title>
<indexterm zone="g-strlcat"><primary sortas="strlcat">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>. 
</para>
<para>
At most dest_size - 1 characters will be copied.
Unlike strncat, dest_size is the full size of dest, not the space left over.
This function does NOT allocate memory.
This always NUL terminates (unless siz == 0 or there were no NUL characters
in the dest_size characters of dest to start with).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>dest</parameter>&#160;:</term>
<listitem><simpara> destination buffer, already containing one nul-terminated string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>src</parameter>&#160;:</term>
<listitem><simpara> source buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dest_size</parameter>&#160;:</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>&#160;:</term><listitem><simpara>size of attempted result, which is
MIN (dest_size, strlen (original dest)) + strlen (src),
so if retval &gt;= dest_size, truncation occurred.

<note><para>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></note>

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strdup-printf" role="function">
<title>g_strdup_printf ()</title>
<indexterm zone="g-strdup-printf"><primary sortas="strdup_printf">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 with <link linkend="g-free"><function>g_free()</function></link> when no 
longer needed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> the parameters to insert into the format string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string holding the result
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strdup-vprintf" role="function">
<title>g_strdup_vprintf ()</title>
<indexterm zone="g-strdup-vprintf"><primary sortas="strdup_vprintf">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 with <link linkend="g-free"><function>g_free()</function></link> 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>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> the list of parameters to insert into the format string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string holding the result
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-printf" role="function" condition="since:2.2">
<title>g_printf ()</title>
<indexterm zone="g-printf" role="2.2"><primary sortas="printf">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>&#160;:</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>&#160;:</term>
<listitem><simpara> the arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="g-vprintf" role="function" condition="since:2.2">
<title>g_vprintf ()</title>
<indexterm zone="g-vprintf" role="2.2"><primary sortas="vprintf">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>&#160;:</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>&#160;:</term>
<listitem><simpara> the list of arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="g-fprintf" role="function" condition="since:2.2">
<title>g_fprintf ()</title>
<indexterm zone="g-fprintf" role="2.2"><primary sortas="fprintf">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>&#160;:</term>
<listitem><simpara> the stream to write to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> the arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="g-vfprintf" role="function" condition="since:2.2">
<title>g_vfprintf ()</title>
<indexterm zone="g-vfprintf" role="2.2"><primary sortas="vfprintf">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>&#160;:</term>
<listitem><simpara> the stream to write to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> the list of arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="g-sprintf" role="function" condition="since:2.2">
<title>g_sprintf ()</title>
<indexterm zone="g-sprintf" role="2.2"><primary sortas="sprintf">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>&#160;:</term>
<listitem><simpara> A pointer to a memory buffer to contain the resulting string. It 
         is up to the caller to ensure that the allocated buffer is large 
         enough to hold the formatted result
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> the arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="g-vsprintf" role="function" condition="since:2.2">
<title>g_vsprintf ()</title>
<indexterm zone="g-vsprintf" role="2.2"><primary sortas="vsprintf">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>&#160;:</term>
<listitem><simpara> the buffer to hold the output.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> the list of arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="g-snprintf" role="function">
<title>g_snprintf ()</title>
<indexterm zone="g-snprintf"><primary sortas="snprintf">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>&#160;:</term>
<listitem><simpara> the buffer to hold the output.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n</parameter>&#160;:</term>
<listitem><simpara> the maximum number of bytes to produce (including the 
    terminating nul character).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> the arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes which would be produced if the buffer 
    was large enough.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-vsnprintf" role="function">
<title>g_vsnprintf ()</title>
<indexterm zone="g-vsnprintf"><primary sortas="vsnprintf">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>&#160;:</term>
<listitem><simpara> the buffer to hold the output.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n</parameter>&#160;:</term>
<listitem><simpara> the maximum number of bytes to produce (including the 
    terminating nul character).
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> the list of arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes which would be produced if the buffer 
 was large enough.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-vasprintf" role="function" condition="since:2.4">
<title>g_vasprintf ()</title>
<indexterm zone="g-vasprintf" role="2.4"><primary sortas="vasprintf">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>&#160;:</term>
<listitem><simpara> the return location for the newly-allocated string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> the list of arguments to insert in the output.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-printf-string-upper-bound" role="function">
<title>g_printf_string_upper_bound ()</title>
<indexterm zone="g-printf-string-upper-bound"><primary sortas="printf_string_upper_bound">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>&#160;:</term>
<listitem><simpara>the format string. See the <link linkend="printf"><function>printf()</function></link> documentation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter>&#160;:</term>
<listitem><simpara>the parameters to be inserted into the format string.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the maximum space needed to store the formatted string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-isalnum" role="function">
<title>g_ascii_isalnum ()</title>
<indexterm zone="g-ascii-isalnum"><primary sortas="ascii_isalnum">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
<link linkend="FALSE--CAPS"><literal>FALSE</literal></link> 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 <link linkend="EOF--CAPS"><literal>EOF</literal></link> 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>&#160;:</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII alphanumeric character
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-isalpha" role="function">
<title>g_ascii_isalpha ()</title>
<indexterm zone="g-ascii-isalpha"><primary sortas="ascii_isalpha">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
<link linkend="FALSE--CAPS"><literal>FALSE</literal></link> 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 <link linkend="EOF--CAPS"><literal>EOF</literal></link> 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>&#160;:</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII alphabetic character
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-iscntrl" role="function">
<title>g_ascii_iscntrl ()</title>
<indexterm zone="g-ascii-iscntrl"><primary sortas="ascii_iscntrl">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 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> 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 <link linkend="EOF--CAPS"><literal>EOF</literal></link> 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>&#160;:</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII control character.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-isdigit" role="function">
<title>g_ascii_isdigit ()</title>
<indexterm zone="g-ascii-isdigit"><primary sortas="ascii_isdigit">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 <link linkend="EOF--CAPS"><literal>EOF</literal></link> 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>&#160;:</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII digit.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-isgraph" role="function">
<title>g_ascii_isgraph ()</title>
<indexterm zone="g-ascii-isgraph"><primary sortas="ascii_isgraph">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 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> 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 <link linkend="EOF--CAPS"><literal>EOF</literal></link> 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>&#160;:</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII printing character other than space.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-islower" role="function">
<title>g_ascii_islower ()</title>
<indexterm zone="g-ascii-islower"><primary sortas="ascii_islower">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 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> 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 <link linkend="EOF--CAPS"><literal>EOF</literal></link> 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>&#160;:</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII lower case letter
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-isprint" role="function">
<title>g_ascii_isprint ()</title>
<indexterm zone="g-ascii-isprint"><primary sortas="ascii_isprint">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 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> 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 <link linkend="EOF--CAPS"><literal>EOF</literal></link> 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>&#160;:</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII printing character.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-ispunct" role="function">
<title>g_ascii_ispunct ()</title>
<indexterm zone="g-ascii-ispunct"><primary sortas="ascii_ispunct">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 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> 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 <link linkend="EOF--CAPS"><literal>EOF</literal></link> 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>&#160;:</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII punctuation character.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-isspace" role="function">
<title>g_ascii_isspace ()</title>
<indexterm zone="g-ascii-isspace"><primary sortas="ascii_isspace">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 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> 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 <link linkend="EOF--CAPS"><literal>EOF</literal></link> 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>&#160;:</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII white-space character
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-isupper" role="function">
<title>g_ascii_isupper ()</title>
<indexterm zone="g-ascii-isupper"><primary sortas="ascii_isupper">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 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> 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 <link linkend="EOF--CAPS"><literal>EOF</literal></link> 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>&#160;:</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII upper case letter
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-isxdigit" role="function">
<title>g_ascii_isxdigit ()</title>
<indexterm zone="g-ascii-isxdigit"><primary sortas="ascii_isxdigit">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 <link linkend="EOF--CAPS"><literal>EOF</literal></link> 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>&#160;:</term>
<listitem><simpara>any character
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII hexadecimal-digit character.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-digit-value" role="function">
<title>g_ascii_digit_value ()</title>
<indexterm zone="g-ascii-digit-value"><primary sortas="ascii_digit_value">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>&#160;:</term>
<listitem><simpara> an ASCII character.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</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 id="g-ascii-xdigit-value" role="function">
<title>g_ascii_xdigit_value ()</title>
<indexterm zone="g-ascii-xdigit-value"><primary sortas="ascii_xdigit_value">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>&#160;:</term>
<listitem><simpara> an ASCII character.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</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 id="g-ascii-strcasecmp" role="function">
<title>g_ascii_strcasecmp ()</title>
<indexterm zone="g-ascii-strcasecmp"><primary sortas="ascii_strcasecmp">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
bytes as if they are not letters.
</para>
<para>
This function should be used only on strings that are known to be
in encodings where the bytes corresponding to ASCII letters always
represent themselves. This includes UTF-8 and the ISO-8859-*
charsets, but not for instance double-byte encodings like the
Windows Codepage 932, where the trailing bytes of double-byte
characters include all ASCII letters. If you compare two CP932
strings using this function, you will get false matches.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>s1</parameter>&#160;:</term>
<listitem><simpara> string to compare with <parameter>s2</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>s2</parameter>&#160;:</term>
<listitem><simpara> string to compare with <parameter>s1</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> 0 if the strings match, a negative value if <parameter>s1</parameter> &lt; <parameter>s2</parameter>, 
  or a positive value if <parameter>s1</parameter> &gt; <parameter>s2</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-strncasecmp" role="function">
<title>g_ascii_strncasecmp ()</title>
<indexterm zone="g-ascii-strncasecmp"><primary sortas="ascii_strncasecmp">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>
The same warning as in <link linkend="g-ascii-strcasecmp"><function>g_ascii_strcasecmp()</function></link> applies: Use this
function only on strings known to be in encodings where bytes
corresponding to ASCII letters always represent themselves.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>s1</parameter>&#160;:</term>
<listitem><simpara> string to compare with <parameter>s2</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>s2</parameter>&#160;:</term>
<listitem><simpara> string to compare with <parameter>s1</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n</parameter>&#160;:</term>
<listitem><simpara>  number of characters to compare.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> 0 if the strings match, a negative value if <parameter>s1</parameter> &lt; <parameter>s2</parameter>, 
  or a positive value if <parameter>s1</parameter> &gt; <parameter>s2</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-strup" role="function">
<title>g_ascii_strup ()</title>
<indexterm zone="g-ascii-strup"><primary sortas="ascii_strup">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>&#160;:</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&#160;:</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>&#160;:</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 id="g-ascii-strdown" role="function">
<title>g_ascii_strdown ()</title>
<indexterm zone="g-ascii-strdown"><primary sortas="ascii_strdown">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>&#160;:</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&#160;:</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>&#160;:</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 id="g-ascii-tolower" role="function">
<title>g_ascii_tolower ()</title>
<indexterm zone="g-ascii-tolower"><primary sortas="ascii_tolower">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 <link linkend="EOF--CAPS"><literal>EOF</literal></link> 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>&#160;:</term>
<listitem><simpara> any character.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</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 id="g-ascii-toupper" role="function">
<title>g_ascii_toupper ()</title>
<indexterm zone="g-ascii-toupper"><primary sortas="ascii_toupper">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 <link linkend="EOF--CAPS"><literal>EOF</literal></link> 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>&#160;:</term>
<listitem><simpara> any character.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</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 id="g-string-ascii-up" role="function">
<title>g_string_ascii_up ()</title>
<indexterm zone="g-string-ascii-up"><primary sortas="string_ascii_up">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>&#160;:</term>
<listitem><simpara> a GString
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</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 <link linkend="g-ascii-toupper"><function>g_ascii_toupper()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-string-ascii-down" role="function">
<title>g_string_ascii_down ()</title>
<indexterm zone="g-string-ascii-down"><primary sortas="string_ascii_down">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>&#160;:</term>
<listitem><simpara> a GString
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</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 <link linkend="g-ascii-tolower"><function>g_ascii_tolower()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strup" role="function" condition="deprecated">
<title>g_strup ()</title>
<indexterm zone="g-strup" role="deprecated"><primary sortas="strup">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> has been deprecated since version 2.2 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>&#160;:</term>
<listitem><simpara> the string to convert.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the string

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strdown" role="function" condition="deprecated">
<title>g_strdown ()</title>
<indexterm zone="g-strdown" role="deprecated"><primary sortas="strdown">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> has been deprecated since version 2.2 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>&#160;:</term>
<listitem><simpara> the string to convert.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the string 

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strcasecmp" role="function" condition="deprecated">
<title>g_strcasecmp ()</title>
<indexterm zone="g-strcasecmp" role="deprecated"><primary sortas="strcasecmp">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> has been deprecated since version 2.2 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>&#160;:</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>s2</parameter>&#160;:</term>
<listitem><simpara> a string to compare with <parameter>s1</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> 0 if the strings match, a negative value if <parameter>s1</parameter> &lt; <parameter>s2</parameter>, 
  or a positive value if <parameter>s1</parameter> &gt; <parameter>s2</parameter>.

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strncasecmp" role="function" condition="deprecated">
<title>g_strncasecmp ()</title>
<indexterm zone="g-strncasecmp" role="deprecated"><primary sortas="strncasecmp">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> has been deprecated since version 2.2 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>&#160;:</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>s2</parameter>&#160;:</term>
<listitem><simpara> a string to compare with <parameter>s1</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n</parameter>&#160;:</term>
<listitem><simpara> the maximum number of characters to compare.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> 0 if the strings match, a negative value if <parameter>s1</parameter> &lt; <parameter>s2</parameter>, 
  or a positive value if <parameter>s1</parameter> &gt; <parameter>s2</parameter>.

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strreverse" role="function">
<title>g_strreverse ()</title>
<indexterm zone="g-strreverse"><primary sortas="strreverse">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>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara> the string to reverse 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the same pointer passed in as <parameter>string</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-strtoll" role="function" condition="since:2.12">
<title>g_ascii_strtoll ()</title>
<indexterm zone="g-ascii-strtoll" role="2.12"><primary sortas="ascii_strtoll">g_ascii_strtoll</primary></indexterm><programlisting><link linkend="gint64">gint64</link>              g_ascii_strtoll                     (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="gint64"><type>gint64</type></link> value.
This function behaves like the standard <link linkend="strtoll"><function>strtoll()</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="strtoll"><function>strtoll()</function></link> function.
</para>
<para>
If the correct value would cause overflow, <link linkend="G-MAXINT64--CAPS"><literal>G_MAXINT64</literal></link> or <link linkend="G-MININT64--CAPS"><literal>G_MININT64</literal></link>
is returned, and <link linkend="ERANGE--CAPS"><literal>ERANGE</literal></link> is stored in <link linkend="errno"><literal>errno</literal></link>.  If the base is
outside the valid range, zero is returned, and <link linkend="EINVAL--CAPS"><literal>EINVAL</literal></link> is stored
in <link linkend="errno"><literal>errno</literal></link>.  If the string conversion fails, zero is returned, and
<parameter>endptr</parameter> returns <parameter>nptr</parameter> (if <parameter>endptr</parameter> is non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>nptr</parameter>&#160;:</term>
<listitem><simpara>    the string to convert to a numeric value.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>endptr</parameter>&#160;:</term>
<listitem><simpara>  if non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, it returns the character after
          the last character used in the conversion.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>base</parameter>&#160;:</term>
<listitem><simpara>    to be used for the conversion, 2..36 or 0
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="gint64"><type>gint64</type></link> value or zero on error.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.12</para></refsect2>
<refsect2 id="g-ascii-strtoull" role="function" condition="since:2.2">
<title>g_ascii_strtoull ()</title>
<indexterm zone="g-ascii-strtoull" role="2.2"><primary sortas="ascii_strtoull">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, <link linkend="G-MAXUINT64--CAPS"><literal>G_MAXUINT64</literal></link>
is returned, and <link linkend="ERANGE--CAPS"><literal>ERANGE</literal></link> is stored in <link linkend="errno"><literal>errno</literal></link>.  If the base is
outside the valid range, zero is returned, and <link linkend="EINVAL--CAPS"><literal>EINVAL</literal></link> is stored
in <link linkend="errno"><literal>errno</literal></link>.  If the string conversion fails, zero is returned, and
<parameter>endptr</parameter> returns <parameter>nptr</parameter> (if <parameter>endptr</parameter> is non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>nptr</parameter>&#160;:</term>
<listitem><simpara>    the string to convert to a numeric value.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>endptr</parameter>&#160;:</term>
<listitem><simpara>  if non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, it returns the character after
          the last character used in the conversion.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>base</parameter>&#160;:</term>
<listitem><simpara>    to be used for the conversion, 2..36 or 0
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="guint64"><type>guint64</type></link> value or zero on error.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="G-ASCII-DTOSTR-BUF-SIZE--CAPS" role="macro">
<title>G_ASCII_DTOSTR_BUF_SIZE</title>
<indexterm zone="G-ASCII-DTOSTR-BUF-SIZE--CAPS"><primary sortas="ASCII_DTOSTR_BUF_SIZE">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=&percnt;s\n", g_ascii_dtostr (buf, sizeof (buf), value));
</programlisting></informalexample>
</para></refsect2>
<refsect2 id="g-ascii-strtod" role="function">
<title>g_ascii_strtod ()</title>
<indexterm zone="g-ascii-strtod"><primary sortas="ascii_strtod">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.
</para>
<para>
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. 
A limitation of the implementation is that this function
will still accept localized versions of infinities and NANs. 
</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 <link linkend="HUGE-VAL--CAPS"><literal>HUGE_VAL</literal></link>
is returned (according to the sign of the value), and <link linkend="ERANGE--CAPS"><literal>ERANGE</literal></link> is
stored in <link linkend="errno"><literal>errno</literal></link>. If the correct value would cause underflow,
zero is returned and <link linkend="ERANGE--CAPS"><literal>ERANGE</literal></link> is stored in <link linkend="errno"><literal>errno</literal></link>.
</para>
<para>
This function resets <link linkend="errno"><literal>errno</literal></link> 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>&#160;:</term>
<listitem><simpara>    the string to convert to a numeric value.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>endptr</parameter>&#160;:</term>
<listitem><simpara>  if non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, it returns the character after
          the last character used in the conversion.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="gdouble"><type>gdouble</type></link> value.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-dtostr" role="function">
<title>g_ascii_dtostr ()</title>
<indexterm zone="g-ascii-dtostr"><primary sortas="ascii_dtostr">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>&#160;:</term>
<listitem><simpara> A buffer to place the resulting string in
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf_len</parameter>&#160;:</term>
<listitem><simpara> The length of the buffer.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>d</parameter>&#160;:</term>
<listitem><simpara> The <link linkend="gdouble"><type>gdouble</type></link> to convert
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The pointer to the buffer with the converted string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ascii-formatd" role="function">
<title>g_ascii_formatd ()</title>
<indexterm zone="g-ascii-formatd"><primary sortas="ascii_formatd">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>&#160;:</term>
<listitem><simpara> A buffer to place the resulting string in
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf_len</parameter>&#160;:</term>
<listitem><simpara> The length of the buffer.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&#160;:</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>&#160;:</term>
<listitem><simpara> The <link linkend="gdouble"><type>gdouble</type></link> to convert
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The pointer to the buffer with the converted string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strtod" role="function">
<title>g_strtod ()</title>
<indexterm zone="g-strtod"><primary sortas="strtod">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>&#160;:</term>
<listitem><simpara>    the string to convert to a numeric value.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>endptr</parameter>&#160;:</term>
<listitem><simpara>  if non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, it returns the character after
          the last character used in the conversion.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="gdouble"><type>gdouble</type></link> value.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strchug" role="function">
<title>g_strchug ()</title>
<indexterm zone="g-strchug"><primary sortas="strchug">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>
<para>
This function doesn't allocate or reallocate any memory; it modifies <parameter>string</parameter>
in place. The pointer to <parameter>string</parameter> is returned to allow the nesting of functions.
</para>
<para>
Also see <link linkend="g-strchomp"><function>g_strchomp()</function></link> and <link linkend="g-strstrip"><function>g_strstrip()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara>a string to remove the leading whitespace from.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>@string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strchomp" role="function">
<title>g_strchomp ()</title>
<indexterm zone="g-strchomp"><primary sortas="strchomp">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>
<para>
This function doesn't allocate or reallocate any memory; it modifies <parameter>string</parameter> in
place. The pointer to <parameter>string</parameter> is returned to allow the nesting of functions.
</para>
<para>
Also see <link linkend="g-strchug"><function>g_strchug()</function></link> and <link linkend="g-strstrip"><function>g_strstrip()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara>a string to remove the trailing whitespace from.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>@string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strstrip" role="macro">
<title>g_strstrip()</title>
<indexterm zone="g-strstrip"><primary sortas="strstrip">g_strstrip</primary></indexterm><programlisting>#define             g_strstrip( string )</programlisting>
<para>
Removes leading and trailing whitespace from a string. See <link linkend="g-strchomp"><function>g_strchomp()</function></link> and
<link linkend="g-strchug"><function>g_strchug()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara>a string to remove the leading and trailing whitespace from.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strdelimit" role="function">
<title>g_strdelimit ()</title>
<indexterm zone="g-strdelimit"><primary sortas="strdelimit">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>&#160;:</term>
<listitem><simpara>the string to convert.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>delimiters</parameter>&#160;:</term>
<listitem><simpara>a string containing the current delimiters, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> 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>&#160;:</term>
<listitem><simpara>the new delimiter character.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>@string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="G-STR-DELIMITERS--CAPS" role="macro">
<title>G_STR_DELIMITERS</title>
<indexterm zone="G-STR-DELIMITERS--CAPS"><primary sortas="STR_DELIMITERS">G_STR_DELIMITERS</primary></indexterm><programlisting>#define	 G_STR_DELIMITERS	"_-|&gt; &lt;."
</programlisting>
<para>
The standard delimiters, used in <link linkend="g-strdelimit"><function>g_strdelimit()</function></link>.
</para></refsect2>
<refsect2 id="g-strescape" role="function">
<title>g_strescape ()</title>
<indexterm zone="g-strescape"><primary sortas="strescape">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
'&quot;' 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>&#160;:</term>
<listitem><simpara>a string to escape.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>exceptions</parameter>&#160;:</term>
<listitem><simpara>a string of characters not to escape in <parameter>source</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated copy of <parameter>source</parameter> with certain
characters escaped. See above.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strcompress" role="function">
<title>g_strcompress ()</title>
<indexterm zone="g-strcompress"><primary sortas="strcompress">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>&#160;:</term>
<listitem><simpara>a string to compress.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated copy of <parameter>source</parameter> with all escaped 
character compressed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strcanon" role="function">
<title>g_strcanon ()</title>
<indexterm zone="g-strcanon"><primary sortas="strcanon">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>&#160;:</term>
<listitem><simpara>a nul-terminated array of bytes.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>valid_chars</parameter>&#160;:</term>
<listitem><simpara>bytes permitted in <parameter>string</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>substitutor</parameter>&#160;:</term>
<listitem><simpara>replacement character for disallowed bytes.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>@string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strsplit" role="function">
<title>g_strsplit ()</title>
<indexterm zone="g-strsplit"><primary sortas="strsplit">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>&#160;:</term>
<listitem><simpara> a string to split.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>delimiter</parameter>&#160;:</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>&#160;:</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>&#160;:</term><listitem><simpara> a newly-allocated <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings. Use 
   <link linkend="g-strfreev"><function>g_strfreev()</function></link> to free it.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strsplit-set" role="function" condition="since:2.4">
<title>g_strsplit_set ()</title>
<indexterm zone="g-strsplit-set" role="2.4"><primary sortas="strsplit_set">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
<link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated vector containing the three strings "abc", "def", 
and "ghi".
</para>
<para>
The result if g_strsplit_set (":def/ghi:", ":/", -1) is a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-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-set"><function>g_strsplit_set()</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>&#160;:</term>
<listitem><simpara> The string to be tokenized
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>delimiters</parameter>&#160;:</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>&#160;:</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>&#160;:</term><listitem><simpara> a newly-allocated <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings. Use 
   <link linkend="g-strfreev"><function>g_strfreev()</function></link> to free it.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-strfreev" role="function">
<title>g_strfreev ()</title>
<indexterm zone="g-strfreev"><primary sortas="strfreev">g_strfreev</primary></indexterm><programlisting><link linkend="void">void</link>                g_strfreev                          (<link linkend="gchar">gchar</link> **str_array);</programlisting>
<para>
Frees a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings, and the array itself.
If called on a <link linkend="NULL--CAPS"><literal>NULL</literal></link> value, <link linkend="g-strfreev"><function>g_strfreev()</function></link> simply returns.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str_array</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings to free.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strconcat" role="function">
<title>g_strconcat ()</title>
<indexterm zone="g-strconcat"><primary sortas="strconcat">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 with <link linkend="g-free"><function>g_free()</function></link> when no longer needed.
</para>
<para>
<warning><para>The variable argument list <emphasis>must</emphasis> end 
with <link linkend="NULL--CAPS"><literal>NULL</literal></link>. If you forget the <link linkend="NULL--CAPS"><literal>NULL</literal></link>, <link linkend="g-strconcat"><function>g_strconcat()</function></link> will start appending
random memory junk to your string.</para></warning></para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string1</parameter>&#160;:</term>
<listitem><simpara> the first string to add, which must not be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated list of strings to append to the string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string containing all the string arguments
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-strjoin" role="function">
<title>g_strjoin ()</title>
<indexterm zone="g-strjoin"><primary sortas="strjoin">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. The returned string
should be freed with <link linkend="g-free"><function>g_free()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>separator</parameter>&#160;:</term>
<listitem><simpara> a string to insert between each of the strings, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated list of strings to join
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</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 id="g-strjoinv" role="function">
<title>g_strjoinv ()</title>
<indexterm zone="g-strjoinv"><primary sortas="strjoinv">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. The returned string
should be freed with <link linkend="g-free"><function>g_free()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>separator</parameter>&#160;:</term>
<listitem><simpara> a string to insert between each of the strings, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str_array</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings to join
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</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 id="g-strv-length" role="function" condition="since:2.6">
<title>g_strv_length ()</title>
<indexterm zone="g-strv-length" role="2.6"><primary sortas="strv_length">g_strv_length</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_strv_length                       (<link linkend="gchar">gchar</link> **str_array);</programlisting>
<para>
Returns the length of the given <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated 
string array <parameter>str_array</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>str_array</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> length of <parameter>str_array</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.6</para></refsect2>
<refsect2 id="g-strerror" role="function">
<title>g_strerror ()</title>
<indexterm zone="g-strerror"><primary sortas="strerror">g_strerror</primary></indexterm><programlisting>const <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". You should use this function in preference to 
<link linkend="strerror"><function>strerror()</function></link>, because it returns a string in UTF-8 encoding, and since 
not all platforms support the <link linkend="strerror"><function>strerror()</function></link> function.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>errnum</parameter>&#160;:</term>
<listitem><simpara> the system error number. See the standard C <link linkend="errno"><literal>errno</literal></link>
    documentation
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a UTF-8 string describing the error code. If the error code 
    is unknown, it returns "unknown error (&lt;code&gt;)". 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 id="g-strsignal" role="function">
<title>g_strsignal ()</title>
<indexterm zone="g-strsignal"><primary sortas="strsignal">g_strsignal</primary></indexterm><programlisting>const <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".
You should use this function in preference to <link linkend="strsignal"><function>strsignal()</function></link>, because it 
returns a string in UTF-8 encoding, and since not all platforms support
the <link linkend="strsignal"><function>strsignal()</function></link> function.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>signum</parameter>&#160;:</term>
<listitem><simpara> the signal number. See the <literal>signal</literal>
    documentation
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a UTF-8 string describing the signal. If the signal is unknown,
    it returns "unknown signal (&lt;signum&gt;)". 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>
