<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="glib-String-Utility-Functions">
<refmeta>
<refentrytitle role="top_of_page" id="glib-String-Utility-Functions.top_of_page">String Utility Functions</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>String Utility Functions</refname>
<refpurpose>various string-related functions</refpurpose>
</refnamediv>

<refsect1 id="glib-String-Utility-Functions.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_return" colwidth="150px"/>
<colspec colname="functions_name"/>
<tbody>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strdup">g_strdup</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strndup">g_strndup</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
</entry><entry role="function_name"><link linkend="g-strdupv">g_strdupv</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strnfill">g_strnfill</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-stpcpy">g_stpcpy</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strstr-len">g_strstr_len</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strrstr">g_strrstr</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strrstr-len">g_strrstr_len</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-str-has-prefix">g_str_has_prefix</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-str-has-suffix">g_str_has_suffix</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="int"><returnvalue>int</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-strcmp0">g_strcmp0</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-str-to-ascii">g_str_to_ascii</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
</entry><entry role="function_name"><link linkend="g-str-tokenize-and-fold">g_str_tokenize_and_fold</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-str-match-string">g_str_match_string</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-strlcpy">g_strlcpy</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-strlcat">g_strlcat</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strdup-printf">g_strdup_printf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strdup-vprintf">g_strdup_vprintf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-printf">g_printf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-vprintf">g_vprintf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-fprintf">g_fprintf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-vfprintf">g_vfprintf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-sprintf">g_sprintf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-vsprintf">g_vsprintf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-snprintf">g_snprintf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-vsnprintf">g_vsnprintf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-vasprintf">g_vasprintf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-printf-string-upper-bound">g_printf_string_upper_bound</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-str-is-ascii">g_str_is_ascii</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-isalnum">g_ascii_isalnum</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-isalpha">g_ascii_isalpha</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-iscntrl">g_ascii_iscntrl</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-isdigit">g_ascii_isdigit</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-isgraph">g_ascii_isgraph</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-islower">g_ascii_islower</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-isprint">g_ascii_isprint</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-ispunct">g_ascii_ispunct</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-isspace">g_ascii_isspace</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-isupper">g_ascii_isupper</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-isxdigit">g_ascii_isxdigit</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-digit-value">g_ascii_digit_value</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-xdigit-value">g_ascii_xdigit_value</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-strcasecmp">g_ascii_strcasecmp</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-strncasecmp">g_ascii_strncasecmp</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-ascii-strup">g_ascii_strup</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-ascii-strdown">g_ascii_strdown</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-tolower">g_ascii_tolower</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-toupper">g_ascii_toupper</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

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

<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strup">g_strup</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strdown">g_strdown</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-strcasecmp">g_strcasecmp</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-strncasecmp">g_strncasecmp</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strreverse">g_strreverse</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gint64"><returnvalue>gint64</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-strtoll">g_ascii_strtoll</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint64"><returnvalue>guint64</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-strtoull">g_ascii_strtoull</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gdouble"><returnvalue>gdouble</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-strtod">g_ascii_strtod</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-ascii-dtostr">g_ascii_dtostr</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-ascii-formatd">g_ascii_formatd</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gdouble"><returnvalue>gdouble</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-strtod">g_strtod</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-string-to-signed">g_ascii_string_to_signed</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-ascii-string-to-unsigned">g_ascii_string_to_unsigned</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>


<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strchug">g_strchug</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strchomp">g_strchomp</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-strstrip">g_strstrip</link><phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strdelimit">g_strdelimit</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strescape">g_strescape</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strcompress">g_strcompress</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strcanon">g_strcanon</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
</entry><entry role="function_name"><link linkend="g-strsplit">g_strsplit</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
</entry><entry role="function_name"><link linkend="g-strsplit-set">g_strsplit_set</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-strfreev">g_strfreev</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strconcat">g_strconcat</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strjoin">g_strjoin</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strjoinv">g_strjoinv</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-strv-length">g_strv_length</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-strv-contains">g_strv_contains</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-strv-equal">g_strv_equal</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strerror">g_strerror</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strsignal">g_strsignal</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="glib-String-Utility-Functions.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="name" colwidth="150px"/>
<colspec colname="description"/>
<tbody>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-ASCII-DTOSTR-BUF-SIZE:CAPS">G_ASCII_DTOSTR_BUF_SIZE</link></entry></row>

<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="GNumberParserError">GNumberParserError</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-NUMBER-PARSER-ERROR:CAPS">G_NUMBER_PARSER_ERROR</link></entry></row>



<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-STR-DELIMITERS:CAPS">G_STR_DELIMITERS</link></entry></row>

<row><entry role="typedef_keyword">typedef</entry><entry role="function_name"><link linkend="GStrv">GStrv</link></entry></row>

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

<refsect1 id="glib-String-Utility-Functions.includes"><title>Includes</title><synopsis>#include &lt;glib.h&gt;
#include &lt;glib/gprintf.h&gt;
</synopsis></refsect1>

<refsect1 id="glib-String-Utility-Functions.description" role="desc">
<title role="desc.title">Description</title>
<para>This section describes a number of utility functions for creating,
duplicating, and manipulating strings.</para>
<para>Note that the functions <link linkend="g-printf"><function>g_printf()</function></link>, <link linkend="g-fprintf"><function>g_fprintf()</function></link>, <link linkend="g-sprintf"><function>g_sprintf()</function></link>,
<link linkend="g-vprintf"><function>g_vprintf()</function></link>, <link linkend="g-vfprintf"><function>g_vfprintf()</function></link>, <link linkend="g-vsprintf"><function>g_vsprintf()</function></link> and <link linkend="g-vasprintf"><function>g_vasprintf()</function></link>
are declared in the header <literal>gprintf.h</literal> which is not included in <literal>glib.h</literal>
(otherwise using <literal>glib.h</literal> would drag in <literal>stdio.h</literal>), so you'll have to
explicitly include <literal>&lt;glib/gprintf.h&gt;</literal> in order to use the GLib
<link linkend="printf"><function>printf()</function></link> functions.</para>
<refsect3 id="string-precision"><title>String precision pitfalls</title><para>While you may use the <link linkend="printf"><function>printf()</function></link> functions to format UTF-8 strings,
notice that the precision of a %Ns parameter is interpreted
as the number of bytes, not characters to print. On top of that,
the GNU libc implementation of the <link linkend="printf"><function>printf()</function></link> functions has the
"feature" that it checks that the string given for the %Ns
parameter consists of a whole number of characters in the current
encoding. So, unless you are sure you are always going to be in an
UTF-8 locale or your know your text is restricted to ASCII, avoid
using %Ns. If your intention is to format strings for a
certain number of columns, then %Ns is not a correct solution
anyway, since it fails to take wide characters (see <link linkend="g-unichar-iswide"><function>g_unichar_iswide()</function></link>)
into account.</para>
<para>Note also that there are various <link linkend="printf"><function>printf()</function></link> parameters which are platform
dependent. GLib provides platform independent macros for these parameters
which should be used instead. A common example is <link linkend="G-GUINT64-FORMAT:CAPS"><literal>G_GUINT64_FORMAT</literal></link>, which
should be used instead of <literal>%llu</literal> or similar parameters for formatting
64-bit integers. These macros are all named <literal>G_*_FORMAT</literal>; see
<link linkend="glib-Basic-Types">Basic Types</link>.</para>
</refsect3>

</refsect1>
<refsect1 id="glib-String-Utility-Functions.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="g-strdup" role="function">
<title>g_strdup&#160;()</title>
<indexterm zone="g-strdup"><primary sortas="strdup">g_strdup</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strdup (<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>);</programlisting>
<para>Duplicates a string. If <parameter>str</parameter>
 is <link linkend="NULL:CAPS"><literal>NULL</literal></link> it returns <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
The returned string should be freed with <link linkend="g-free"><function>g_free()</function></link>
when no longer needed.</para>
<refsect3 id="g-strdup.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str</para></entry>
<entry role="parameter_description"><para>the string to duplicate. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strdup.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated copy of <parameter>str</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-strndup" role="function">
<title>g_strndup&#160;()</title>
<indexterm zone="g-strndup"><primary sortas="strndup">g_strndup</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strndup (<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>,
           <parameter><link linkend="gsize"><type>gsize</type></link> n</parameter>);</programlisting>
<para>Duplicates the first <parameter>n</parameter>
 bytes of a string, returning a newly-allocated
buffer <parameter>n</parameter>
 + 1 bytes long which will always be nul-terminated. If <parameter>str</parameter>

is less than <parameter>n</parameter>
 bytes long the buffer is padded with nuls. If <parameter>str</parameter>
 is
<link linkend="NULL:CAPS"><literal>NULL</literal></link> it returns <link linkend="NULL:CAPS"><literal>NULL</literal></link>. The returned value should be freed when no longer
needed.</para>
<para>To copy a number of characters from a UTF-8 encoded string,
use <link linkend="g-utf8-strncpy"><function>g_utf8_strncpy()</function></link> instead.</para>
<refsect3 id="g-strndup.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str</para></entry>
<entry role="parameter_description"><para>the string to duplicate</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>n</para></entry>
<entry role="parameter_description"><para>the maximum number of bytes to copy from <parameter>str</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strndup.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated buffer containing the first <parameter>n</parameter>
bytes
of <parameter>str</parameter>
, nul-terminated</para>
</refsect3></refsect2>
<refsect2 id="g-strdupv" role="function">
<title>g_strdupv&#160;()</title>
<indexterm zone="g-strdupv"><primary sortas="strdupv">g_strdupv</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
g_strdupv (<parameter><link linkend="gchar"><type>gchar</type></link> **str_array</parameter>);</programlisting>
<para>Copies <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings. The copy is a deep copy;
the new array should be freed by first freeing each string, then
the array itself. <link linkend="g-strfreev"><function>g_strfreev()</function></link> does this for you. If called
on a <link linkend="NULL:CAPS"><literal>NULL</literal></link> value, <link linkend="g-strdupv"><function>g_strdupv()</function></link> simply returns <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
<refsect3 id="g-strdupv.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str_array</para></entry>
<entry role="parameter_description"><para>a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strdupv.returns" role="returns">
<title>Returns</title>
<para>a new <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-strnfill" role="function">
<title>g_strnfill&#160;()</title>
<indexterm zone="g-strnfill"><primary sortas="strnfill">g_strnfill</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strnfill (<parameter><link linkend="gsize"><type>gsize</type></link> length</parameter>,
            <parameter><link linkend="gchar"><type>gchar</type></link> fill_char</parameter>);</programlisting>
<para>Creates a new string <parameter>length</parameter>
 bytes long filled with <parameter>fill_char</parameter>
.
The returned string should be freed when no longer needed.</para>
<refsect3 id="g-strnfill.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>the length of the new string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>fill_char</para></entry>
<entry role="parameter_description"><para>the byte to fill the string with</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strnfill.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated string filled the <parameter>fill_char</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-stpcpy" role="function">
<title>g_stpcpy&#160;()</title>
<indexterm zone="g-stpcpy"><primary sortas="stpcpy">g_stpcpy</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_stpcpy (<parameter><link linkend="gchar"><type>gchar</type></link> *dest</parameter>,
          <parameter>const <link linkend="char"><type>char</type></link> *src</parameter>);</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>
<refsect3 id="g-stpcpy.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>dest</para></entry>
<entry role="parameter_description"><para>destination buffer.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>src</para></entry>
<entry role="parameter_description"><para>source string.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-stpcpy.returns" role="returns">
<title>Returns</title>
<para> a pointer to trailing nul byte.</para>
</refsect3></refsect2>
<refsect2 id="g-strstr-len" role="function">
<title>g_strstr_len&#160;()</title>
<indexterm zone="g-strstr-len"><primary sortas="strstr_len">g_strstr_len</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strstr_len (<parameter>const <link linkend="gchar"><type>gchar</type></link> *haystack</parameter>,
              <parameter><link linkend="gssize"><type>gssize</type></link> haystack_len</parameter>,
              <parameter>const <link linkend="gchar"><type>gchar</type></link> *needle</parameter>);</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>
<refsect3 id="g-strstr-len.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>haystack</para></entry>
<entry role="parameter_description"><para>a string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>haystack_len</para></entry>
<entry role="parameter_description"><para>the maximum length of <parameter>haystack</parameter>
. Note that -1 is
a valid length, if <parameter>haystack</parameter>
is nul-terminated, meaning it will
search through the whole string.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>needle</para></entry>
<entry role="parameter_description"><para>the string to search for</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strstr-len.returns" role="returns">
<title>Returns</title>
<para> a pointer to the found occurrence, or
<link linkend="NULL:CAPS"><literal>NULL</literal></link> if not found.</para>
</refsect3></refsect2>
<refsect2 id="g-strrstr" role="function">
<title>g_strrstr&#160;()</title>
<indexterm zone="g-strrstr"><primary sortas="strrstr">g_strrstr</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strrstr (<parameter>const <link linkend="gchar"><type>gchar</type></link> *haystack</parameter>,
           <parameter>const <link linkend="gchar"><type>gchar</type></link> *needle</parameter>);</programlisting>
<para>Searches the string <parameter>haystack</parameter>
 for the last occurrence
