<refentry id="glib-String-Utility-Functions">
<refmeta>
<refentrytitle>String Utility Functions</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>String Utility Functions</refname><refpurpose>various string-related functions.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.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 char *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="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,
                                             va_list 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,
                                             va_list 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,
                                             va_list 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);

#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);
void        <link linkend="g-strfreev">g_strfreev</link>                      (<link linkend="gchar">gchar</link> **str_array);
<link linkend="gchar">gchar</link>*      <link linkend="g-strconcat">g_strconcat</link>                     (const <link linkend="gchar">gchar</link> *string1,
                                             ...);
<link linkend="gchar">gchar</link>*      <link linkend="g-strjoin">g_strjoin</link>                       (const <link linkend="gchar">gchar</link> *separator,
                                             ...);
<link linkend="gchar">gchar</link>*      <link linkend="g-strjoinv">g_strjoinv</link>                      (const <link linkend="gchar">gchar</link> *separator,
                                             <link linkend="gchar">gchar</link> **str_array);

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

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
This section describes a number of utility functions for creating,
duplicating, and manipulating strings.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="g-strdup">g_strdup ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strdup                        (const <link linkend="gchar">gchar</link> *str);</programlisting>
<para>
Duplicates a string.
The returned string should be freed when no longer needed.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry>the string to duplicate.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated copy of <parameter>str</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strndup">g_strndup ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strndup                       (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gsize">gsize</link> n);</programlisting>
<para>
Duplicates the first <parameter>n</parameter> characters of a string, returning a newly-allocated
buffer <parameter>n</parameter> + 1 characters long which will always be nul-terminated.
If <parameter>str</parameter> is less than <parameter>n</parameter> characters long the buffer is padded with nuls.
The returned value should be freed when no longer needed.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry>the string to duplicate part of.
</entry></row>
<row><entry align="right"><parameter>n</parameter>&nbsp;:</entry>
<entry>the maximum number of characters to copy from <parameter>str</parameter>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated buffer containing the first <parameter>n</parameter> characters of <parameter>str</parameter>,
nul-terminated.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strdupv">g_strdupv ()</title>
<programlisting><link linkend="gchar">gchar</link>**     g_strdupv                       (<link linkend="gchar">gchar</link> **str_array);</programlisting>
<para>
Copies <literal>NULL</literal>-terminated array of strings. The copy is a deep copy;
the new array should be freed by first freeing each string, then
the array itself. <link linkend="g-strfreev">g_strfreev</link>() does this for you. If called
on a <literal>NULL</literal> value, <link linkend="g-strdupv">g_strdupv</link>() simply returns <literal>NULL</literal>.</para>
<para>
Copies a <literal>NULL</literal>-terminated array of strings. The result consists of a
<literal>NULL</literal>-terminated array, with one malloc block holding the array of strings, and
each string itself allocated. The simplest way to free the result is with
<link linkend="g-strfreev">g_strfreev</link>() which frees each string in a vector, then the vector itself.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str_array</parameter>&nbsp;:</entry>
<entry> <literal>NULL</literal>-terminated array of strings.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new <literal>NULL</literal>-terminated array of strings.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strnfill">g_strnfill ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strnfill                      (<link linkend="gsize">gsize</link> length,
                                             <link linkend="gchar">gchar</link> fill_char);</programlisting>
<para>
Creates a new string <parameter>length</parameter> characters long filled with <parameter>fill_char</parameter>.
The returned string should be freed when no longer needed.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>length</parameter>&nbsp;:</entry>
<entry>the length of the new string.
</entry></row>
<row><entry align="right"><parameter>fill_char</parameter>&nbsp;:</entry>
<entry>the character to fill the string with.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated string filled the <parameter>fill_char</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-stpcpy">g_stpcpy ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_stpcpy                        (<link linkend="gchar">gchar</link> *dest,
                                             const char *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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dest</parameter>&nbsp;:</entry>
