<?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_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_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 pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<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>
<para>The returned string is guaranteed to be non-NULL, unless <parameter>format</parameter>

contains <literal>%lc</literal> or <literal>%ls</literal> conversions, which can fail if no multibyte
representation is available for the given character.</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"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></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>The returned string is guaranteed to be non-NULL, unless <parameter>format</parameter>

contains <literal>%lc</literal> or <literal>%ls</literal> conversions, which can fail if no multibyte
representation is available for the given character.</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"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></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>The returned value in <parameter>string</parameter>
 is guaranteed to be non-NULL, unless
<parameter>format</parameter>
 contains <literal>%lc</literal> or <literal>%ls</literal> conversions, which can fail if no
multibyte representation is available for the given character.</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"><emphasis role="annotation">[<acronym>not optional</acronym>][<acronym>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"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></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 hexadecimal
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>
<para>In order to modify a copy, you may use <literal><link linkend="g-strdup"><function>g_strdup()</function></link></literal>:</para>
<informalexample><programlisting role="example"><![CDATA[
  reformatted = g_strdelimit (g_strdup (const_str), "abc", '?');
  ...
  g_free (reformatted);
]]></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>
<para>In order to modify a copy, you may use <literal><link linkend="g-strdup"><function>g_strdup()</function></link></literal>:</para>
<informalexample><programlisting role="example"><![CDATA[
  reformatted = g_strcanon (g_strdup (const_str), "abc", '?');
  ...
  g_free (reformatted);
]]></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 an 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 an 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 (it can accept an empty string, which will result
in no string splitting).</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>