of the string <parameter>needle</parameter>
.</para>
<refsect3 id="g-strrstr.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>haystack</para></entry>
<entry role="parameter_description"><para>a nul-terminated string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>needle</para></entry>
<entry role="parameter_description"><para>the nul-terminated string to search for</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strrstr.returns" role="returns">
<title>Returns</title>
<para> a pointer to the found occurrence, or
<link linkend="NULL:CAPS"><literal>NULL</literal></link> if not found.</para>
</refsect3></refsect2>
<refsect2 id="g-strrstr-len" role="function">
<title>g_strrstr_len&#160;()</title>
<indexterm zone="g-strrstr-len"><primary sortas="strrstr_len">g_strrstr_len</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strrstr_len (<parameter>const <link linkend="gchar"><type>gchar</type></link> *haystack</parameter>,
               <parameter><link linkend="gssize"><type>gssize</type></link> haystack_len</parameter>,
               <parameter>const <link linkend="gchar"><type>gchar</type></link> *needle</parameter>);</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>
<refsect3 id="g-strrstr-len.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>haystack</para></entry>
<entry role="parameter_description"><para>a nul-terminated string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>haystack_len</para></entry>
<entry role="parameter_description"><para>the maximum length of <parameter>haystack</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>needle</para></entry>
<entry role="parameter_description"><para>the nul-terminated string to search for</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strrstr-len.returns" role="returns">
<title>Returns</title>
<para> a pointer to the found occurrence, or
<link linkend="NULL:CAPS"><literal>NULL</literal></link> if not found.</para>
</refsect3></refsect2>
<refsect2 id="g-str-has-prefix" role="function" condition="since:2.2">
<title>g_str_has_prefix&#160;()</title>
<indexterm zone="g-str-has-prefix" role="2.2"><primary sortas="str_has_prefix">g_str_has_prefix</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_str_has_prefix (<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>,
                  <parameter>const <link linkend="gchar"><type>gchar</type></link> *prefix</parameter>);</programlisting>
<para>Looks whether the string <parameter>str</parameter>
 begins with <parameter>prefix</parameter>
.</para>
<refsect3 id="g-str-has-prefix.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str</para></entry>
<entry role="parameter_description"><para>a nul-terminated string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>prefix</para></entry>
<entry role="parameter_description"><para>the nul-terminated prefix to look for</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-str-has-prefix.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter>
begins with <parameter>prefix</parameter>
, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.2">2.2</link></para></refsect2>
<refsect2 id="g-str-has-suffix" role="function" condition="since:2.2">
<title>g_str_has_suffix&#160;()</title>
<indexterm zone="g-str-has-suffix" role="2.2"><primary sortas="str_has_suffix">g_str_has_suffix</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_str_has_suffix (<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>,
                  <parameter>const <link linkend="gchar"><type>gchar</type></link> *suffix</parameter>);</programlisting>
<para>Looks whether the string <parameter>str</parameter>
 ends with <parameter>suffix</parameter>
.</para>
<refsect3 id="g-str-has-suffix.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str</para></entry>
<entry role="parameter_description"><para>a nul-terminated string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>suffix</para></entry>
<entry role="parameter_description"><para>the nul-terminated suffix to look for</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-str-has-suffix.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter>
end with <parameter>suffix</parameter>
, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.2">2.2</link></para></refsect2>
<refsect2 id="g-strcmp0" role="function" condition="since:2.16">
<title>g_strcmp0&#160;()</title>
<indexterm zone="g-strcmp0" role="2.16"><primary sortas="strcmp0">g_strcmp0</primary></indexterm>
<programlisting language="C"><link linkend="int"><returnvalue>int</returnvalue></link>
g_strcmp0 (<parameter>const <link linkend="char"><type>char</type></link> *str1</parameter>,
           <parameter>const <link linkend="char"><type>char</type></link> *str2</parameter>);</programlisting>
<para>Compares <parameter>str1</parameter>
 and <parameter>str2</parameter>
 like <link linkend="strcmp"><function>strcmp()</function></link>. Handles <link linkend="NULL:CAPS"><literal>NULL</literal></link>
gracefully by sorting it before non-<link linkend="NULL:CAPS"><literal>NULL</literal></link> strings.
Comparing two <link linkend="NULL:CAPS"><literal>NULL</literal></link> pointers returns 0.</para>
<refsect3 id="g-strcmp0.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str1</para></entry>
<entry role="parameter_description"><para>a C string or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>str2</para></entry>
<entry role="parameter_description"><para>another C string or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strcmp0.returns" role="returns">
<title>Returns</title>
<para> an integer less than, equal to, or greater than zero, if <parameter>str1</parameter>
is &lt;, == or &gt; than <parameter>str2</parameter>
.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.16">2.16</link></para></refsect2>
<refsect2 id="g-str-to-ascii" role="function" condition="since:2.40">
<title>g_str_to_ascii&#160;()</title>
<indexterm zone="g-str-to-ascii" role="2.40"><primary sortas="str_to_ascii">g_str_to_ascii</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_str_to_ascii (<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>,
                <parameter>const <link linkend="gchar"><type>gchar</type></link> *from_locale</parameter>);</programlisting>
<para>Transliterate <parameter>str</parameter>
 to plain ASCII.</para>
<para>For best results, <parameter>str</parameter>
 should be in composed normalised form.</para>
<para>This function performs a reasonably good set of character
replacements.  The particular set of replacements that is done may
change by version or even by runtime environment.</para>
<para>If the source language of <parameter>str</parameter>
 is known, it can used to improve the
accuracy of the translation by passing it as <parameter>from_locale</parameter>
.  It should
be a valid POSIX locale string (of the form
<literal>language[_territory][.codeset][@modifier]</literal>).</para>
<para>If <parameter>from_locale</parameter>
 is <link linkend="NULL:CAPS"><literal>NULL</literal></link> then the current locale is used.</para>
<para>If you want to do translation for no specific locale, and you want it
to be done independently of the currently locale, specify <literal>"C"</literal> for
<parameter>from_locale</parameter>
.</para>
<refsect3 id="g-str-to-ascii.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str</para></entry>
<entry role="parameter_description"><para>a string, in UTF-8</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>from_locale</para></entry>
<entry role="parameter_description"><para>the source locale, if known. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-str-to-ascii.returns" role="returns">
<title>Returns</title>
<para> a string in plain ASCII</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.40">2.40</link></para></refsect2>
<refsect2 id="g-str-tokenize-and-fold" role="function" condition="since:2.40">
<title>g_str_tokenize_and_fold&#160;()</title>
<indexterm zone="g-str-tokenize-and-fold" role="2.40"><primary sortas="str_tokenize_and_fold">g_str_tokenize_and_fold</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
g_str_tokenize_and_fold (<parameter>const <link linkend="gchar"><type>gchar</type></link> *string</parameter>,
                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *translit_locale</parameter>,
                         <parameter><link linkend="gchar"><type>gchar</type></link> ***ascii_alternates</parameter>);</programlisting>
<para>Tokenises <parameter>string</parameter>
 and performs folding on each token.</para>
<para>A token is a non-empty sequence of alphanumeric characters in the
source string, separated by non-alphanumeric characters.  An
"alphanumeric" character for this purpose is one that matches
<link linkend="g-unichar-isalnum"><function>g_unichar_isalnum()</function></link> or <link linkend="g-unichar-ismark"><function>g_unichar_ismark()</function></link>.</para>
<para>Each token is then (Unicode) normalised and case-folded.  If
<parameter>ascii_alternates</parameter>
 is non-<link linkend="NULL:CAPS"><literal>NULL</literal></link> and some of the returned tokens
contain non-ASCII characters, ASCII alternatives will be generated.</para>
<para>The number of ASCII alternatives that are generated and the method
for doing so is unspecified, but <parameter>translit_locale</parameter>
 (if specified) may
improve the transliteration if the language of the source string is
known.</para>
<refsect3 id="g-str-tokenize-and-fold.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>translit_locale</para></entry>
<entry role="parameter_description"><para>the language code (like 'de' or
'en_GB') from which <parameter>string</parameter>
originates. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>ascii_alternates</para></entry>
<entry role="parameter_description"><para>a
return location for ASCII alternates. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>transfer full</acronym>][<acronym>array</acronym> zero-terminated=1]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-str-tokenize-and-fold.returns" role="returns">
<title>Returns</title>
<para>the folded tokens. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>][<acronym>array</acronym> zero-terminated=1]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.40">2.40</link></para></refsect2>
<refsect2 id="g-str-match-string" role="function" condition="since:2.40">
<title>g_str_match_string&#160;()</title>
<indexterm zone="g-str-match-string" role="2.40"><primary sortas="str_match_string">g_str_match_string</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_str_match_string (<parameter>const <link linkend="gchar"><type>gchar</type></link> *search_term</parameter>,
                    <parameter>const <link linkend="gchar"><type>gchar</type></link> *potential_hit</parameter>,
                    <parameter><link linkend="gboolean"><type>gboolean</type></link> accept_alternates</parameter>);</programlisting>
<para>Checks if a search conducted for <parameter>search_term</parameter>
 should match
<parameter>potential_hit</parameter>
.</para>
<para>This function calls <link linkend="g-str-tokenize-and-fold"><function>g_str_tokenize_and_fold()</function></link> on both
<parameter>search_term</parameter>
 and <parameter>potential_hit</parameter>
.  ASCII alternates are never taken
for <parameter>search_term</parameter>
 but will be taken for <parameter>potential_hit</parameter>
 according to
the value of <parameter>accept_alternates</parameter>
.</para>
<para>A hit occurs when each folded token in <parameter>search_term</parameter>
 is a prefix of a
folded token from <parameter>potential_hit</parameter>
.</para>
<para>Depending on how you're performing the search, it will typically be
faster to call <link linkend="g-str-tokenize-and-fold"><function>g_str_tokenize_and_fold()</function></link> on each string in
your corpus and build an index on the returned folded tokens, then
call <link linkend="g-str-tokenize-and-fold"><function>g_str_tokenize_and_fold()</function></link> on the search term and
perform lookups into that index.</para>
<para>As some examples, searching for ‘fred’ would match the potential hit
‘Smith, Fred’ and also ‘Frédéric’.  Searching for ‘Fréd’ would match
‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of
accent matching).  Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo
Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix).</para>
<refsect3 id="g-str-match-string.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>search_term</para></entry>
<entry role="parameter_description"><para>the search term from the user</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>potential_hit</para></entry>
<entry role="parameter_description"><para>the text that may be a hit</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>accept_alternates</para></entry>
<entry role="parameter_description"><para><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to accept ASCII alternates</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-str-match-string.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>potential_hit</parameter>
is a hit</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.40">2.40</link></para></refsect2>
<refsect2 id="g-strlcpy" role="function">
<title>g_strlcpy&#160;()</title>
<indexterm zone="g-strlcpy"><primary sortas="strlcpy">g_strlcpy</primary></indexterm>
<programlisting language="C"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
g_strlcpy (<parameter><link linkend="gchar"><type>gchar</type></link> *dest</parameter>,
           <parameter>const <link linkend="gchar"><type>gchar</type></link> *src</parameter>,
           <parameter><link linkend="gsize"><type>gsize</type></link> dest_size</parameter>);</programlisting>
<para>Portability wrapper that calls <link linkend="strlcpy"><function>strlcpy()</function></link> on systems which have it,
and emulates <link linkend="strlcpy"><function>strlcpy()</function></link> otherwise. Copies <parameter>src</parameter>
 to <parameter>dest</parameter>
; <parameter>dest</parameter>
 is
guaranteed to be nul-terminated; <parameter>src</parameter>
 must be nul-terminated;
<parameter>dest_size</parameter>
 is the buffer size, not the number of bytes to copy.</para>
<para>At most <parameter>dest_size</parameter>
 - 1 characters will be copied. Always nul-terminates
(unless <parameter>dest_size</parameter>
 is 0). This function does not allocate memory. Unlike