<entry> destination buffer.
</entry></row>
<row><entry align="right"><parameter>src</parameter>&nbsp;:</entry>
<entry> source string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to trailing nul byte.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strstr-len">g_strstr_len ()</title>
<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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>haystack</parameter>&nbsp;:</entry>
<entry> a string.
</entry></row>
<row><entry align="right"><parameter>haystack_len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>haystack</parameter>.
</entry></row>
<row><entry align="right"><parameter>needle</parameter>&nbsp;:</entry>
<entry> the string to search for.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to the found occurrence, or
   <literal>NULL</literal> if not found.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strrstr">g_strrstr ()</title>
<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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>haystack</parameter>&nbsp;:</entry>
<entry> a nul-terminated string.
</entry></row>
<row><entry align="right"><parameter>needle</parameter>&nbsp;:</entry>
<entry> the nul-terminated string to search for.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to the found occurrence, or
   <literal>NULL</literal> if not found.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strrstr-len">g_strrstr_len ()</title>
<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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>haystack</parameter>&nbsp;:</entry>
<entry> a nul-terminated string.
</entry></row>
<row><entry align="right"><parameter>haystack_len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>haystack</parameter>.
</entry></row>
<row><entry align="right"><parameter>needle</parameter>&nbsp;:</entry>
<entry> the nul-terminated string to search for.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to the found occurrence, or
   <literal>NULL</literal> if not found.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strlcpy">g_strlcpy ()</title>
<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">strlcpy</link>() on systems which have it, and emulates
<link linkend="strlcpy">strlcpy</link>() otherwise. Copies <parameter>src</parameter> to <parameter>dest</parameter>; <parameter>dest</parameter> is guaranteed to be
nul-terminated; <parameter>src</parameter> must be nul-terminated; <parameter>dest_size</parameter> is the buffer size, not
the number of chars to copy. Caveat: <link linkend="strlcpy">strlcpy</link>() is supposedly more secure than
<link linkend="strcpy">strcpy</link>() or <link linkend="strncpy">strncpy</link>(), but if you really want to avoid screwups, <link linkend="g-strdup">g_strdup</link>() is
an even better idea.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dest</parameter>&nbsp;:</entry>
<entry>destination buffer
</entry></row>
<row><entry align="right"><parameter>src</parameter>&nbsp;:</entry>
<entry>source buffer
</entry></row>
<row><entry align="right"><parameter>dest_size</parameter>&nbsp;:</entry>
<entry>length of <parameter>dest</parameter> in bytes
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>length of <parameter>src</parameter>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strlcat">g_strlcat ()</title>
<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 <function><link linkend="strlcat">strlcat</link>()</function> on systems which have it, and emulates it otherwise. Appends nul-terminated <parameter>src</parameter> string to <parameter>dest</parameter>, guaranteeing
nul-termination for <parameter>dest</parameter>. The total size of <parameter>dest</parameter> won't exceed
<parameter>dest_size</parameter>. Caveat: this is supposedly a more secure alternative to <function><link linkend="strcat">strcat</link>()</function> or
<function><link linkend="strncat">strncat</link>()</function>, but for real security <link linkend="g-strconcat">g_strconcat</link>() is harder to mess up.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dest</parameter>&nbsp;:</entry>
<entry>destination buffer, already containing one nul-terminated string
</entry></row>
<row><entry align="right"><parameter>src</parameter>&nbsp;:</entry>
<entry>source buffer
</entry></row>
<row><entry align="right"><parameter>dest_size</parameter>&nbsp;:</entry>
<entry>length of <parameter>dest</parameter> buffer in bytes (not length of existing string inside <parameter>dest</parameter>)
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>length of <parameter>src</parameter> plus initial length of string in <parameter>dest</parameter>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strdup-printf">g_strdup_printf ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strdup_printf                 (const <link linkend="gchar">gchar</link> *format,
                                             ...);</programlisting>
<para>
Similar to the standard C <function>sprintf()</function> function
but safer, since it calculates the maximum space required and allocates
memory to hold the result.
The returned string should be freed when no longer needed.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry>the standard <function>sprintf()</function> format string.
</entry></row>
<row><entry align="right"><parameter>...</parameter>&nbsp;:</entry>
<entry>the parameters to insert into the format string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated string holding the result.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strdup-vprintf">g_strdup_vprintf ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strdup_vprintf                (const <link linkend="gchar">gchar</link> *format,
                                             va_list args);</programlisting>