<link linkend="strncpy"><function>strncpy()</function></link>, this function doesn't pad <parameter>dest</parameter>
 (so it's often faster). It
returns the size of the attempted result, strlen (src), so if
<parameter>retval</parameter>
 &gt;= <parameter>dest_size</parameter>
, truncation occurred.</para>
<para>Caveat: <link linkend="strlcpy"><function>strlcpy()</function></link> is supposedly more secure than <link linkend="strcpy"><function>strcpy()</function></link> or <link linkend="strncpy"><function>strncpy()</function></link>,
but if you really want to avoid screwups, <link linkend="g-strdup"><function>g_strdup()</function></link> is an even better
idea.</para>
<refsect3 id="g-strlcpy.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>dest</para></entry>
<entry role="parameter_description"><para>destination buffer</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>src</para></entry>
<entry role="parameter_description"><para>source buffer</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dest_size</para></entry>
<entry role="parameter_description"><para>length of <parameter>dest</parameter>
in bytes</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strlcpy.returns" role="returns">
<title>Returns</title>
<para> length of <parameter>src</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-strlcat" role="function">
<title>g_strlcat&#160;()</title>
<indexterm zone="g-strlcat"><primary sortas="strlcat">g_strlcat</primary></indexterm>
<programlisting language="C"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
g_strlcat (<parameter><link linkend="gchar"><type>gchar</type></link> *dest</parameter>,
           <parameter>const <link linkend="gchar"><type>gchar</type></link> *src</parameter>,
           <parameter><link linkend="gsize"><type>gsize</type></link> dest_size</parameter>);</programlisting>
<para>Portability wrapper that calls <link linkend="strlcat"><function>strlcat()</function></link> on systems which have it,
and emulates it otherwise. Appends nul-terminated <parameter>src</parameter>
 string to <parameter>dest</parameter>
,
guaranteeing nul-termination for <parameter>dest</parameter>
. The total size of <parameter>dest</parameter>
 won't
exceed <parameter>dest_size</parameter>
.</para>
<para>At most <parameter>dest_size</parameter>
 - 1 characters will be copied. Unlike <link linkend="strncat"><function>strncat()</function></link>,
<parameter>dest_size</parameter>
 is the full size of dest, not the space left over. This
function does not allocate memory. It always nul-terminates (unless
<parameter>dest_size</parameter>
 == 0 or there were no nul characters in the <parameter>dest_size</parameter>

characters of dest to start with).</para>
<para>Caveat: this is supposedly a more secure alternative to <link linkend="strcat"><function>strcat()</function></link> or
<link linkend="strncat"><function>strncat()</function></link>, but for real security <link linkend="g-strconcat"><function>g_strconcat()</function></link> is harder to mess up.</para>
<refsect3 id="g-strlcat.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>dest</para></entry>
<entry role="parameter_description"><para>destination buffer, already containing one nul-terminated string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>src</para></entry>
<entry role="parameter_description"><para>source buffer</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dest_size</para></entry>
<entry role="parameter_description"><para>length of <parameter>dest</parameter>
buffer in bytes (not length of existing string
inside <parameter>dest</parameter>
)</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strlcat.returns" role="returns">
<title>Returns</title>
<para> size of attempted result, which is MIN (dest_size, strlen
(original dest)) + strlen (src), so if retval &gt;= dest_size,
truncation occurred.</para>
</refsect3></refsect2>
<refsect2 id="g-strdup-printf" role="function">
<title>g_strdup_printf&#160;()</title>
<indexterm zone="g-strdup-printf"><primary sortas="strdup_printf">g_strdup_printf</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strdup_printf (<parameter>const <link linkend="gchar"><type>gchar</type></link> *format</parameter>,
                 <parameter>...</parameter>);</programlisting>
<para>Similar to the standard C <link linkend="sprintf"><function>sprintf()</function></link> function but safer, since it
calculates the maximum space required and allocates memory to hold
the result. The returned string should be freed with <link linkend="g-free"><function>g_free()</function></link> when no
longer needed.</para>
<refsect3 id="g-strdup-printf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>the parameters to insert into the format string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strdup-printf.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated string holding the result</para>
</refsect3></refsect2>
<refsect2 id="g-strdup-vprintf" role="function">
<title>g_strdup_vprintf&#160;()</title>
<indexterm zone="g-strdup-vprintf"><primary sortas="strdup_vprintf">g_strdup_vprintf</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strdup_vprintf (<parameter>const <link linkend="gchar"><type>gchar</type></link> *format</parameter>,
                  <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);</programlisting>
<para>Similar to the standard C <link linkend="vsprintf"><function>vsprintf()</function></link> function but safer, since it
calculates the maximum space required and allocates memory to hold
the result. The returned string should be freed with <link linkend="g-free"><function>g_free()</function></link> when
no longer needed.</para>
<para>See also <link linkend="g-vasprintf"><function>g_vasprintf()</function></link>, which offers the same functionality, but
additionally returns the length of the allocated string.</para>
<refsect3 id="g-strdup-vprintf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>args</para></entry>
<entry role="parameter_description"><para>the list of parameters to insert into the format string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strdup-vprintf.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated string holding the result</para>
</refsect3></refsect2>
<refsect2 id="g-printf" role="function" condition="since:2.2">
<title>g_printf&#160;()</title>
<indexterm zone="g-printf" role="2.2"><primary sortas="printf">g_printf</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_printf (<parameter><link linkend="gchar"><type>gchar</type></link> const *format</parameter>,
          <parameter>...</parameter>);</programlisting>
<para>An implementation of the standard <link linkend="printf"><function>printf()</function></link> function which supports 
positional parameters, as specified in the Single Unix Specification.</para>
<para>As with the standard <link linkend="printf"><function>printf()</function></link>, this does not automatically append a trailing
new-line character to the message, so typically <parameter>format</parameter>
 should end with its
own new-line character.</para>
<para><literal>glib/gprintf.h</literal> must be explicitly included in order to use this function.</para>
<refsect3 id="g-printf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>the arguments to insert in the output.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-printf.returns" role="returns">
<title>Returns</title>
<para> the number of bytes printed.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.2">2.2</link></para></refsect2>
<refsect2 id="g-vprintf" role="function" condition="since:2.2">
<title>g_vprintf&#160;()</title>
<indexterm zone="g-vprintf" role="2.2"><primary sortas="vprintf">g_vprintf</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_vprintf (<parameter><link linkend="gchar"><type>gchar</type></link> const *format</parameter>,
           <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);</programlisting>
<para>An implementation of the standard <link linkend="vprintf"><function>vprintf()</function></link> function which supports 
positional parameters, as specified in the Single Unix Specification.</para>
<para><literal>glib/gprintf.h</literal> must be explicitly included in order to use this function.</para>
<refsect3 id="g-vprintf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>args</para></entry>
<entry role="parameter_description"><para>the list of arguments to insert in the output.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-vprintf.returns" role="returns">
<title>Returns</title>
<para> the number of bytes printed.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.2">2.2</link></para></refsect2>
<refsect2 id="g-fprintf" role="function" condition="since:2.2">
<title>g_fprintf&#160;()</title>
<indexterm zone="g-fprintf" role="2.2"><primary sortas="fprintf">g_fprintf</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_fprintf (<parameter><link linkend="FILE:CAPS"><type>FILE</type></link> *file</parameter>,
           <parameter><link linkend="gchar"><type>gchar</type></link> const *format</parameter>,
           <parameter>...</parameter>);</programlisting>
<para>An implementation of the standard <link linkend="fprintf"><function>fprintf()</function></link> function which supports 
positional parameters, as specified in the Single Unix Specification.</para>
<para><literal>glib/gprintf.h</literal> must be explicitly included in order to use this function.</para>
<refsect3 id="g-fprintf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>file</para></entry>
<entry role="parameter_description"><para>the stream to write to. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>the arguments to insert in the output.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-fprintf.returns" role="returns">
<title>Returns</title>
<para> the number of bytes printed.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.2">2.2</link></para></refsect2>
<refsect2 id="g-vfprintf" role="function" condition="since:2.2">
<title>g_vfprintf&#160;()</title>
<indexterm zone="g-vfprintf" role="2.2"><primary sortas="vfprintf">g_vfprintf</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_vfprintf (<parameter><link linkend="FILE:CAPS"><type>FILE</type></link> *file</parameter>,
            <parameter><link linkend="gchar"><type>gchar</type></link> const *format</parameter>,
            <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);</programlisting>
<para>An implementation of the standard <link linkend="fprintf"><function>fprintf()</function></link> function which supports 
positional parameters, as specified in the Single Unix Specification.</para>
<para><literal>glib/gprintf.h</literal> must be explicitly included in order to use this function.</para>
<refsect3 id="g-vfprintf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>file</para></entry>
<entry role="parameter_description"><para>the stream to write to. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>args</para></entry>
<entry role="parameter_description"><para>the list of arguments to insert in the output.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-vfprintf.returns" role="returns">
<title>Returns</title>
<para> the number of bytes printed.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.2">2.2</link></para></refsect2>
<refsect2 id="g-sprintf" role="function" condition="since:2.2">
<title>g_sprintf&#160;()</title>
<indexterm zone="g-sprintf" role="2.2"><primary sortas="sprintf">g_sprintf</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_sprintf (<parameter><link linkend="gchar"><type>gchar</type></link> *string</parameter>,
           <parameter><link linkend="gchar"><type>gchar</type></link> const *format</parameter>,
           <parameter>...</parameter>);</programlisting>
<para>An implementation of the standard <link linkend="sprintf"><function>sprintf()</function></link> function which supports
positional parameters, as specified in the Single Unix Specification.</para>
<para>Note that it is usually better to use <link linkend="g-snprintf"><function>g_snprintf()</function></link>, to avoid the
risk of buffer overflow.</para>
<para><literal>glib/gprintf.h</literal> must be explicitly included in order to use this function.</para>
<para>See also <link linkend="g-strdup-printf"><function>g_strdup_printf()</function></link>.</para>
<refsect3 id="g-sprintf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>A pointer to a memory buffer to contain the resulting string. It
is up to the caller to ensure that the allocated buffer is large
enough to hold the formatted result</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>the arguments to insert in the output.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-sprintf.returns" role="returns">
<title>Returns</title>
<para> the number of bytes printed.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.2">2.2</link></para></refsect2>
<refsect2 id="g-vsprintf" role="function" condition="since:2.2">
<title>g_vsprintf&#160;()</title>
<indexterm zone="g-vsprintf" role="2.2"><primary sortas="vsprintf">g_vsprintf</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_vsprintf (<parameter><link linkend="gchar"><type>gchar</type></link> *string</parameter>,
            <parameter><link linkend="gchar"><type>gchar</type></link> const *format</parameter>,
            <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);</programlisting>
<para>An implementation of the standard <link linkend="vsprintf"><function>vsprintf()</function></link> function which supports 
positional parameters, as specified in the Single Unix Specification.</para>
<para><literal>glib/gprintf.h</literal> must be explicitly included in order to use this function.</para>
<refsect3 id="g-vsprintf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the buffer to hold the output.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>args</para></entry>
<entry role="parameter_description"><para>the list of arguments to insert in the output.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-vsprintf.returns" role="returns">
<title>Returns</title>
<para> the number of bytes printed.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.2">2.2</link></para></refsect2>
<refsect2 id="g-snprintf" role="function">
<title>g_snprintf&#160;()</title>
<indexterm zone="g-snprintf"><primary sortas="snprintf">g_snprintf</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_snprintf (<parameter><link linkend="gchar"><type>gchar</type></link> *string</parameter>,
            <parameter><link linkend="gulong"><type>gulong</type></link> n</parameter>,
            <parameter><link linkend="gchar"><type>gchar</type></link> const *format</parameter>,
            <parameter>...</parameter>);</programlisting>
<para>A safer form of the standard <link linkend="sprintf"><function>sprintf()</function></link> function. The output is guaranteed
to not exceed <parameter>n</parameter>
 characters (including the terminating nul character), so
it is easy to ensure that a buffer overflow cannot occur.</para>
<para>See also <link linkend="g-strdup-printf"><function>g_strdup_printf()</function></link>.</para>
<para>In versions of GLib prior to 1.2.3, this function may return -1 if the
output was truncated, and the truncated string may not be nul-terminated.
In versions prior to 1.3.12, this function returns the length of the output
string.</para>
<para>The return value of <link linkend="g-snprintf"><function>g_snprintf()</function></link> conforms to the <link linkend="snprintf"><function>snprintf()</function></link>
function as standardized in ISO C99. Note that this is different from
traditional <link linkend="snprintf"><function>snprintf()</function></link>, which returns the length of the output string.</para>
<para>The format string may contain positional parameters, as specified in
the Single Unix Specification.</para>
<refsect3 id="g-snprintf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the buffer to hold the output.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>n</para></entry>
<entry role="parameter_description"><para>the maximum number of bytes to produce (including the
terminating nul character).</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>the arguments to insert in the output.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-snprintf.returns" role="returns">
<title>Returns</title>
<para> the number of bytes which would be produced if the buffer
was large enough.</para>
</refsect3></refsect2>
<refsect2 id="g-vsnprintf" role="function">
<title>g_vsnprintf&#160;()</title>
<indexterm zone="g-vsnprintf"><primary sortas="vsnprintf">g_vsnprintf</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_vsnprintf (<parameter><link linkend="gchar"><type>gchar</type></link> *string</parameter>,
             <parameter><link linkend="gulong"><type>gulong</type></link> n</parameter>,
             <parameter><link linkend="gchar"><type>gchar</type></link> const *format</parameter>,
             <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);</programlisting>
<para>A safer form of the standard <link linkend="vsprintf"><function>vsprintf()</function></link> function. The output is guaranteed
to not exceed <parameter>n</parameter>
 characters (including the terminating nul character), so 
it is easy to ensure that a buffer overflow cannot occur.</para>
<para>See also <link linkend="g-strdup-vprintf"><function>g_strdup_vprintf()</function></link>.</para>
<para>In versions of GLib prior to 1.2.3, this function may return -1 if the 
output was truncated, and the truncated string may not be nul-terminated.
In versions prior to 1.3.12, this function returns the length of the output 
string.</para>
<para>The return value of <link linkend="g-vsnprintf"><function>g_vsnprintf()</function></link> conforms to the <link linkend="vsnprintf"><function>vsnprintf()</function></link> function 
as standardized in ISO C99. Note that this is different from traditional 
<link linkend="vsnprintf"><function>vsnprintf()</function></link>, which returns the length of the output string.</para>
<para>The format string may contain positional parameters, as specified in 
the Single Unix Specification.</para>
<refsect3 id="g-vsnprintf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the buffer to hold the output.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>n</para></entry>
<entry role="parameter_description"><para>the maximum number of bytes to produce (including the
terminating nul character).</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
string precision pitfalls][string-precision]</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>args</para></entry>
<entry role="parameter_description"><para>the list of arguments to insert in the output.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-vsnprintf.returns" role="returns">
<title>Returns</title>
<para> the number of bytes which would be produced if the buffer
was large enough.</para>
</refsect3></refsect2>
<refsect2 id="g-vasprintf" role="function" condition="since:2.4">
<title>g_vasprintf&#160;()</title>
<indexterm zone="g-vasprintf" role="2.4"><primary sortas="vasprintf">g_vasprintf</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_vasprintf (<parameter><link linkend="gchar"><type>gchar</type></link> **string</parameter>,
             <parameter><link linkend="gchar"><type>gchar</type></link> const *format</parameter>,
             <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);</programlisting>
<para>An implementation of the GNU <link linkend="vasprintf"><function>vasprintf()</function></link> function which supports 
positional parameters, as specified in the Single Unix Specification.
This function is similar to <link linkend="g-vsprintf"><function>g_vsprintf()</function></link>, except that it allocates a 
string to hold the output, instead of putting the output in a buffer 
you allocate in advance.</para>
<para><literal>glib/gprintf.h</literal> must be explicitly included in order to use this function.</para>
<refsect3 id="g-vasprintf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the return location for the newly-allocated string.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
<link linkend="string-precision">string precision pitfalls</link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>args</para></entry>
<entry role="parameter_description"><para>the list of arguments to insert in the output.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-vasprintf.returns" role="returns">
<title>Returns</title>
<para> the number of bytes printed.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-printf-string-upper-bound" role="function">
<title>g_printf_string_upper_bound&#160;()</title>
<indexterm zone="g-printf-string-upper-bound"><primary sortas="printf_string_upper_bound">g_printf_string_upper_bound</primary></indexterm>
<programlisting language="C"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
g_printf_string_upper_bound (<parameter>const <link linkend="gchar"><type>gchar</type></link> *format</parameter>,
                             <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);</programlisting>
<para>Calculates the maximum space needed to store the output
of the <link linkend="sprintf"><function>sprintf()</function></link> function.</para>
<refsect3 id="g-printf-string-upper-bound.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>the format string. See the <link linkend="printf"><function>printf()</function></link> documentation</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>args</para></entry>
<entry role="parameter_description"><para>the parameters to be inserted into the format string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-printf-string-upper-bound.returns" role="returns">
<title>Returns</title>
<para> the maximum space needed to store the formatted string</para>
</refsect3></refsect2>
<refsect2 id="g-str-is-ascii" role="function" condition="since:2.40">
<title>g_str_is_ascii&#160;()</title>
<indexterm zone="g-str-is-ascii" role="2.40"><primary sortas="str_is_ascii">g_str_is_ascii</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_str_is_ascii (<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>);</programlisting>
<para>Determines if a string is pure ASCII. A string is pure ASCII if it
contains no bytes with the high bit set.</para>
<refsect3 id="g-str-is-ascii.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str</para></entry>
<entry role="parameter_description"><para>a string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-str-is-ascii.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter>
is ASCII</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.40">2.40</link></para></refsect2>
<refsect2 id="g-ascii-isalnum" role="function">
<title>g_ascii_isalnum&#160;()</title>
<indexterm zone="g-ascii-isalnum"><primary sortas="ascii_isalnum">g_ascii_isalnum</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_ascii_isalnum (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Determines whether a character is alphanumeric.</para>
<para>Unlike the standard C library <link linkend="isalnum"><function>isalnum()</function></link> function, this only
recognizes standard ASCII letters and ignores the locale,
returning <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also, unlike
the standard library function, this takes a char, not an int,
so don't call it on <link linkend="EOF:CAPS"><literal>EOF</literal></link>, but no need to cast to <link linkend="guchar"><type>guchar</type></link> before
passing a possibly non-ASCII character in.</para>
<refsect3 id="g-ascii-isalnum.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>any character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-isalnum.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>c</parameter>
is an ASCII alphanumeric character</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-isalpha" role="function">
<title>g_ascii_isalpha&#160;()</title>
<indexterm zone="g-ascii-isalpha"><primary sortas="ascii_isalpha">g_ascii_isalpha</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_ascii_isalpha (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Determines whether a character is alphabetic (i.e. a letter).</para>
<para>Unlike the standard C library <link linkend="isalpha"><function>isalpha()</function></link> function, this only
recognizes standard ASCII letters and ignores the locale,
returning <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also, unlike
the standard library function, this takes a char, not an int,
so don't call it on <link linkend="EOF:CAPS"><literal>EOF</literal></link>, but no need to cast to <link linkend="guchar"><type>guchar</type></link> before
passing a possibly non-ASCII character in.</para>
<refsect3 id="g-ascii-isalpha.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>any character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-isalpha.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>c</parameter>
is an ASCII alphabetic character</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-iscntrl" role="function">
<title>g_ascii_iscntrl&#160;()</title>
<indexterm zone="g-ascii-iscntrl"><primary sortas="ascii_iscntrl">g_ascii_iscntrl</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_ascii_iscntrl (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Determines whether a character is a control character.</para>
<para>Unlike the standard C library <link linkend="iscntrl"><function>iscntrl()</function></link> function, this only
recognizes standard ASCII control characters and ignores the
locale, returning <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also,
unlike the standard library function, this takes a char, not
an int, so don't call it on <link linkend="EOF:CAPS"><literal>EOF</literal></link>, but no need to cast to <link linkend="guchar"><type>guchar</type></link>
before passing a possibly non-ASCII character in.</para>
<refsect3 id="g-ascii-iscntrl.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>any character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-iscntrl.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>c</parameter>
is an ASCII control character.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-isdigit" role="function">
<title>g_ascii_isdigit&#160;()</title>
<indexterm zone="g-ascii-isdigit"><primary sortas="ascii_isdigit">g_ascii_isdigit</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_ascii_isdigit (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Determines whether a character is digit (0-9).</para>
<para>Unlike the standard C library <link linkend="isdigit"><function>isdigit()</function></link> function, this takes
a char, not an int, so don't call it  on <link linkend="EOF:CAPS"><literal>EOF</literal></link>, but no need to
cast to <link linkend="guchar"><type>guchar</type></link> before passing a possibly non-ASCII character in.</para>
<refsect3 id="g-ascii-isdigit.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>any character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-isdigit.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>c</parameter>
is an ASCII digit.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-isgraph" role="function">
<title>g_ascii_isgraph&#160;()</title>
<indexterm zone="g-ascii-isgraph"><primary sortas="ascii_isgraph">g_ascii_isgraph</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_ascii_isgraph (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Determines whether a character is a printing character and not a space.</para>
<para>Unlike the standard C library <link linkend="isgraph"><function>isgraph()</function></link> function, this only
recognizes standard ASCII characters and ignores the locale,
returning <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also, unlike
the standard library function, this takes a char, not an int,
so don't call it on <link linkend="EOF:CAPS"><literal>EOF</literal></link>, but no need to cast to <link linkend="guchar"><type>guchar</type></link> before
passing a possibly non-ASCII character in.</para>
<refsect3 id="g-ascii-isgraph.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>any character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-isgraph.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>c</parameter>
is an ASCII printing character other than space.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-islower" role="function">
<title>g_ascii_islower&#160;()</title>
<indexterm zone="g-ascii-islower"><primary sortas="ascii_islower">g_ascii_islower</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_ascii_islower (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Determines whether a character is an ASCII lower case letter.</para>
<para>Unlike the standard C library <link linkend="islower"><function>islower()</function></link> function, this only
recognizes standard ASCII letters and ignores the locale,
returning <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also, unlike
the standard library function, this takes a char, not an int,
so don't call it on <link linkend="EOF:CAPS"><literal>EOF</literal></link>, but no need to worry about casting
to <link linkend="guchar"><type>guchar</type></link> before passing a possibly non-ASCII character in.</para>
<refsect3 id="g-ascii-islower.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>any character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-islower.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>c</parameter>
is an ASCII lower case letter</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-isprint" role="function">
<title>g_ascii_isprint&#160;()</title>
<indexterm zone="g-ascii-isprint"><primary sortas="ascii_isprint">g_ascii_isprint</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_ascii_isprint (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Determines whether a character is a printing character.</para>
<para>Unlike the standard C library <link linkend="isprint"><function>isprint()</function></link> function, this only
recognizes standard ASCII characters and ignores the locale,
returning <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also, unlike
the standard library function, this takes a char, not an int,
so don't call it on <link linkend="EOF:CAPS"><literal>EOF</literal></link>, but no need to cast to <link linkend="guchar"><type>guchar</type></link> before
passing a possibly non-ASCII character in.</para>
<refsect3 id="g-ascii-isprint.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>any character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-isprint.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>c</parameter>
is an ASCII printing character.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-ispunct" role="function">
<title>g_ascii_ispunct&#160;()</title>
<indexterm zone="g-ascii-ispunct"><primary sortas="ascii_ispunct">g_ascii_ispunct</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_ascii_ispunct (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Determines whether a character is a punctuation character.</para>
<para>Unlike the standard C library <link linkend="ispunct"><function>ispunct()</function></link> function, this only
recognizes standard ASCII letters and ignores the locale,
returning <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also, unlike
the standard library function, this takes a char, not an int,
so don't call it on <link linkend="EOF:CAPS"><literal>EOF</literal></link>, but no need to cast to <link linkend="guchar"><type>guchar</type></link> before
passing a possibly non-ASCII character in.</para>
<refsect3 id="g-ascii-ispunct.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>any character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-ispunct.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>c</parameter>
is an ASCII punctuation character.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-isspace" role="function">
<title>g_ascii_isspace&#160;()</title>
<indexterm zone="g-ascii-isspace"><primary sortas="ascii_isspace">g_ascii_isspace</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_ascii_isspace (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Determines whether a character is a white-space character.</para>
<para>Unlike the standard C library <link linkend="isspace"><function>isspace()</function></link> function, this only
recognizes standard ASCII white-space and ignores the locale,
returning <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also, unlike
the standard library function, this takes a char, not an int,
so don't call it on <link linkend="EOF:CAPS"><literal>EOF</literal></link>, but no need to cast to <link linkend="guchar"><type>guchar</type></link> before
passing a possibly non-ASCII character in.</para>
<refsect3 id="g-ascii-isspace.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>any character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-isspace.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>c</parameter>
is an ASCII white-space character</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-isupper" role="function">
<title>g_ascii_isupper&#160;()</title>
<indexterm zone="g-ascii-isupper"><primary sortas="ascii_isupper">g_ascii_isupper</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_ascii_isupper (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Determines whether a character is an ASCII upper case letter.</para>
<para>Unlike the standard C library <link linkend="isupper"><function>isupper()</function></link> function, this only
recognizes standard ASCII letters and ignores the locale,
returning <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also, unlike
the standard library function, this takes a char, not an int,
so don't call it on <link linkend="EOF:CAPS"><literal>EOF</literal></link>, but no need to worry about casting
to <link linkend="guchar"><type>guchar</type></link> before passing a possibly non-ASCII character in.</para>
<refsect3 id="g-ascii-isupper.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>any character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-isupper.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>c</parameter>
is an ASCII upper case letter</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-isxdigit" role="function">
<title>g_ascii_isxdigit&#160;()</title>
<indexterm zone="g-ascii-isxdigit"><primary sortas="ascii_isxdigit">g_ascii_isxdigit</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_ascii_isxdigit (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Determines whether a character is a hexadecimal-digit character.</para>
<para>Unlike the standard C library <link linkend="isxdigit"><function>isxdigit()</function></link> function, this takes
a char, not an int, so don't call it on <link linkend="EOF:CAPS"><literal>EOF</literal></link>, but no need to
cast to <link linkend="guchar"><type>guchar</type></link> before passing a possibly non-ASCII character in.</para>
<refsect3 id="g-ascii-isxdigit.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>any character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-isxdigit.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>c</parameter>
is an ASCII hexadecimal-digit character.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-digit-value" role="function">
<title>g_ascii_digit_value&#160;()</title>
<indexterm zone="g-ascii-digit-value"><primary sortas="ascii_digit_value">g_ascii_digit_value</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_ascii_digit_value (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Determines the numeric value of a character as a decimal digit.
Differs from <link linkend="g-unichar-digit-value"><function>g_unichar_digit_value()</function></link> because it takes a char, so
there's no worry about sign extension if characters are signed.</para>
<refsect3 id="g-ascii-digit-value.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>an ASCII character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-digit-value.returns" role="returns">
<title>Returns</title>
<para> If <parameter>c</parameter>
is a decimal digit (according to <link linkend="g-ascii-isdigit"><function>g_ascii_isdigit()</function></link>),
its numeric value. Otherwise, -1.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-xdigit-value" role="function">
<title>g_ascii_xdigit_value&#160;()</title>
<indexterm zone="g-ascii-xdigit-value"><primary sortas="ascii_xdigit_value">g_ascii_xdigit_value</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_ascii_xdigit_value (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Determines the numeric value of a character as a hexidecimal
digit. Differs from <link linkend="g-unichar-xdigit-value"><function>g_unichar_xdigit_value()</function></link> because it takes
a char, so there's no worry about sign extension if characters
are signed.</para>
<refsect3 id="g-ascii-xdigit-value.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>an ASCII character.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-xdigit-value.returns" role="returns">
<title>Returns</title>
<para> If <parameter>c</parameter>
is a hex digit (according to <link linkend="g-ascii-isxdigit"><function>g_ascii_isxdigit()</function></link>),
its numeric value. Otherwise, -1.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-strcasecmp" role="function">
<title>g_ascii_strcasecmp&#160;()</title>
<indexterm zone="g-ascii-strcasecmp"><primary sortas="ascii_strcasecmp">g_ascii_strcasecmp</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_ascii_strcasecmp (<parameter>const <link linkend="gchar"><type>gchar</type></link> *s1</parameter>,
                    <parameter>const <link linkend="gchar"><type>gchar</type></link> *s2</parameter>);</programlisting>
<para>Compare two strings, ignoring the case of ASCII characters.</para>
<para>Unlike the BSD <link linkend="strcasecmp"><function>strcasecmp()</function></link> function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
bytes as if they are not letters.</para>
<para>This function should be used only on strings that are known to be
in encodings where the bytes corresponding to ASCII letters always
represent themselves. This includes UTF-8 and the ISO-8859-*
charsets, but not for instance double-byte encodings like the
Windows Codepage 932, where the trailing bytes of double-byte
characters include all ASCII letters. If you compare two CP932
strings using this function, you will get false matches.</para>
<para>Both <parameter>s1</parameter>
 and <parameter>s2</parameter>
 must be non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
<refsect3 id="g-ascii-strcasecmp.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>s1</para></entry>
<entry role="parameter_description"><para>string to compare with <parameter>s2</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>s2</para></entry>
<entry role="parameter_description"><para>string to compare with <parameter>s1</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-strcasecmp.returns" role="returns">
<title>Returns</title>
<para> 0 if the strings match, a negative value if <parameter>s1</parameter>
&lt; <parameter>s2</parameter>
,
or a positive value if <parameter>s1</parameter>
&gt; <parameter>s2</parameter>
.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-strncasecmp" role="function">
<title>g_ascii_strncasecmp&#160;()</title>
<indexterm zone="g-ascii-strncasecmp"><primary sortas="ascii_strncasecmp">g_ascii_strncasecmp</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_ascii_strncasecmp (<parameter>const <link linkend="gchar"><type>gchar</type></link> *s1</parameter>,
                     <parameter>const <link linkend="gchar"><type>gchar</type></link> *s2</parameter>,
                     <parameter><link linkend="gsize"><type>gsize</type></link> n</parameter>);</programlisting>
<para>Compare <parameter>s1</parameter>
 and <parameter>s2</parameter>
, ignoring the case of ASCII characters and any
characters after the first <parameter>n</parameter>
 in each string.</para>
<para>Unlike the BSD <link linkend="strcasecmp"><function>strcasecmp()</function></link> function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
characters as if they are not letters.</para>
<para>The same warning as in <link linkend="g-ascii-strcasecmp"><function>g_ascii_strcasecmp()</function></link> applies: Use this
function only on strings known to be in encodings where bytes
corresponding to ASCII letters always represent themselves.</para>
<refsect3 id="g-ascii-strncasecmp.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>s1</para></entry>
<entry role="parameter_description"><para>string to compare with <parameter>s2</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>s2</para></entry>
<entry role="parameter_description"><para>string to compare with <parameter>s1</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>n</para></entry>
<entry role="parameter_description"><para>number of characters to compare</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-strncasecmp.returns" role="returns">
<title>Returns</title>
<para> 0 if the strings match, a negative value if <parameter>s1</parameter>
&lt; <parameter>s2</parameter>
,
or a positive value if <parameter>s1</parameter>
&gt; <parameter>s2</parameter>
.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-strup" role="function">
<title>g_ascii_strup&#160;()</title>
<indexterm zone="g-ascii-strup"><primary sortas="ascii_strup">g_ascii_strup</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_ascii_strup (<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>,
               <parameter><link linkend="gssize"><type>gssize</type></link> len</parameter>);</programlisting>
<para>Converts all lower case ASCII letters to upper case ASCII letters.</para>
<refsect3 id="g-ascii-strup.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str</para></entry>
<entry role="parameter_description"><para>a string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>length of <parameter>str</parameter>
in bytes, or -1 if <parameter>str</parameter>
is nul-terminated</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-strup.returns" role="returns">
<title>Returns</title>
<para> a newly allocated string, with all the lower case
characters in <parameter>str</parameter>
converted to upper case, with semantics that
exactly match <link linkend="g-ascii-toupper"><function>g_ascii_toupper()</function></link>. (Note that this is unlike the
old <link linkend="g-strup"><function>g_strup()</function></link>, which modified the string in place.)</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-strdown" role="function">
<title>g_ascii_strdown&#160;()</title>
<indexterm zone="g-ascii-strdown"><primary sortas="ascii_strdown">g_ascii_strdown</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_ascii_strdown (<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>,
                 <parameter><link linkend="gssize"><type>gssize</type></link> len</parameter>);</programlisting>
<para>Converts all upper case ASCII letters to lower case ASCII letters.</para>
<refsect3 id="g-ascii-strdown.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str</para></entry>
<entry role="parameter_description"><para>a string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>length of <parameter>str</parameter>
in bytes, or -1 if <parameter>str</parameter>
is nul-terminated</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-strdown.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated string, with all the upper case
characters in <parameter>str</parameter>
converted to lower case, with semantics that
exactly match <link linkend="g-ascii-tolower"><function>g_ascii_tolower()</function></link>. (Note that this is unlike the
old <link linkend="g-strdown"><function>g_strdown()</function></link>, which modified the string in place.)</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-tolower" role="function">
<title>g_ascii_tolower&#160;()</title>
<indexterm zone="g-ascii-tolower"><primary sortas="ascii_tolower">g_ascii_tolower</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>
g_ascii_tolower (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Convert a character to ASCII lower case.</para>
<para>Unlike the standard C library <link linkend="tolower"><function>tolower()</function></link> function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are lower case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
don't call it on <link linkend="EOF:CAPS"><literal>EOF</literal></link> but no need to worry about casting to <link linkend="guchar"><type>guchar</type></link>
before passing a possibly non-ASCII character in.</para>
<refsect3 id="g-ascii-tolower.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>any character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-tolower.returns" role="returns">
<title>Returns</title>
<para> 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.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-toupper" role="function">
<title>g_ascii_toupper&#160;()</title>
<indexterm zone="g-ascii-toupper"><primary sortas="ascii_toupper">g_ascii_toupper</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>
g_ascii_toupper (<parameter><link linkend="gchar"><type>gchar</type></link> c</parameter>);</programlisting>
<para>Convert a character to ASCII upper case.</para>
<para>Unlike the standard C library <link linkend="toupper"><function>toupper()</function></link> function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are upper case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
don't call it on <link linkend="EOF:CAPS"><literal>EOF</literal></link> but no need to worry about casting to <link linkend="guchar"><type>guchar</type></link>
before passing a possibly non-ASCII character in.</para>
<refsect3 id="g-ascii-toupper.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>c</para></entry>
<entry role="parameter_description"><para>any character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-toupper.returns" role="returns">
<title>Returns</title>
<para> 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.</para>
</refsect3></refsect2>
<refsect2 id="g-string-ascii-up" role="function">
<title>g_string_ascii_up&#160;()</title>
<indexterm zone="g-string-ascii-up"><primary sortas="string_ascii_up">g_string_ascii_up</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_ascii_up (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>);</programlisting>
<para>Converts all lowercase ASCII letters to uppercase ASCII letters.</para>
<refsect3 id="g-string-ascii-up.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a GString</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-ascii-up.returns" role="returns">
<title>Returns</title>
<para>passed-in <parameter>string</parameter>
pointer, with all the
lowercase characters converted to uppercase in place,
with semantics that exactly match <link linkend="g-ascii-toupper"><function>g_ascii_toupper()</function></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-string-ascii-down" role="function">
<title>g_string_ascii_down&#160;()</title>
<indexterm zone="g-string-ascii-down"><primary sortas="string_ascii_down">g_string_ascii_down</primary></indexterm>
<programlisting language="C"><link linkend="GString"><returnvalue>GString</returnvalue></link>&#160;*
g_string_ascii_down (<parameter><link linkend="GString"><type>GString</type></link> *string</parameter>);</programlisting>
<para>Converts all uppercase ASCII letters to lowercase ASCII letters.</para>
<refsect3 id="g-string-ascii-down.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a GString</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-string-ascii-down.returns" role="returns">
<title>Returns</title>
<para>passed-in <parameter>string</parameter>
pointer, with all the
uppercase characters converted to lowercase in place,
with semantics that exactly match <link linkend="g-ascii-tolower"><function>g_ascii_tolower()</function></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-strup" role="function" condition="deprecated">
<title>g_strup&#160;()</title>
<indexterm zone="g-strup" role="deprecated"><primary sortas="strup">g_strup</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strup (<parameter><link linkend="gchar"><type>gchar</type></link> *string</parameter>);</programlisting>
<warning><para><literal>g_strup</literal> has been deprecated since version 2.2 and should not be used in newly-written code.</para> <para>This function is totally broken for the reasons
    discussed in the <link linkend="g-strncasecmp"><function>g_strncasecmp()</function></link> docs - use <link linkend="g-ascii-strup"><function>g_ascii_strup()</function></link>
    or <link linkend="g-utf8-strup"><function>g_utf8_strup()</function></link> instead.</para>
</warning>
<para>Converts a string to upper case.</para>
<refsect3 id="g-strup.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the string to convert</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strup.returns" role="returns">
<title>Returns</title>
<para> the string</para>
</refsect3></refsect2>
<refsect2 id="g-strdown" role="function" condition="deprecated">
<title>g_strdown&#160;()</title>
<indexterm zone="g-strdown" role="deprecated"><primary sortas="strdown">g_strdown</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strdown (<parameter><link linkend="gchar"><type>gchar</type></link> *string</parameter>);</programlisting>
<warning><para><literal>g_strdown</literal> has been deprecated since version 2.2 and should not be used in newly-written code.</para> <para>This function is totally broken for the reasons discussed
in the <link linkend="g-strncasecmp"><function>g_strncasecmp()</function></link> docs - use <link linkend="g-ascii-strdown"><function>g_ascii_strdown()</function></link> or <link linkend="g-utf8-strdown"><function>g_utf8_strdown()</function></link>
instead.</para>
</warning>
<para>Converts a string to lower case.</para>
<refsect3 id="g-strdown.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the string to convert.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strdown.returns" role="returns">
<title>Returns</title>
<para> the string</para>
</refsect3></refsect2>
<refsect2 id="g-strcasecmp" role="function" condition="deprecated">
<title>g_strcasecmp&#160;()</title>
<indexterm zone="g-strcasecmp" role="deprecated"><primary sortas="strcasecmp">g_strcasecmp</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_strcasecmp (<parameter>const <link linkend="gchar"><type>gchar</type></link> *s1</parameter>,
              <parameter>const <link linkend="gchar"><type>gchar</type></link> *s2</parameter>);</programlisting>
<warning><para><literal>g_strcasecmp</literal> has been deprecated since version 2.2 and should not be used in newly-written code.</para> <para>See <link linkend="g-strncasecmp"><function>g_strncasecmp()</function></link> for a discussion of why this
    function is deprecated and how to replace it.</para>
</warning>
<para>A case-insensitive string comparison, corresponding to the standard
<link linkend="strcasecmp"><function>strcasecmp()</function></link> function on platforms which support it.</para>
<refsect3 id="g-strcasecmp.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>s1</para></entry>
<entry role="parameter_description"><para>a string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>s2</para></entry>
<entry role="parameter_description"><para>a string to compare with <parameter>s1</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strcasecmp.returns" role="returns">
<title>Returns</title>
<para> 0 if the strings match, a negative value if <parameter>s1</parameter>
&lt; <parameter>s2</parameter>
,
or a positive value if <parameter>s1</parameter>
&gt; <parameter>s2</parameter>
.</para>
</refsect3></refsect2>
<refsect2 id="g-strncasecmp" role="function" condition="deprecated">
<title>g_strncasecmp&#160;()</title>
<indexterm zone="g-strncasecmp" role="deprecated"><primary sortas="strncasecmp">g_strncasecmp</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_strncasecmp (<parameter>const <link linkend="gchar"><type>gchar</type></link> *s1</parameter>,
               <parameter>const <link linkend="gchar"><type>gchar</type></link> *s2</parameter>,
               <parameter><link linkend="guint"><type>guint</type></link> n</parameter>);</programlisting>
<warning><para><literal>g_strncasecmp</literal> has been deprecated since version 2.2 and should not be used in newly-written code.</para> <para>The problem with <link linkend="g-strncasecmp"><function>g_strncasecmp()</function></link> is that it does
    the comparison by calling <link linkend="toupper"><function>toupper()</function></link>/<link linkend="tolower"><function>tolower()</function></link>. These functions
    are locale-specific and operate on single bytes. However, it is
    impossible to handle things correctly from an internationalization
    standpoint by operating on bytes, since characters may be multibyte.
    Thus <link linkend="g-strncasecmp"><function>g_strncasecmp()</function></link> is broken if your string is guaranteed to be
    ASCII, since it is 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 techniques: <link linkend="g-ascii-strncasecmp"><function>g_ascii_strncasecmp()</function></link>,
    which only works on ASCII and is not locale-sensitive, and
    <link linkend="g-utf8-casefold"><function>g_utf8_casefold()</function></link> followed by <link linkend="strcmp"><function>strcmp()</function></link> on the resulting strings,
    which is good for case-insensitive sorting of UTF-8.</para>
</warning>
<para>A case-insensitive string comparison, corresponding to the standard
<link linkend="strncasecmp"><function>strncasecmp()</function></link> function on platforms which support it. It is similar
to <link linkend="g-strcasecmp"><function>g_strcasecmp()</function></link> except it only compares the first <parameter>n</parameter>
 characters of
the strings.</para>
<refsect3 id="g-strncasecmp.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>s1</para></entry>
<entry role="parameter_description"><para>a string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>s2</para></entry>
<entry role="parameter_description"><para>a string to compare with <parameter>s1</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>n</para></entry>
<entry role="parameter_description"><para>the maximum number of characters to compare</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strncasecmp.returns" role="returns">
<title>Returns</title>
<para> 0 if the strings match, a negative value if <parameter>s1</parameter>
&lt; <parameter>s2</parameter>
,
or a positive value if <parameter>s1</parameter>
&gt; <parameter>s2</parameter>
.</para>
</refsect3></refsect2>
<refsect2 id="g-strreverse" role="function">
<title>g_strreverse&#160;()</title>
<indexterm zone="g-strreverse"><primary sortas="strreverse">g_strreverse</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strreverse (<parameter><link linkend="gchar"><type>gchar</type></link> *string</parameter>);</programlisting>
<para>Reverses all of the bytes in a string. For example,
<literal>g_strreverse ("abcdef")</literal> will result in "fedcba".</para>
<para>Note that <link linkend="g-strreverse"><function>g_strreverse()</function></link> doesn't work on UTF-8 strings
containing multibyte characters. For that purpose, use
<link linkend="g-utf8-strreverse"><function>g_utf8_strreverse()</function></link>.</para>
<refsect3 id="g-strreverse.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the string to reverse</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strreverse.returns" role="returns">
<title>Returns</title>
<para> the same pointer passed in as <parameter>string</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-strtoll" role="function" condition="since:2.12">
<title>g_ascii_strtoll&#160;()</title>
<indexterm zone="g-ascii-strtoll" role="2.12"><primary sortas="ascii_strtoll">g_ascii_strtoll</primary></indexterm>
<programlisting language="C"><link linkend="gint64"><returnvalue>gint64</returnvalue></link>
g_ascii_strtoll (<parameter>const <link linkend="gchar"><type>gchar</type></link> *nptr</parameter>,
                 <parameter><link linkend="gchar"><type>gchar</type></link> **endptr</parameter>,
                 <parameter><link linkend="guint"><type>guint</type></link> base</parameter>);</programlisting>
<para>Converts a string to a <link linkend="gint64"><type>gint64</type></link> value.
This function behaves like the standard <link linkend="strtoll"><function>strtoll()</function></link> function
does in the C locale. It does this without actually
changing the current locale, since that would not be
thread-safe.</para>
<para>This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system <link linkend="strtoll"><function>strtoll()</function></link> function.</para>
<para>If the correct value would cause overflow, <link linkend="G-MAXINT64:CAPS"><literal>G_MAXINT64</literal></link> or <link linkend="G-MININT64:CAPS"><literal>G_MININT64</literal></link>
is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
If the base is outside the valid range, zero is returned, and
<literal>EINVAL</literal> is stored in <literal>errno</literal>. If the
string conversion fails, zero is returned, and <parameter>endptr</parameter>
 returns <parameter>nptr</parameter>

(if <parameter>endptr</parameter>
 is non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>).</para>
<refsect3 id="g-ascii-strtoll.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>nptr</para></entry>
<entry role="parameter_description"><para>the string to convert to a numeric value.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>endptr</para></entry>
<entry role="parameter_description"><para>if non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>, it returns the
character after the last character used in the conversion. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>transfer none</acronym>][<acronym>optional</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>base</para></entry>
<entry role="parameter_description"><para>to be used for the conversion, 2..36 or 0</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-strtoll.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="gint64"><type>gint64</type></link> value or zero on error.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.12">2.12</link></para></refsect2>
<refsect2 id="g-ascii-strtoull" role="function" condition="since:2.2">
<title>g_ascii_strtoull&#160;()</title>
<indexterm zone="g-ascii-strtoull" role="2.2"><primary sortas="ascii_strtoull">g_ascii_strtoull</primary></indexterm>
<programlisting language="C"><link linkend="guint64"><returnvalue>guint64</returnvalue></link>
g_ascii_strtoull (<parameter>const <link linkend="gchar"><type>gchar</type></link> *nptr</parameter>,
                  <parameter><link linkend="gchar"><type>gchar</type></link> **endptr</parameter>,
                  <parameter><link linkend="guint"><type>guint</type></link> base</parameter>);</programlisting>
<para>Converts a string to a <link linkend="guint64"><type>guint64</type></link> value.
This function behaves like the standard <link linkend="strtoull"><function>strtoull()</function></link> function
does in the C locale. It does this without actually
changing the current locale, since that would not be
thread-safe.</para>
<para>Note that input with a leading minus sign (<literal>-</literal>) is accepted, and will return
the negation of the parsed number, unless that would overflow a <link linkend="guint64"><type>guint64</type></link>.
Critically, this means you cannot assume that a short fixed length input will
never result in a low return value, as the input could have a leading <literal>-</literal>.</para>
<para>This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system <link linkend="strtoull"><function>strtoull()</function></link> function.</para>
<para>If the correct value would cause overflow, <link linkend="G-MAXUINT64:CAPS"><literal>G_MAXUINT64</literal></link>
is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
If the base is outside the valid range, zero is returned, and
<literal>EINVAL</literal> is stored in <literal>errno</literal>.
If the string conversion fails, zero is returned, and <parameter>endptr</parameter>
 returns
<parameter>nptr</parameter>
 (if <parameter>endptr</parameter>
 is non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>).</para>
<refsect3 id="g-ascii-strtoull.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>nptr</para></entry>
<entry role="parameter_description"><para>the string to convert to a numeric value.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>endptr</para></entry>
<entry role="parameter_description"><para>if non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>, it returns the
character after the last character used in the conversion. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>transfer none</acronym>][<acronym>optional</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>base</para></entry>
<entry role="parameter_description"><para>to be used for the conversion, 2..36 or 0</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-strtoull.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="guint64"><type>guint64</type></link> value or zero on error.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.2">2.2</link></para></refsect2>
<refsect2 id="g-ascii-strtod" role="function">
<title>g_ascii_strtod&#160;()</title>
<indexterm zone="g-ascii-strtod"><primary sortas="ascii_strtod">g_ascii_strtod</primary></indexterm>
<programlisting language="C"><link linkend="gdouble"><returnvalue>gdouble</returnvalue></link>
g_ascii_strtod (<parameter>const <link linkend="gchar"><type>gchar</type></link> *nptr</parameter>,
                <parameter><link linkend="gchar"><type>gchar</type></link> **endptr</parameter>);</programlisting>
<para>Converts a string to a <link linkend="gdouble"><type>gdouble</type></link> value.</para>
<para>This function behaves like the standard <link linkend="strtod"><function>strtod()</function></link> function
does in the C locale. It does this without actually changing
the current locale, since that would not be thread-safe.
A limitation of the implementation is that this function
will still accept localized versions of infinities and NANs.</para>
<para>This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system <link linkend="strtod"><function>strtod()</function></link> function.</para>
<para>To convert from a <link linkend="gdouble"><type>gdouble</type></link> to a string in a locale-insensitive
way, use <link linkend="g-ascii-dtostr"><function>g_ascii_dtostr()</function></link>.</para>
<para>If the correct value would cause overflow, plus or minus <link linkend="HUGE-VAL:CAPS"><literal>HUGE_VAL</literal></link>
is returned (according to the sign of the value), and <link linkend="ERANGE:CAPS"><literal>ERANGE</literal></link> is
stored in <link linkend="errno"><literal>errno</literal></link>. If the correct value would cause underflow,
zero is returned and <link linkend="ERANGE:CAPS"><literal>ERANGE</literal></link> is stored in <link linkend="errno"><literal>errno</literal></link>.</para>
<para>This function resets <link linkend="errno"><literal>errno</literal></link> before calling <link linkend="strtod"><function>strtod()</function></link> so that
you can reliably detect overflow and underflow.</para>
<refsect3 id="g-ascii-strtod.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>nptr</para></entry>
<entry role="parameter_description"><para>the string to convert to a numeric value.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>endptr</para></entry>
<entry role="parameter_description"><para>if non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>, it returns the
character after the last character used in the conversion. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>transfer none</acronym>][<acronym>optional</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-strtod.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="gdouble"><type>gdouble</type></link> value.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-dtostr" role="function">
<title>g_ascii_dtostr&#160;()</title>
<indexterm zone="g-ascii-dtostr"><primary sortas="ascii_dtostr">g_ascii_dtostr</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_ascii_dtostr (<parameter><link linkend="gchar"><type>gchar</type></link> *buffer</parameter>,
                <parameter><link linkend="gint"><type>gint</type></link> buf_len</parameter>,
                <parameter><link linkend="gdouble"><type>gdouble</type></link> d</parameter>);</programlisting>
<para>Converts a <link linkend="gdouble"><type>gdouble</type></link> to a string, using the '.' as
decimal point.</para>
<para>This function generates enough precision that converting
the string back using <link linkend="g-ascii-strtod"><function>g_ascii_strtod()</function></link> gives the same machine-number
(on machines with IEEE compatible 64bit doubles). It is
guaranteed that the size of the resulting string will never
be larger than <parameter>G_ASCII_DTOSTR_BUF_SIZE</parameter>
 bytes, including the terminating
nul character, which is always added.</para>
<refsect3 id="g-ascii-dtostr.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>buffer</para></entry>
<entry role="parameter_description"><para>A buffer to place the resulting string in</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>buf_len</para></entry>
<entry role="parameter_description"><para>The length of the buffer.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>d</para></entry>
<entry role="parameter_description"><para>The <link linkend="gdouble"><type>gdouble</type></link> to convert</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-dtostr.returns" role="returns">
<title>Returns</title>
<para> The pointer to the buffer with the converted string.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-formatd" role="function">
<title>g_ascii_formatd&#160;()</title>
<indexterm zone="g-ascii-formatd"><primary sortas="ascii_formatd">g_ascii_formatd</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_ascii_formatd (<parameter><link linkend="gchar"><type>gchar</type></link> *buffer</parameter>,
                 <parameter><link linkend="gint"><type>gint</type></link> buf_len</parameter>,
                 <parameter>const <link linkend="gchar"><type>gchar</type></link> *format</parameter>,
                 <parameter><link linkend="gdouble"><type>gdouble</type></link> d</parameter>);</programlisting>
<para>Converts a <link linkend="gdouble"><type>gdouble</type></link> to a string, using the '.' as
decimal point. To format the number you pass in
a <link linkend="printf"><function>printf()</function></link>-style format string. Allowed conversion
specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.</para>
<para>The returned buffer is guaranteed to be nul-terminated.</para>
<para>If you just want to want to serialize the value into a
string, use <link linkend="g-ascii-dtostr"><function>g_ascii_dtostr()</function></link>.</para>
<refsect3 id="g-ascii-formatd.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>buffer</para></entry>
<entry role="parameter_description"><para>A buffer to place the resulting string in</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>buf_len</para></entry>
<entry role="parameter_description"><para>The length of the buffer.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>The <link linkend="printf"><function>printf()</function></link>-style format to use for the
code to use for converting.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>d</para></entry>
<entry role="parameter_description"><para>The <link linkend="gdouble"><type>gdouble</type></link> to convert</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-formatd.returns" role="returns">
<title>Returns</title>
<para> The pointer to the buffer with the converted string.</para>
</refsect3></refsect2>
<refsect2 id="g-strtod" role="function">
<title>g_strtod&#160;()</title>
<indexterm zone="g-strtod"><primary sortas="strtod">g_strtod</primary></indexterm>
<programlisting language="C"><link linkend="gdouble"><returnvalue>gdouble</returnvalue></link>
g_strtod (<parameter>const <link linkend="gchar"><type>gchar</type></link> *nptr</parameter>,
          <parameter><link linkend="gchar"><type>gchar</type></link> **endptr</parameter>);</programlisting>
<para>Converts a string to a <link linkend="gdouble"><type>gdouble</type></link> value.
It calls the standard <link linkend="strtod"><function>strtod()</function></link> function to handle the conversion, but
if the string is not completely converted it attempts the conversion
again with <link linkend="g-ascii-strtod"><function>g_ascii_strtod()</function></link>, and returns the best match.</para>
<para>This function should seldom be used. The normal situation when reading
numbers not for human consumption is to use <link linkend="g-ascii-strtod"><function>g_ascii_strtod()</function></link>. Only when
you know that you must expect both locale formatted and C formatted numbers
should you use this. Make sure that you don't pass strings such as comma
separated lists of values, since the commas may be interpreted as a decimal
point in some locales, causing unexpected results.</para>
<refsect3 id="g-strtod.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>nptr</para></entry>
<entry role="parameter_description"><para>the string to convert to a numeric value.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>endptr</para></entry>
<entry role="parameter_description"><para>if non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>, it returns the
character after the last character used in the conversion. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>transfer none</acronym>][<acronym>optional</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strtod.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="gdouble"><type>gdouble</type></link> value.</para>
</refsect3></refsect2>
<refsect2 id="g-ascii-string-to-signed" role="function" condition="since:2.54">
<title>g_ascii_string_to_signed&#160;()</title>
<indexterm zone="g-ascii-string-to-signed" role="2.54"><primary sortas="ascii_string_to_signed">g_ascii_string_to_signed</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_ascii_string_to_signed (<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>,
                          <parameter><link linkend="guint"><type>guint</type></link> base</parameter>,
                          <parameter><link linkend="gint64"><type>gint64</type></link> min</parameter>,
                          <parameter><link linkend="gint64"><type>gint64</type></link> max</parameter>,
                          <parameter><link linkend="gint64"><type>gint64</type></link> *out_num</parameter>,
                          <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>A convenience function for converting a string to a signed number.</para>
<para>This function assumes that <parameter>str</parameter>
 contains only a number of the given
<parameter>base</parameter>
 that is within inclusive bounds limited by <parameter>min</parameter>
 and <parameter>max</parameter>
. If
this is true, then the converted number is stored in <parameter>out_num</parameter>
. An
empty string is not a valid input. A string with leading or
trailing whitespace is also an invalid input.</para>
<para><parameter>base</parameter>
 can be between 2 and 36 inclusive. Hexadecimal numbers must
not be prefixed with "0x" or "0X". Such a problem does not exist
for octal numbers, since they were usually prefixed with a zero
which does not change the value of the parsed number.</para>
<para>Parsing failures result in an error with the <link linkend="G-NUMBER-PARSER-ERROR:CAPS"><literal>G_NUMBER_PARSER_ERROR</literal></link>
domain. If the input is invalid, the error code will be
<link linkend="G-NUMBER-PARSER-ERROR-INVALID:CAPS"><literal>G_NUMBER_PARSER_ERROR_INVALID</literal></link>. If the parsed number is out of
bounds - <link linkend="G-NUMBER-PARSER-ERROR-OUT-OF-BOUNDS:CAPS"><literal>G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS</literal></link>.</para>
<para>See <link linkend="g-ascii-strtoll"><function>g_ascii_strtoll()</function></link> if you have more complex needs such as
parsing a string which starts with a number, but then has other
characters.</para>
<refsect3 id="g-ascii-string-to-signed.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str</para></entry>
<entry role="parameter_description"><para>a string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>base</para></entry>
<entry role="parameter_description"><para>base of a parsed number</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>min</para></entry>
<entry role="parameter_description"><para>a lower bound (inclusive)</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>max</para></entry>
<entry role="parameter_description"><para>an upper bound (inclusive)</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>out_num</para></entry>
<entry role="parameter_description"><para>a return location for a number. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>optional</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>a return location for <link linkend="GError"><type>GError</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-string-to-signed.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter>
was a number, otherwise <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.54">2.54</link></para></refsect2>
<refsect2 id="g-ascii-string-to-unsigned" role="function" condition="since:2.54">
<title>g_ascii_string_to_unsigned&#160;()</title>
<indexterm zone="g-ascii-string-to-unsigned" role="2.54"><primary sortas="ascii_string_to_unsigned">g_ascii_string_to_unsigned</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_ascii_string_to_unsigned (<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>,
                            <parameter><link linkend="guint"><type>guint</type></link> base</parameter>,
                            <parameter><link linkend="guint64"><type>guint64</type></link> min</parameter>,
                            <parameter><link linkend="guint64"><type>guint64</type></link> max</parameter>,
                            <parameter><link linkend="guint64"><type>guint64</type></link> *out_num</parameter>,
                            <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>A convenience function for converting a string to an unsigned number.</para>
<para>This function assumes that <parameter>str</parameter>
 contains only a number of the given
<parameter>base</parameter>
 that is within inclusive bounds limited by <parameter>min</parameter>
 and <parameter>max</parameter>
. If
this is true, then the converted number is stored in <parameter>out_num</parameter>
. An
empty string is not a valid input. A string with leading or
trailing whitespace is also an invalid input. A string with a leading sign
(<literal>-</literal> or <literal>+</literal>) is not a valid input for the unsigned parser.</para>
<para><parameter>base</parameter>
 can be between 2 and 36 inclusive. Hexadecimal numbers must
not be prefixed with "0x" or "0X". Such a problem does not exist
for octal numbers, since they were usually prefixed with a zero
which does not change the value of the parsed number.</para>
<para>Parsing failures result in an error with the <link linkend="G-NUMBER-PARSER-ERROR:CAPS"><literal>G_NUMBER_PARSER_ERROR</literal></link>
domain. If the input is invalid, the error code will be
<link linkend="G-NUMBER-PARSER-ERROR-INVALID:CAPS"><literal>G_NUMBER_PARSER_ERROR_INVALID</literal></link>. If the parsed number is out of
bounds - <link linkend="G-NUMBER-PARSER-ERROR-OUT-OF-BOUNDS:CAPS"><literal>G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS</literal></link>.</para>
<para>See <link linkend="g-ascii-strtoull"><function>g_ascii_strtoull()</function></link> if you have more complex needs such as
parsing a string which starts with a number, but then has other
characters.</para>
<refsect3 id="g-ascii-string-to-unsigned.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str</para></entry>
<entry role="parameter_description"><para>a string</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>base</para></entry>
<entry role="parameter_description"><para>base of a parsed number</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>min</para></entry>
<entry role="parameter_description"><para>a lower bound (inclusive)</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>max</para></entry>
<entry role="parameter_description"><para>an upper bound (inclusive)</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>out_num</para></entry>
<entry role="parameter_description"><para>a return location for a number. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>optional</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>a return location for <link linkend="GError"><type>GError</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-ascii-string-to-unsigned.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter>
was a number, otherwise <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.54">2.54</link></para></refsect2>
<refsect2 id="g-strchug" role="function">
<title>g_strchug&#160;()</title>
<indexterm zone="g-strchug"><primary sortas="strchug">g_strchug</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strchug (<parameter><link linkend="gchar"><type>gchar</type></link> *string</parameter>);</programlisting>
<para>Removes leading whitespace from a string, by moving the rest
of the characters forward.</para>
<para>This function doesn't allocate or reallocate any memory;
it modifies <parameter>string</parameter>
 in place. Therefore, it cannot be used on
statically allocated strings.</para>
<para>The pointer to <parameter>string</parameter>
 is returned to allow the nesting of functions.</para>
<para>Also see <link linkend="g-strchomp"><function>g_strchomp()</function></link> and <link linkend="g-strstrip"><function>g_strstrip()</function></link>.</para>
<refsect3 id="g-strchug.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a string to remove the leading whitespace from</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strchug.returns" role="returns">
<title>Returns</title>
<para> <parameter>string</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-strchomp" role="function">
<title>g_strchomp&#160;()</title>
<indexterm zone="g-strchomp"><primary sortas="strchomp">g_strchomp</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strchomp (<parameter><link linkend="gchar"><type>gchar</type></link> *string</parameter>);</programlisting>
<para>Removes trailing whitespace from a string.</para>
<para>This function doesn't allocate or reallocate any memory;
it modifies <parameter>string</parameter>
 in place. Therefore, it cannot be used
on statically allocated strings.</para>
<para>The pointer to <parameter>string</parameter>
 is returned to allow the nesting of functions.</para>
<para>Also see <link linkend="g-strchug"><function>g_strchug()</function></link> and <link linkend="g-strstrip"><function>g_strstrip()</function></link>.</para>
<refsect3 id="g-strchomp.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a string to remove the trailing whitespace from</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strchomp.returns" role="returns">
<title>Returns</title>
<para> <parameter>string</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-strstrip" role="macro">
<title>g_strstrip()</title>
<indexterm zone="g-strstrip"><primary sortas="strstrip">g_strstrip</primary></indexterm>
<programlisting language="C">#define             g_strstrip( string )</programlisting>
<para>Removes leading and trailing whitespace from a string.
See <link linkend="g-strchomp"><function>g_strchomp()</function></link> and <link linkend="g-strchug"><function>g_strchug()</function></link>.</para>
<refsect3 id="g-strstrip.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a string to remove the leading and trailing whitespace from</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strstrip.returns" role="returns">
<title>Returns</title>
<para> <parameter>string</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-strdelimit" role="function">
<title>g_strdelimit&#160;()</title>
<indexterm zone="g-strdelimit"><primary sortas="strdelimit">g_strdelimit</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strdelimit (<parameter><link linkend="gchar"><type>gchar</type></link> *string</parameter>,
              <parameter>const <link linkend="gchar"><type>gchar</type></link> *delimiters</parameter>,
              <parameter><link linkend="gchar"><type>gchar</type></link> new_delimiter</parameter>);</programlisting>
<para>Converts any delimiter characters in <parameter>string</parameter>
 to <parameter>new_delimiter</parameter>
.
Any characters in <parameter>string</parameter>
 which are found in <parameter>delimiters</parameter>
 are
changed to the <parameter>new_delimiter</parameter>
 character. Modifies <parameter>string</parameter>
 in place,
and returns <parameter>string</parameter>
 itself, not a copy. The return value is to
allow nesting such as</para>
<informalexample><programlisting role="example"><![CDATA[
  g_ascii_strup (g_strdelimit (str, "abc", '?'))
]]></programlisting></informalexample>
<para></para>
<refsect3 id="g-strdelimit.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the string to convert</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>delimiters</para></entry>
<entry role="parameter_description"><para>a string containing the current delimiters,
or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to use the standard delimiters defined in <link linkend="G-STR-DELIMITERS:CAPS"><type>G_STR_DELIMITERS</type></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>new_delimiter</para></entry>
<entry role="parameter_description"><para>the new delimiter character</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strdelimit.returns" role="returns">
<title>Returns</title>
<para> <parameter>string</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-strescape" role="function">
<title>g_strescape&#160;()</title>
<indexterm zone="g-strescape"><primary sortas="strescape">g_strescape</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strescape (<parameter>const <link linkend="gchar"><type>gchar</type></link> *source</parameter>,
             <parameter>const <link linkend="gchar"><type>gchar</type></link> *exceptions</parameter>);</programlisting>
<para>Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
and '"' in the string <parameter>source</parameter>
 by inserting a '\' before
them. Additionally all characters in the range 0x01-0x1F (everything
below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
replaced with a '\' followed by their octal representation.
Characters supplied in <parameter>exceptions</parameter>
 are not escaped.</para>
<para>g_strcompress() does the reverse conversion.</para>
<refsect3 id="g-strescape.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a string to escape</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>exceptions</para></entry>
<entry role="parameter_description"><para>a string of characters not to escape in <parameter>source</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strescape.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated copy of <parameter>source</parameter>
with certain
characters escaped. See above.</para>
</refsect3></refsect2>
<refsect2 id="g-strcompress" role="function">
<title>g_strcompress&#160;()</title>
<indexterm zone="g-strcompress"><primary sortas="strcompress">g_strcompress</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strcompress (<parameter>const <link linkend="gchar"><type>gchar</type></link> *source</parameter>);</programlisting>
<para>Replaces all escaped characters with their one byte equivalent.</para>
<para>This function does the reverse conversion of <link linkend="g-strescape"><function>g_strescape()</function></link>.</para>
<refsect3 id="g-strcompress.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>a string to compress</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strcompress.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated copy of <parameter>source</parameter>
with all escaped
character compressed</para>
</refsect3></refsect2>
<refsect2 id="g-strcanon" role="function">
<title>g_strcanon&#160;()</title>
<indexterm zone="g-strcanon"><primary sortas="strcanon">g_strcanon</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strcanon (<parameter><link linkend="gchar"><type>gchar</type></link> *string</parameter>,
            <parameter>const <link linkend="gchar"><type>gchar</type></link> *valid_chars</parameter>,
            <parameter><link linkend="gchar"><type>gchar</type></link> substitutor</parameter>);</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</para>
<informalexample><programlisting role="example"><![CDATA[
  g_ascii_strup (g_strcanon (str, "abc", '?'))
]]></programlisting></informalexample>
<para></para>
<refsect3 id="g-strcanon.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a nul-terminated array of bytes</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>valid_chars</para></entry>
<entry role="parameter_description"><para>bytes permitted in <parameter>string</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>substitutor</para></entry>
<entry role="parameter_description"><para>replacement character for disallowed bytes</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strcanon.returns" role="returns">
<title>Returns</title>
<para> <parameter>string</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-strsplit" role="function">
<title>g_strsplit&#160;()</title>
<indexterm zone="g-strsplit"><primary sortas="strsplit">g_strsplit</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
g_strsplit (<parameter>const <link linkend="gchar"><type>gchar</type></link> *string</parameter>,
            <parameter>const <link linkend="gchar"><type>gchar</type></link> *delimiter</parameter>,
            <parameter><link linkend="gint"><type>gint</type></link> max_tokens</parameter>);</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 an example, the result of g_strsplit (":a:bc::d:", ":", -1) is a
<link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated vector containing the six strings "", "a", "bc", "", "d"
and "".</para>
<para>As a special case, the result of splitting the empty string "" is an empty
vector, not a vector containing a single string. The reason for this
special case is that being able to represent a empty vector is typically
more useful than consistent handling of empty elements. If you do need
to represent empty elements, you'll need to check for the empty string
before calling <link linkend="g-strsplit"><function>g_strsplit()</function></link>.</para>
<refsect3 id="g-strsplit.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a string to split</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>delimiter</para></entry>
<entry role="parameter_description"><para>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.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>max_tokens</para></entry>
<entry role="parameter_description"><para>the maximum number of pieces to split <parameter>string</parameter>
into.
If this is less than 1, the string is split completely.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strsplit.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings. Use
<link linkend="g-strfreev"><function>g_strfreev()</function></link> to free it.</para>
</refsect3></refsect2>
<refsect2 id="g-strsplit-set" role="function" condition="since:2.4">
<title>g_strsplit_set&#160;()</title>
<indexterm zone="g-strsplit-set" role="2.4"><primary sortas="strsplit_set">g_strsplit_set</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
g_strsplit_set (<parameter>const <link linkend="gchar"><type>gchar</type></link> *string</parameter>,
                <parameter>const <link linkend="gchar"><type>gchar</type></link> *delimiters</parameter>,
                <parameter><link linkend="gint"><type>gint</type></link> max_tokens</parameter>);</programlisting>
<para>Splits <parameter>string</parameter>
 into a number of tokens not containing any of the characters
in <parameter>delimiter</parameter>
. A token is the (possibly empty) longest string that does not
contain any of the characters in <parameter>delimiters</parameter>
. If <parameter>max_tokens</parameter>
 is reached, the
remainder is appended to the last token.</para>
<para>For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
<link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated vector containing the three strings "abc", "def",
and "ghi".</para>
<para>The result of g_strsplit_set (":def/ghi:", ":/", -1) is a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated
vector containing the four strings "", "def", "ghi", and "".</para>
<para>As a special case, the result of splitting the empty string "" is an empty
vector, not a vector containing a single string. The reason for this
special case is that being able to represent a empty vector is typically
more useful than consistent handling of empty elements. If you do need
to represent empty elements, you'll need to check for the empty string
before calling <link linkend="g-strsplit-set"><function>g_strsplit_set()</function></link>.</para>
<para>Note that this function works on bytes not characters, so it can't be used
to delimit UTF-8 strings for anything but ASCII characters.</para>
<refsect3 id="g-strsplit-set.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>The string to be tokenized</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>delimiters</para></entry>
<entry role="parameter_description"><para>A nul-terminated string containing bytes that are used
to split the string.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>max_tokens</para></entry>
<entry role="parameter_description"><para>The maximum number of tokens to split <parameter>string</parameter>
into.
If this is less than 1, the string is split completely</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strsplit-set.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings. Use
<link linkend="g-strfreev"><function>g_strfreev()</function></link> to free it.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-strfreev" role="function">
<title>g_strfreev&#160;()</title>
<indexterm zone="g-strfreev"><primary sortas="strfreev">g_strfreev</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_strfreev (<parameter><link linkend="gchar"><type>gchar</type></link> **str_array</parameter>);</programlisting>
<para>Frees a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings, as well as each
string it contains.</para>
<para>If <parameter>str_array</parameter>
 is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, this function simply returns.</para>
<refsect3 id="g-strfreev.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str_array</para></entry>
<entry role="parameter_description"><para>a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings to free. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-strconcat" role="function">
<title>g_strconcat&#160;()</title>
<indexterm zone="g-strconcat"><primary sortas="strconcat">g_strconcat</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strconcat (<parameter>const <link linkend="gchar"><type>gchar</type></link> *string1</parameter>,
             <parameter>...</parameter>);</programlisting>
<para>Concatenates all of the given strings into one long string. The
returned string should be freed with <link linkend="g-free"><function>g_free()</function></link> when no longer needed.</para>
<para>The variable argument list must end with <link linkend="NULL:CAPS"><literal>NULL</literal></link>. If you forget the <link linkend="NULL:CAPS"><literal>NULL</literal></link>,
<link linkend="g-strconcat"><function>g_strconcat()</function></link> will start appending random memory junk to your string.</para>
<para>Note that this function is usually not the right function to use to
assemble a translated message from pieces, since proper translation
often requires the pieces to be reordered.</para>
<refsect3 id="g-strconcat.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string1</para></entry>
<entry role="parameter_description"><para>the first string to add, which must not be <link linkend="NULL:CAPS"><literal>NULL</literal></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated list of strings to append to the string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strconcat.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated string containing all the string arguments</para>
</refsect3></refsect2>
<refsect2 id="g-strjoin" role="function">
<title>g_strjoin&#160;()</title>
<indexterm zone="g-strjoin"><primary sortas="strjoin">g_strjoin</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strjoin (<parameter>const <link linkend="gchar"><type>gchar</type></link> *separator</parameter>,
           <parameter>...</parameter>);</programlisting>
<para>Joins a number of strings together to form one long string, with the
optional <parameter>separator</parameter>
 inserted between each of them. The returned string
should be freed with <link linkend="g-free"><function>g_free()</function></link>.</para>
<refsect3 id="g-strjoin.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>separator</para></entry>
<entry role="parameter_description"><para>a string to insert between each of the
strings, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated list of strings to join</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strjoin.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated string containing all of the strings joined
together, with <parameter>separator</parameter>
between them</para>
</refsect3></refsect2>
<refsect2 id="g-strjoinv" role="function">
<title>g_strjoinv&#160;()</title>
<indexterm zone="g-strjoinv"><primary sortas="strjoinv">g_strjoinv</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strjoinv (<parameter>const <link linkend="gchar"><type>gchar</type></link> *separator</parameter>,
            <parameter><link linkend="gchar"><type>gchar</type></link> **str_array</parameter>);</programlisting>
<para>Joins a number of strings together to form one long string, with the
optional <parameter>separator</parameter>
 inserted between each of them. The returned string
should be freed with <link linkend="g-free"><function>g_free()</function></link>.</para>
<para>If <parameter>str_array</parameter>
 has no items, the return value will be an
empty string. If <parameter>str_array</parameter>
 contains a single item, <parameter>separator</parameter>
 will not
appear in the resulting string.</para>
<refsect3 id="g-strjoinv.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>separator</para></entry>
<entry role="parameter_description"><para>a string to insert between each of the
strings, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>str_array</para></entry>
<entry role="parameter_description"><para>a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings to join</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strjoinv.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated string containing all of the strings joined
together, with <parameter>separator</parameter>
between them</para>
</refsect3></refsect2>
<refsect2 id="g-strv-length" role="function" condition="since:2.6">
<title>g_strv_length&#160;()</title>
<indexterm zone="g-strv-length" role="2.6"><primary sortas="strv_length">g_strv_length</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_strv_length (<parameter><link linkend="gchar"><type>gchar</type></link> **str_array</parameter>);</programlisting>
<para>Returns the length of the given <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated
string array <parameter>str_array</parameter>
. <parameter>str_array</parameter>
 must not be <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
<refsect3 id="g-strv-length.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>str_array</para></entry>
<entry role="parameter_description"><para>a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strv-length.returns" role="returns">
<title>Returns</title>
<para> length of <parameter>str_array</parameter>
.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.6">2.6</link></para></refsect2>
<refsect2 id="g-strv-contains" role="function" condition="since:2.44">
<title>g_strv_contains&#160;()</title>
<indexterm zone="g-strv-contains" role="2.44"><primary sortas="strv_contains">g_strv_contains</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_strv_contains (<parameter>const <link linkend="gchar"><type>gchar</type></link> * const *strv</parameter>,
                 <parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>);</programlisting>
<para>Checks if <parameter>strv</parameter>
 contains <parameter>str</parameter>
. <parameter>strv</parameter>
 must not be <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
<refsect3 id="g-strv-contains.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>strv</para></entry>
<entry role="parameter_description"><para>a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>str</para></entry>
<entry role="parameter_description"><para>a string</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strv-contains.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter>
is an element of <parameter>strv</parameter>
, according to <link linkend="g-str-equal"><function>g_str_equal()</function></link>.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.44">2.44</link></para></refsect2>
<refsect2 id="g-strv-equal" role="function" condition="since:2.60">
<title>g_strv_equal&#160;()</title>
<indexterm zone="g-strv-equal" role="2.60"><primary sortas="strv_equal">g_strv_equal</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_strv_equal (<parameter>const <link linkend="gchar"><type>gchar</type></link> * const *strv1</parameter>,
              <parameter>const <link linkend="gchar"><type>gchar</type></link> * const *strv2</parameter>);</programlisting>
<para>Checks if <parameter>strv1</parameter>
 and <parameter>strv2</parameter>
 contain exactly the same elements in exactly the
same order. Elements are compared using <link linkend="g-str-equal"><function>g_str_equal()</function></link>. To match independently
of order, sort the arrays first (using <link linkend="g-qsort-with-data"><function>g_qsort_with_data()</function></link> or similar).</para>
<para>Two empty arrays are considered equal. Neither <parameter>strv1</parameter>
 not <parameter>strv2</parameter>
 may be
<link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
<refsect3 id="g-strv-equal.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>strv1</para></entry>
<entry role="parameter_description"><para>a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>strv2</para></entry>
<entry role="parameter_description"><para>another <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strv-equal.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>strv1</parameter>
and <parameter>strv2</parameter>
are equal</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.60">2.60</link></para></refsect2>
<refsect2 id="g-strerror" role="function">
<title>g_strerror&#160;()</title>
<indexterm zone="g-strerror"><primary sortas="strerror">g_strerror</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strerror (<parameter><link linkend="gint"><type>gint</type></link> errnum</parameter>);</programlisting>
<para>Returns a string corresponding to the given error code, e.g. "no
such process". Unlike <link linkend="strerror"><function>strerror()</function></link>, this always returns a string in
UTF-8 encoding, and the pointer is guaranteed to remain valid for
the lifetime of the process.</para>
<para>Note that the string may be translated according to the current locale.</para>
<para>The value of <link linkend="errno"><literal>errno</literal></link> will not be changed by this function. However, it may
be changed by intermediate function calls, so you should save its value
as soon as the call returns:</para>
<informalexample><programlisting role="example"><![CDATA[
  int saved_errno;

  ret = read (blah);
  saved_errno = errno;

  g_strerror (saved_errno);
]]></programlisting></informalexample>
<para></para>
<refsect3 id="g-strerror.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>errnum</para></entry>
<entry role="parameter_description"><para>the system error number. See the standard C <link linkend="errno"><literal>errno</literal></link>
documentation</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strerror.returns" role="returns">
<title>Returns</title>
<para> a UTF-8 string describing the error code. If the error code
is unknown, it returns a string like "unknown error (&lt;code>)".</para>
</refsect3></refsect2>
<refsect2 id="g-strsignal" role="function">
<title>g_strsignal&#160;()</title>
<indexterm zone="g-strsignal"><primary sortas="strsignal">g_strsignal</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strsignal (<parameter><link linkend="gint"><type>gint</type></link> signum</parameter>);</programlisting>
<para>Returns a string describing the given signal, e.g. "Segmentation fault".
You should use this function in preference to <link linkend="strsignal"><function>strsignal()</function></link>, because it
returns a string in UTF-8 encoding, and since not all platforms support
the <link linkend="strsignal"><function>strsignal()</function></link> function.</para>
<refsect3 id="g-strsignal.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>signum</para></entry>
<entry role="parameter_description"><para>the signal number. See the <literal>signal</literal> documentation</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strsignal.returns" role="returns">
<title>Returns</title>
<para> a UTF-8 string describing the signal. If the signal is unknown,
it returns "unknown signal (&lt;signum>)".</para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="glib-String-Utility-Functions.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="G-ASCII-DTOSTR-BUF-SIZE:CAPS" role="macro">
<title>G_ASCII_DTOSTR_BUF_SIZE</title>
<indexterm zone="G-ASCII-DTOSTR-BUF-SIZE:CAPS"><primary sortas="ASCII_DTOSTR_BUF_SIZE">G_ASCII_DTOSTR_BUF_SIZE</primary></indexterm>
<programlisting language="C">#define G_ASCII_DTOSTR_BUF_SIZE (29 + 10)
</programlisting>
<para>A good size for a buffer to be passed into <link linkend="g-ascii-dtostr"><function>g_ascii_dtostr()</function></link>.
It is guaranteed to be enough for all output of that function
on systems with 64bit IEEE-compatible doubles.</para>
<para>The typical usage would be something like:</para>
<informalexample><programlisting role="example"><![CDATA[
  char buf[G_ASCII_DTOSTR_BUF_SIZE];

  fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
]]></programlisting></informalexample>
<para></para>
</refsect2>
<refsect2 id="GNumberParserError" role="enum" condition="since:2.54">
<title>enum GNumberParserError</title>
<indexterm zone="GNumberParserError" role="2.54"><primary sortas="NumberParserError">GNumberParserError</primary></indexterm>
<para>Error codes returned by functions converting a string to a number.</para>
<refsect3 id="GNumberParserError.members" role="enum_members">
<title>Members</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="enum_members_name" colwidth="300px"/>
<colspec colname="enum_members_description"/>
<colspec colname="enum_members_annotations" colwidth="200px"/>
<tbody>
<row role="constant"><entry role="enum_member_name"><para id="G-NUMBER-PARSER-ERROR-INVALID:CAPS">G_NUMBER_PARSER_ERROR_INVALID</para></entry>
<entry role="enum_member_description"><para>String was not a valid number.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="G-NUMBER-PARSER-ERROR-OUT-OF-BOUNDS:CAPS">G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS</para></entry>
<entry role="enum_member_description"><para>String was a number, but out of bounds.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.54">2.54</link></para></refsect2>
<refsect2 id="G-NUMBER-PARSER-ERROR:CAPS" role="macro" condition="since:2.54">
<title>G_NUMBER_PARSER_ERROR</title>
<indexterm zone="G-NUMBER-PARSER-ERROR:CAPS" role="2.54"><primary sortas="NUMBER_PARSER_ERROR">G_NUMBER_PARSER_ERROR</primary></indexterm>
<programlisting language="C">#define G_NUMBER_PARSER_ERROR (g_number_parser_error_quark ())
</programlisting>
<para>Domain for errors returned by functions converting a string to a
number.</para>
<para role="since">Since: <link linkend="api-index-2.54">2.54</link></para></refsect2>
<refsect2 id="G-STR-DELIMITERS:CAPS" role="macro">
<title>G_STR_DELIMITERS</title>
<indexterm zone="G-STR-DELIMITERS:CAPS"><primary sortas="STR_DELIMITERS">G_STR_DELIMITERS</primary></indexterm>
<programlisting language="C">#define	 G_STR_DELIMITERS&#160;"_-|&gt; &lt;."
</programlisting>
<para>The standard delimiters, used in <link linkend="g-strdelimit"><function>g_strdelimit()</function></link>.</para>
</refsect2>
<refsect2 id="GStrv" role="typedef">
<title>GStrv</title>
<indexterm zone="GStrv"><primary sortas="Strv">GStrv</primary></indexterm>
<programlisting language="C">typedef gchar** GStrv;
</programlisting>
<para>A typedef alias for gchar**. This is mostly useful when used together with
<link linkend="g-auto"><function>g_auto()</function></link>.</para>
</refsect2>

</refsect1>

</refentry>