<para>
Similar to the standard C <function><link linkend="vsprintf">vsprintf</link>()</function> function
but safer, since it calculates the maximum space required and allocates
memory to hold the result.
The returned string should be freed when no longer needed.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry>the standard <function>sprintf()</function> format string.
</entry></row>
<row><entry align="right"><parameter>args</parameter>&nbsp;:</entry>
<entry>the list of parameters to insert into the format string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated string holding the result.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-snprintf">g_snprintf ()</title>
<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 <function>sprintf()</function> 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">g_strdup_printf</link>().
</para>
<note>
<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>
</note>
<note>
<para>
The return value of <link linkend="g-snprintf">g_snprintf</link>() conforms to the <function><link linkend="snprintf">snprintf</link>()</function>
function as standardized in ISO C99. Note that this is different from 
traditional <function><link linkend="snprintf">snprintf</link>()</function>, which returns the length of 
the output string.
</para>
</note><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>the buffer to hold the output.
</entry></row>
<row><entry align="right"><parameter>n</parameter>&nbsp;:</entry>
<entry>the maximum number of characters to produce (including the terminating nul
character).
</entry></row>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry>the format string. See the <function>sprintf()</function>.
documentation.
</entry></row>
<row><entry align="right"><parameter>...</parameter>&nbsp;:</entry>
<entry>the arguments to insert in the output.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the number of characters which would be produced if the buffer was
large enough.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-vsnprintf">g_vsnprintf ()</title>
<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,
                                             va_list args);</programlisting>
<para>
A safer form of the standard <function><link linkend="vsprintf">vsprintf</link>()</function> 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">g_strdup_vprintf</link>().
</para>
<note>
<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>
</note>
<note>
<para>
The return value of <link linkend="g-vsnprintf">g_vsnprintf</link>() conforms to the <function><link linkend="vsnprintf">vsnprintf</link>()</function>
function as standardized in ISO C99. Note that this is different from 
traditional <function><link linkend="vsnprintf">vsnprintf</link>()</function>, which returns the length of 
the output string.
</para>
</note><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>the buffer to hold the output.
</entry></row>
<row><entry align="right"><parameter>n</parameter>&nbsp;:</entry>
<entry>the maximum number of characters to produce (including the terminating nul
character).
</entry></row>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry>the format string. See the <function>sprintf()</function>
documentation.
</entry></row>
<row><entry align="right"><parameter>args</parameter>&nbsp;:</entry>
<entry>the list of arguments to insert in the output.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the number of characters which would be produced if the buffer was
large enough.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-printf-string-upper-bound">g_printf_string_upper_bound ()</title>
<programlisting><link linkend="gsize">gsize</link>       g_printf_string_upper_bound     (const <link linkend="gchar">gchar</link> *format,
                                             va_list args);</programlisting>
<para>
Calculates the maximum space needed to store the output of the
<function>sprintf()</function> function.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry>the format string. See the <function>printf()</function>
documentation.
</entry></row>
<row><entry align="right"><parameter>args</parameter>&nbsp;:</entry>
<entry>the parameters to be inserted into the format string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the maximum space needed to store the formatted string.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-isalnum">g_ascii_isalnum ()</title>
<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 <function><link linkend="isalnum">isalnum</link>()</function> function, this only
recognizes standard ASCII letters and ignores the locale, returning
<literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a 
possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII alphanumeric character


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-isalpha">g_ascii_isalpha ()</title>
<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 <function><link linkend="isalpha">isalpha</link>()</function> function, this only
recognizes standard ASCII letters and ignores the locale, returning
<literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a 
possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII alphabetic character


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-iscntrl">g_ascii_iscntrl ()</title>
<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 <function><link linkend="iscntrl">iscntrl</link>()</function> function, this only
recognizes standard ASCII control characters and ignores the locale,
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a 
possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII control character.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-isdigit">g_ascii_isdigit ()</title>
<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 <function><link linkend="isdigit">isdigit</link>()</function> function,
this takes a <type>char</type>, not an <type>int</type>, so don't call it
on <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a possibly
non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII digit.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-isgraph">g_ascii_isgraph ()</title>
<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 <function><link linkend="isgraph">isgraph</link>()</function> function, 
this only recognizes standard ASCII characters and ignores the locale, 
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a 
possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII printing character other than space.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-islower">g_ascii_islower ()</title>
<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 <function><link linkend="islower">islower</link>()</function> function, 
this only recognizes standard ASCII letters and ignores the locale,
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on <literal>EOF</literal> but no need to worry about casting to <link linkend="guchar">guchar</link> 
before passing a possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII lower case letter


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-isprint">g_ascii_isprint ()</title>
<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 <function><link linkend="isprint">isprint</link>()</function> function, 
this only recognizes standard ASCII characters and ignores the locale, 
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a 
possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII printing character.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-ispunct">g_ascii_ispunct ()</title>
<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 <function><link linkend="ispunct">ispunct</link>()</function> function, 
this only recognizes standard ASCII letters and ignores the locale, 
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a 
possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII punctuation character.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-isspace">g_ascii_isspace ()</title>
<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 <function><link linkend="isspace">isspace</link>()</function> function, 
this only recognizes standard ASCII white-space and ignores the locale, 
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a 
possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII white-space character


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-isupper">g_ascii_isupper ()</title>
<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 <function><link linkend="isupper">isupper</link>()</function> function, 
this only recognizes standard ASCII letters and ignores the locale, 
returning <literal>FALSE</literal> for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on <literal>EOF</literal> but no need to worry about casting to <link linkend="guchar">guchar</link> 
before passing a possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII upper case letter


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-isxdigit">g_ascii_isxdigit ()</title>
<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 <function><link linkend="isxdigit">isxdigit</link>()</function> function,
this takes a <type>char</type>, not an <type>int</type>, so
don't call it on <literal>EOF</literal> but no need to cast to <link linkend="guchar">guchar</link> before passing a
possibly non-ASCII character in.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry>any character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if <parameter>c</parameter> is an ASCII hexadecimal-digit character.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-digit-value">g_ascii_digit_value ()</title>
<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">g_unichar_digit_value</link>() because it takes
a char, so there's no worry about sign extension if characters
are signed.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> an ASCII character.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> If <parameter>c</parameter> is a decimal digit (according to
<link linkend="g-ascii-isdigit">g_ascii_isdigit</link>()), its numeric value. Otherwise, -1.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-xdigit-value">g_ascii_xdigit_value ()</title>
<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">g_unichar_xdigit_value</link>() because it takes
a char, so there's no worry about sign extension if characters
are signed.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> an ASCII character.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> If <parameter>c</parameter> is a hex digit (according to
<link linkend="g-ascii-isxdigit">g_ascii_isxdigit</link>()), its numeric value. Otherwise, -1.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-strcasecmp">g_ascii_strcasecmp ()</title>
<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">strcasecmp</link>() function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
characters as if they are not letters.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>s1</parameter>&nbsp;:</entry>
<entry> string to compare with <parameter>s2</parameter>.
</entry></row>
<row><entry align="right"><parameter>s2</parameter>&nbsp;:</entry>
<entry> string to compare with <parameter>s1</parameter>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> an integer less than, equal to, or greater than
              zero if <parameter>s1</parameter> is found, respectively, to be less than,
              to match, or to be greater than <parameter>s2</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-strncasecmp">g_ascii_strncasecmp ()</title>
<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">strcasecmp</link>() function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
characters as if they are not letters.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>s1</parameter>&nbsp;:</entry>
<entry> string to compare with <parameter>s2</parameter>.
</entry></row>
<row><entry align="right"><parameter>s2</parameter>&nbsp;:</entry>
<entry> string to compare with <parameter>s1</parameter>.
</entry></row>
<row><entry align="right"><parameter>n</parameter>&nbsp;:</entry>
<entry>  number of characters to compare.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> an integer less than, equal to, or greater than zero
              if the first <parameter>n</parameter> bytes of <parameter>s1</parameter> is found, respectively,
              to be less than, to match, or to be greater than the
              first <parameter>n</parameter> bytes of <parameter>s2</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-strup">g_ascii_strup ()</title>
<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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a string.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> length of <parameter>str</parameter> in bytes, or -1 if <parameter>str</parameter> is nul-terminated.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> 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">g_ascii_toupper</link>(). (Note
              that this is unlike the old <link linkend="g-strup">g_strup</link>(), which modified
              the string in place.)
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-strdown">g_ascii_strdown ()</title>
<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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a string.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> length of <parameter>str</parameter> in bytes, or -1 if <parameter>str</parameter> is nul-terminated.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> 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">g_ascii_tolower</link>(). (Note
              that this is unlike the old <link linkend="g-strdown">g_strdown</link>(), which modified
              the string in place.)
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-tolower">g_ascii_tolower ()</title>
<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">tolower</link>() function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are lower case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
don't call it on <literal>EOF</literal> but no need to worry about casting to <link linkend="guchar">guchar</link>
before passing a possibly non-ASCII character in.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> any character.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> 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.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-toupper">g_ascii_toupper ()</title>
<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">toupper</link>() function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are upper case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
don't call it on <literal>EOF</literal> but no need to worry about casting to <link linkend="guchar">guchar</link>
before passing a possibly non-ASCII character in.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> any character.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> 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.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-ascii-up">g_string_ascii_up ()</title>
<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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry> a GString
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> passed-in <parameter>string</parameter> pointer, with all the lower case
              characters converted to upper case in place, with
              semantics that exactly match g_ascii_toupper.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-string-ascii-down">g_string_ascii_down ()</title>
<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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry> a GString
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> passed-in <parameter>string</parameter> pointer, with all the upper case
              characters converted to lower case in place, with
              semantics that exactly match g_ascii_tolower.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strup">g_strup ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strup                         (<link linkend="gchar">gchar</link> *string);</programlisting>
<warning>
<para>
<literal>g_strup</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Converts a string to upper case. This function is totally broken
for the reasons discussed in the <link linkend="g-strncasecmp">g_strncasecmp</link>() docs - 
use <link linkend="g-ascii-strup">g_ascii_strup</link>() or <link linkend="g-utf8-strup">g_utf8_strup</link>() instead.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>the string to convert.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strdown">g_strdown ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strdown                       (<link linkend="gchar">gchar</link> *string);</programlisting>
<warning>
<para>
<literal>g_strdown</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Converts a string to lower case.  This function is totally broken for
the reasons discussed in the <link linkend="g-strncasecmp">g_strncasecmp</link>() docs - use
<link linkend="g-ascii-strdown">g_ascii_strdown</link>() or <link linkend="g-utf8-strdown">g_utf8_strdown</link>() instead.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>the string to convert.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strcasecmp">g_strcasecmp ()</title>
<programlisting><link linkend="gint">gint</link>        g_strcasecmp                    (const <link linkend="gchar">gchar</link> *s1,
                                             const <link linkend="gchar">gchar</link> *s2);</programlisting>
<warning>
<para>
<literal>g_strcasecmp</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
A case-insensitive string comparison, corresponding to the standard
<function><link linkend="strcasecmp">strcasecmp</link>()</function> function on platforms which support it.
</para>
<para>
See <link linkend="g-strncasecmp">g_strncasecmp</link>() for a discussion of why this is deprecated and
how to replace it.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>s1</parameter>&nbsp;:</entry>
<entry>a string.
</entry></row>
<row><entry align="right"><parameter>s2</parameter>&nbsp;:</entry>
<entry>a string to compare with <parameter>s1</parameter>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>0 if the strings match, a negative value if <parameter>s1</parameter> < <parameter>s2</parameter>, or a positive
value if <parameter>s1</parameter> > <parameter>s2</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strncasecmp">g_strncasecmp ()</title>
<programlisting><link linkend="gint">gint</link>        g_strncasecmp                   (const <link linkend="gchar">gchar</link> *s1,
                                             const <link linkend="gchar">gchar</link> *s2,
                                             <link linkend="guint">guint</link> n);</programlisting>
<warning>
<para>
<literal>g_strncasecmp</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
A case-insensitive string comparison, corresponding to the standard
<function><link linkend="strncasecmp">strncasecmp</link>()</function> function on platforms which support it.
It is similar to <link linkend="g-strcasecmp">g_strcasecmp</link>() except it only compares the first <parameter>n</parameter> characters
of the strings.
</para>
<para>
The problem with <link linkend="g-strncasecmp">g_strncasecmp</link>() is that it does the comparison by
calling <function><link linkend="toupper">toupper</link>()</function>/<function><link linkend="tolower">tolower</link>()</function> 
on each byte. <function><link linkend="toupper">toupper</link>()</function>/<function><link linkend="tolower">tolower</link>()</function> 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">g_strncasecmp</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">g_ascii_strncasecmp</link>(),
which only works on ASCII and is not locale-sensitive, and
<link linkend="g-utf8-casefold">g_utf8_casefold</link>(), which is good for case-insensitive sorting of
UTF-8.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>s1</parameter>&nbsp;:</entry>
<entry>a string.
</entry></row>
<row><entry align="right"><parameter>s2</parameter>&nbsp;:</entry>
<entry>a string to compare with <parameter>s1</parameter>.
</entry></row>
<row><entry align="right"><parameter>n</parameter>&nbsp;:</entry>
<entry>the maximum number of characters to compare.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>0 if the strings match, a negative value if <parameter>s1</parameter> < <parameter>s2</parameter>, or a positive
value if <parameter>s1</parameter> > <parameter>s2</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strreverse">g_strreverse ()</title>
<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">g_strreverse</link>() doesn't work on UTF-8 strings containing multibyte characters.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>the string to reverse.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the same pointer passed in as <parameter>string</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-ASCII-DTOSTR-BUF-SIZE-CAPS">G_ASCII_DTOSTR_BUF_SIZE</title>
<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">g_ascii_dtostr</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=<literal>s</literal>\n", g_ascii_dtostr (buf, sizeof (buf), value));
</programlisting></informalexample>
</para></refsect2>
<refsect2>
<title><anchor id="g-ascii-strtod">g_ascii_strtod ()</title>
<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">gdouble</link> value.
This function behaves like the standard <link linkend="strtod">strtod</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 dependent.
To handle input from the user you should normally use the
locale-sensitive system <link linkend="strtod">strtod</link>() function.
</para>
<para>
To convert from a string to <link linkend="gdouble">gdouble</link> in a locale-insensitive
way, use <link linkend="g-ascii-dtostr">g_ascii_dtostr</link>().
</para>
<para>
If the correct value would cause overflow, plus or minus <literal>HUGE_VAL</literal>
is returned (according to the sign of the value), and <literal>ERANGE</literal> is
stored in <literal>errno</literal>. If the correct value would cause underflow,
zero is returned and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
</para>
<para>
This function resets <literal>errno</literal> before calling <link linkend="strtod">strtod</link>() so that
you can reliably detect overflow and underflow.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>nptr</parameter>&nbsp;:</entry>
<entry>    the string to convert to a numeric value.
</entry></row>
<row><entry align="right"><parameter>endptr</parameter>&nbsp;:</entry>
<entry>  if non-<literal>NULL</literal>, it returns the character after
          the last character used in the conversion.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the <link linkend="gdouble">gdouble</link> value.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-dtostr">g_ascii_dtostr ()</title>
<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">gdouble</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-strtod">g_strtod</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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>buffer</parameter>&nbsp;:</entry>
<entry> A buffer to place the resulting string in
</entry></row>
<row><entry align="right"><parameter>buf_len</parameter>&nbsp;:</entry>
<entry> The length of the buffer.
</entry></row>
<row><entry align="right"><parameter>d</parameter>&nbsp;:</entry>
<entry> The <link linkend="gdouble">gdouble</link> to convert
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The pointer to the buffer with the converted string.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ascii-formatd">g_ascii_formatd ()</title>
<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">gdouble</link> to a string, using the '.' as
decimal point. To format the number you pass in
a printf-style formating 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">g_ascii_dtostr</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>buffer</parameter>&nbsp;:</entry>
<entry> A buffer to place the resulting string in
</entry></row>
<row><entry align="right"><parameter>buf_len</parameter>&nbsp;:</entry>
<entry> The length of the buffer.
</entry></row>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry> The printf-style format to use for the
         code to use for converting. 
</entry></row>
<row><entry align="right"><parameter>d</parameter>&nbsp;:</entry>
<entry> The <link linkend="gdouble">gdouble</link> to convert
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The pointer to the buffer with the converted string.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strtod">g_strtod ()</title>
<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">gdouble</link> value.
It calls the standard <link linkend="strtod">strtod</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">g_ascii_strtod</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">g_ascii_strtod</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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>nptr</parameter>&nbsp;:</entry>
<entry>    the string to convert to a numeric value.
</entry></row>
<row><entry align="right"><parameter>endptr</parameter>&nbsp;:</entry>
<entry>  if non-<literal>NULL</literal>, it returns the character after
          the last character used in the conversion.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the <link linkend="gdouble">gdouble</link> value.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strchug">g_strchug ()</title>
<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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>a string to remove the leading whitespace from.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><parameter>string</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strchomp">g_strchomp ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strchomp                      (<link linkend="gchar">gchar</link> *string);</programlisting>
<para>
Removes trailing whitespace from a string.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>a string to remove the trailing whitespace from.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><parameter>string</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strstrip">g_strstrip()</title>
<programlisting>#define     g_strstrip( string )</programlisting>
<para>
Removes leading and trailing whitespace from a string.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>a string to remove the leading and trailing whitespace from.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strdelimit">g_strdelimit ()</title>
<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.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>the string to convert.
</entry></row>
<row><entry align="right"><parameter>delimiters</parameter>&nbsp;:</entry>
<entry>a string containing the current delimiters, or <literal>NULL</literal> to use the
standard delimiters defined in <link linkend="G-STR-DELIMITERS-CAPS">G_STR_DELIMITERS</link>.
</entry></row>
<row><entry align="right"><parameter>new_delimiter</parameter>&nbsp;:</entry>
<entry>the new delimiter character.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-STR-DELIMITERS-CAPS">G_STR_DELIMITERS</title>
<programlisting>#define	 G_STR_DELIMITERS	"_-|&gt; &lt;."
</programlisting>
<para>
The standard delimiters, used in <link linkend="g-strdelimit">g_strdelimit</link>().
</para></refsect2>
<refsect2>
<title><anchor id="g-strescape">g_strescape ()</title>
<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 0x80-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">g_strcompress</link>() does the reverse conversion.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>source</parameter>&nbsp;:</entry>
<entry>a string to escape.
</entry></row>
<row><entry align="right"><parameter>exceptions</parameter>&nbsp;:</entry>
<entry>a string of characters not to escape in <parameter>source</parameter>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated copy of <parameter>source</parameter> with certain
characters escaped. See above.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strcompress">g_strcompress ()</title>
<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">g_strescape</link>(). 
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>source</parameter>&nbsp;:</entry>
<entry>a string to compress.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated copy of <parameter>source</parameter> with all escaped 
character compressed.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strcanon">g_strcanon ()</title>
<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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry>a nul-terminated array of bytes.
</entry></row>
<row><entry align="right"><parameter>valid_chars</parameter>&nbsp;:</entry>
<entry>bytes permitted in <parameter>string</parameter>.
</entry></row>
<row><entry align="right"><parameter>substitutor</parameter>&nbsp;:</entry>
<entry>replacement character for disallowed bytes.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><parameter>string</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strsplit">g_strsplit ()</title>
<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">g_strsplit</link>().</para>
<para>
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry> a string to split.
</entry></row>
<row><entry align="right"><parameter>delimiter</parameter>&nbsp;:</entry>
<entry> 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.
</entry></row>
<row><entry align="right"><parameter>max_tokens</parameter>&nbsp;:</entry>
<entry> the maximum number of pieces to split <parameter>string</parameter> into. If this is
             less than 1, the string is split completely.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly-allocated <literal>NULL</literal>-terminated array of strings. Use 
   <link linkend="g-strfreev">g_strfreev</link>() to free it.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strfreev">g_strfreev ()</title>
<programlisting>void        g_strfreev                      (<link linkend="gchar">gchar</link> **str_array);</programlisting>
<para>
Frees a <literal>NULL</literal>-terminated array of strings, and the array itself.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str_array</parameter>&nbsp;:</entry>
<entry>a <literal>NULL</literal>-terminated array of strings to free.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strconcat">g_strconcat ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strconcat                     (const <link linkend="gchar">gchar</link> *string1,
                                             ...);</programlisting>
<para>
Concatenates all of the given strings into one long string.  The returned string
should be freed when no longer needed.  WARNING: THE VARIABLE ARGUMENT LIST MUST
END WITH <literal>NULL</literal>. If you forget the <literal>NULL</literal>, <link linkend="g-strconcat">g_strconcat</link>() will start appending
random memory junk to your string.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string1</parameter>&nbsp;:</entry>
<entry>The first string to add, which must not be <literal>NULL</literal>.
</entry></row>
<row><entry align="right"><parameter>...</parameter>&nbsp;:</entry>
<entry>a <literal>NULL</literal>-terminated list of strings to append to the string.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated string containing all the string arguments.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strjoin">g_strjoin ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strjoin                       (const <link linkend="gchar">gchar</link> *separator,
                                             ...);</programlisting>
<para>
Joins a number of strings together to form one long string, with the optional
<parameter>separator</parameter> inserted between each of them.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>separator</parameter>&nbsp;:</entry>
<entry>a string to insert between each of the strings, or <literal>NULL</literal>.
</entry></row>
<row><entry align="right"><parameter>...</parameter>&nbsp;:</entry>
<entry>a <literal>NULL</literal>-terminated list of strings to join.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated string containing all of the strings joined
together, with <parameter>separator</parameter> between them.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strjoinv">g_strjoinv ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_strjoinv                      (const <link linkend="gchar">gchar</link> *separator,
                                             <link linkend="gchar">gchar</link> **str_array);</programlisting>
<para>
Joins a number of strings together to form one long string, with the optional
<parameter>separator</parameter> inserted between each of them.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>separator</parameter>&nbsp;:</entry>
<entry>a string to insert between each of the strings, or <literal>NULL</literal>.
</entry></row>
<row><entry align="right"><parameter>str_array</parameter>&nbsp;:</entry>
<entry>a <literal>NULL</literal>-terminated array of strings to join.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated string containing all of the strings joined
together, with <parameter>separator</parameter> between them.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strerror">g_strerror ()</title>
<programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_strerror            (<link linkend="gint">gint</link> errnum);</programlisting>
<para>
Returns a string corresponding to the given error code, e.g. "no such process".
This function is included since not all platforms support the 
<function><link linkend="strerror">strerror</link>()</function> function.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>errnum</parameter>&nbsp;:</entry>
<entry>the system error number. See the standard C <literal>errno</literal>
documentation.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a 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 g_strerror.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-strsignal">g_strsignal ()</title>
<programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_strsignal           (<link linkend="gint">gint</link> signum);</programlisting>
<para>
Returns a string describing the given signal, e.g. "Segmentation fault".
This function is included since not all platforms support the
<function><link linkend="strsignal">strsignal</link>()</function> function.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>signum</parameter>&nbsp;:</entry>
<entry>the signal number. See the <literal>signal</literal>
documentation.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a 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 g_strsignal.


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

</refsect1>




</refentry>
