glib2.0_2.20.1
[mer:glib2_0.git] / docs / reference / glib / xml / string_utils.xml
1 <refentry id="glib-String-Utility-Functions">
2 <refmeta>
3 <refentrytitle role="top_of_page" id="glib-String-Utility-Functions.top_of_page">String Utility Functions</refentrytitle>
4 <manvolnum>3</manvolnum>
5 <refmiscinfo>GLIB Library</refmiscinfo>
6 </refmeta>
7
8 <refnamediv>
9 <refname>String Utility Functions</refname>
10 <refpurpose>various string-related functions</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv id="glib-String-Utility-Functions.synopsis" role="synopsis">
14 <title role="synopsis.title">Synopsis</title>
15
16 <synopsis>
17
18 #include &lt;glib.h&gt;
19 #include &lt;glib/gprintf.h&gt;
20
21 <link linkend="gchar">gchar</link>*              <link linkend="g-strdup">g_strdup</link>                            (const <link linkend="gchar">gchar</link> *str);
22 <link linkend="gchar">gchar</link>*              <link linkend="g-strndup">g_strndup</link>                           (const <link linkend="gchar">gchar</link> *str,
23                                                          <link linkend="gsize">gsize</link> n);
24 <link linkend="gchar">gchar</link>**             <link linkend="g-strdupv">g_strdupv</link>                           (<link linkend="gchar">gchar</link> **str_array);
25 <link linkend="gchar">gchar</link>*              <link linkend="g-strnfill">g_strnfill</link>                          (<link linkend="gsize">gsize</link> length,
26                                                          <link linkend="gchar">gchar</link> fill_char);
27 <link linkend="gchar">gchar</link>*              <link linkend="g-stpcpy">g_stpcpy</link>                            (<link linkend="gchar">gchar</link> *dest,
28                                                          const <link linkend="char">char</link> *src);
29 <link linkend="gchar">gchar</link> *             <link linkend="g-strstr-len">g_strstr_len</link>                        (const <link linkend="gchar">gchar</link> *haystack,
30                                                          <link linkend="gssize">gssize</link> haystack_len,
31                                                          const <link linkend="gchar">gchar</link> *needle);
32 <link linkend="gchar">gchar</link> *             <link linkend="g-strrstr">g_strrstr</link>                           (const <link linkend="gchar">gchar</link> *haystack,
33                                                          const <link linkend="gchar">gchar</link> *needle);
34 <link linkend="gchar">gchar</link> *             <link linkend="g-strrstr-len">g_strrstr_len</link>                       (const <link linkend="gchar">gchar</link> *haystack,
35                                                          <link linkend="gssize">gssize</link> haystack_len,
36                                                          const <link linkend="gchar">gchar</link> *needle);
37 <link linkend="gboolean">gboolean</link>            <link linkend="g-str-has-prefix">g_str_has_prefix</link>                    (const <link linkend="gchar">gchar</link> *str,
38                                                          const <link linkend="gchar">gchar</link> *prefix);
39 <link linkend="gboolean">gboolean</link>            <link linkend="g-str-has-suffix">g_str_has_suffix</link>                    (const <link linkend="gchar">gchar</link> *str,
40                                                          const <link linkend="gchar">gchar</link> *suffix);
41 <link linkend="int">int</link>                 <link linkend="g-strcmp0">g_strcmp0</link>                           (const <link linkend="char">char</link> *str1,
42                                                          const <link linkend="char">char</link> *str2);
43
44 <link linkend="gsize">gsize</link>               <link linkend="g-strlcpy">g_strlcpy</link>                           (<link linkend="gchar">gchar</link> *dest,
45                                                          const <link linkend="gchar">gchar</link> *src,
46                                                          <link linkend="gsize">gsize</link> dest_size);
47 <link linkend="gsize">gsize</link>               <link linkend="g-strlcat">g_strlcat</link>                           (<link linkend="gchar">gchar</link> *dest,
48                                                          const <link linkend="gchar">gchar</link> *src,
49                                                          <link linkend="gsize">gsize</link> dest_size);
50
51 <link linkend="gchar">gchar</link>*              <link linkend="g-strdup-printf">g_strdup_printf</link>                     (const <link linkend="gchar">gchar</link> *format,
52                                                          ...);
53 <link linkend="gchar">gchar</link>*              <link linkend="g-strdup-vprintf">g_strdup_vprintf</link>                    (const <link linkend="gchar">gchar</link> *format,
54                                                          <link linkend="va-list">va_list</link> args);
55 <link linkend="gint">gint</link>                <link linkend="g-printf">g_printf</link>                            (<link linkend="gchar">gchar</link> const *format,
56                                                          ...);
57 <link linkend="gint">gint</link>                <link linkend="g-vprintf">g_vprintf</link>                           (<link linkend="gchar">gchar</link> const *format,
58                                                          <link linkend="va-list">va_list</link> args);
59 <link linkend="gint">gint</link>                <link linkend="g-fprintf">g_fprintf</link>                           (<link linkend="FILE--CAPS">FILE</link> *file,
60                                                          <link linkend="gchar">gchar</link> const *format,
61                                                          ...);
62 <link linkend="gint">gint</link>                <link linkend="g-vfprintf">g_vfprintf</link>                          (<link linkend="FILE--CAPS">FILE</link> *file,
63                                                          <link linkend="gchar">gchar</link> const *format,
64                                                          <link linkend="va-list">va_list</link> args);
65 <link linkend="gint">gint</link>                <link linkend="g-sprintf">g_sprintf</link>                           (<link linkend="gchar">gchar</link> *string,
66                                                          <link linkend="gchar">gchar</link> const *format,
67                                                          ...);
68 <link linkend="gint">gint</link>                <link linkend="g-vsprintf">g_vsprintf</link>                          (<link linkend="gchar">gchar</link> *string,
69                                                          <link linkend="gchar">gchar</link> const *format,
70                                                          <link linkend="va-list">va_list</link> args);
71 <link linkend="gint">gint</link>                <link linkend="g-snprintf">g_snprintf</link>                          (<link linkend="gchar">gchar</link> *string,
72                                                          <link linkend="gulong">gulong</link> n,
73                                                          <link linkend="gchar">gchar</link> const *format,
74                                                          ...);
75 <link linkend="gint">gint</link>                <link linkend="g-vsnprintf">g_vsnprintf</link>                         (<link linkend="gchar">gchar</link> *string,
76                                                          <link linkend="gulong">gulong</link> n,
77                                                          <link linkend="gchar">gchar</link> const *format,
78                                                          <link linkend="va-list">va_list</link> args);
79 <link linkend="gint">gint</link>                <link linkend="g-vasprintf">g_vasprintf</link>                         (<link linkend="gchar">gchar</link> **string,
80                                                          <link linkend="gchar">gchar</link> const *format,
81                                                          <link linkend="va-list">va_list</link> args);
82 <link linkend="gsize">gsize</link>               <link linkend="g-printf-string-upper-bound">g_printf_string_upper_bound</link>         (const <link linkend="gchar">gchar</link> *format,
83                                                          <link linkend="va-list">va_list</link> args);
84
85 <link linkend="gboolean">gboolean</link>            <link linkend="g-ascii-isalnum">g_ascii_isalnum</link>                     (<link linkend="gchar">gchar</link> c);
86 <link linkend="gboolean">gboolean</link>            <link linkend="g-ascii-isalpha">g_ascii_isalpha</link>                     (<link linkend="gchar">gchar</link> c);
87 <link linkend="gboolean">gboolean</link>            <link linkend="g-ascii-iscntrl">g_ascii_iscntrl</link>                     (<link linkend="gchar">gchar</link> c);
88 <link linkend="gboolean">gboolean</link>            <link linkend="g-ascii-isdigit">g_ascii_isdigit</link>                     (<link linkend="gchar">gchar</link> c);
89 <link linkend="gboolean">gboolean</link>            <link linkend="g-ascii-isgraph">g_ascii_isgraph</link>                     (<link linkend="gchar">gchar</link> c);
90 <link linkend="gboolean">gboolean</link>            <link linkend="g-ascii-islower">g_ascii_islower</link>                     (<link linkend="gchar">gchar</link> c);
91 <link linkend="gboolean">gboolean</link>            <link linkend="g-ascii-isprint">g_ascii_isprint</link>                     (<link linkend="gchar">gchar</link> c);
92 <link linkend="gboolean">gboolean</link>            <link linkend="g-ascii-ispunct">g_ascii_ispunct</link>                     (<link linkend="gchar">gchar</link> c);
93 <link linkend="gboolean">gboolean</link>            <link linkend="g-ascii-isspace">g_ascii_isspace</link>                     (<link linkend="gchar">gchar</link> c);
94 <link linkend="gboolean">gboolean</link>            <link linkend="g-ascii-isupper">g_ascii_isupper</link>                     (<link linkend="gchar">gchar</link> c);
95 <link linkend="gboolean">gboolean</link>            <link linkend="g-ascii-isxdigit">g_ascii_isxdigit</link>                    (<link linkend="gchar">gchar</link> c);
96
97 <link linkend="gint">gint</link>                <link linkend="g-ascii-digit-value">g_ascii_digit_value</link>                 (<link linkend="gchar">gchar</link> c);
98 <link linkend="gint">gint</link>                <link linkend="g-ascii-xdigit-value">g_ascii_xdigit_value</link>                (<link linkend="gchar">gchar</link> c);
99
100 <link linkend="gint">gint</link>                <link linkend="g-ascii-strcasecmp">g_ascii_strcasecmp</link>                  (const <link linkend="gchar">gchar</link> *s1,
101                                                          const <link linkend="gchar">gchar</link> *s2);
102 <link linkend="gint">gint</link>                <link linkend="g-ascii-strncasecmp">g_ascii_strncasecmp</link>                 (const <link linkend="gchar">gchar</link> *s1,
103                                                          const <link linkend="gchar">gchar</link> *s2,
104                                                          <link linkend="gsize">gsize</link> n);
105
106 <link linkend="gchar">gchar</link>*              <link linkend="g-ascii-strup">g_ascii_strup</link>                       (const <link linkend="gchar">gchar</link> *str,
107                                                          <link linkend="gssize">gssize</link> len);
108 <link linkend="gchar">gchar</link>*              <link linkend="g-ascii-strdown">g_ascii_strdown</link>                     (const <link linkend="gchar">gchar</link> *str,
109                                                          <link linkend="gssize">gssize</link> len);
110
111 <link linkend="gchar">gchar</link>               <link linkend="g-ascii-tolower">g_ascii_tolower</link>                     (<link linkend="gchar">gchar</link> c);
112 <link linkend="gchar">gchar</link>               <link linkend="g-ascii-toupper">g_ascii_toupper</link>                     (<link linkend="gchar">gchar</link> c);
113
114 <link linkend="GString">GString</link>*            <link linkend="g-string-ascii-up">g_string_ascii_up</link>                   (<link linkend="GString">GString</link> *string);
115 <link linkend="GString">GString</link>*            <link linkend="g-string-ascii-down">g_string_ascii_down</link>                 (<link linkend="GString">GString</link> *string);
116
117 <link linkend="gchar">gchar</link>*              <link linkend="g-strup">g_strup</link>                             (<link linkend="gchar">gchar</link> *string);
118 <link linkend="gchar">gchar</link>*              <link linkend="g-strdown">g_strdown</link>                           (<link linkend="gchar">gchar</link> *string);
119
120 <link linkend="gint">gint</link>                <link linkend="g-strcasecmp">g_strcasecmp</link>                        (const <link linkend="gchar">gchar</link> *s1,
121                                                          const <link linkend="gchar">gchar</link> *s2);
122 <link linkend="gint">gint</link>                <link linkend="g-strncasecmp">g_strncasecmp</link>                       (const <link linkend="gchar">gchar</link> *s1,
123                                                          const <link linkend="gchar">gchar</link> *s2,
124                                                          <link linkend="guint">guint</link> n);
125
126 <link linkend="gchar">gchar</link>*              <link linkend="g-strreverse">g_strreverse</link>                        (<link linkend="gchar">gchar</link> *string);
127
128 <link linkend="gint64">gint64</link>              <link linkend="g-ascii-strtoll">g_ascii_strtoll</link>                     (const <link linkend="gchar">gchar</link> *nptr,
129                                                          <link linkend="gchar">gchar</link> **endptr,
130                                                          <link linkend="guint">guint</link> base);
131 <link linkend="guint64">guint64</link>             <link linkend="g-ascii-strtoull">g_ascii_strtoull</link>                    (const <link linkend="gchar">gchar</link> *nptr,
132                                                          <link linkend="gchar">gchar</link> **endptr,
133                                                          <link linkend="guint">guint</link> base);
134 #define             <link linkend="G-ASCII-DTOSTR-BUF-SIZE--CAPS">G_ASCII_DTOSTR_BUF_SIZE</link>
135 <link linkend="gdouble">gdouble</link>             <link linkend="g-ascii-strtod">g_ascii_strtod</link>                      (const <link linkend="gchar">gchar</link> *nptr,
136                                                          <link linkend="gchar">gchar</link> **endptr);
137 <link linkend="gchar">gchar</link> *             <link linkend="g-ascii-dtostr">g_ascii_dtostr</link>                      (<link linkend="gchar">gchar</link> *buffer,
138                                                          <link linkend="gint">gint</link> buf_len,
139                                                          <link linkend="gdouble">gdouble</link> d);
140 <link linkend="gchar">gchar</link> *             <link linkend="g-ascii-formatd">g_ascii_formatd</link>                     (<link linkend="gchar">gchar</link> *buffer,
141                                                          <link linkend="gint">gint</link> buf_len,
142                                                          const <link linkend="gchar">gchar</link> *format,
143                                                          <link linkend="gdouble">gdouble</link> d);
144 <link linkend="gdouble">gdouble</link>             <link linkend="g-strtod">g_strtod</link>                            (const <link linkend="gchar">gchar</link> *nptr,
145                                                          <link linkend="gchar">gchar</link> **endptr);
146
147 <link linkend="gchar">gchar</link>*              <link linkend="g-strchug">g_strchug</link>                           (<link linkend="gchar">gchar</link> *string);
148 <link linkend="gchar">gchar</link>*              <link linkend="g-strchomp">g_strchomp</link>                          (<link linkend="gchar">gchar</link> *string);
149 #define             <link linkend="g-strstrip">g_strstrip</link>                          ( string )
150
151 <link linkend="gchar">gchar</link>*              <link linkend="g-strdelimit">g_strdelimit</link>                        (<link linkend="gchar">gchar</link> *string,
152                                                          const <link linkend="gchar">gchar</link> *delimiters,
153                                                          <link linkend="gchar">gchar</link> new_delimiter);
154 #define             <link linkend="G-STR-DELIMITERS--CAPS">G_STR_DELIMITERS</link>
155 <link linkend="gchar">gchar</link>*              <link linkend="g-strescape">g_strescape</link>                         (const <link linkend="gchar">gchar</link> *source,
156                                                          const <link linkend="gchar">gchar</link> *exceptions);
157 <link linkend="gchar">gchar</link>*              <link linkend="g-strcompress">g_strcompress</link>                       (const <link linkend="gchar">gchar</link> *source);
158 <link linkend="gchar">gchar</link>*              <link linkend="g-strcanon">g_strcanon</link>                          (<link linkend="gchar">gchar</link> *string,
159                                                          const <link linkend="gchar">gchar</link> *valid_chars,
160                                                          <link linkend="gchar">gchar</link> substitutor);
161 <link linkend="gchar">gchar</link>**             <link linkend="g-strsplit">g_strsplit</link>                          (const <link linkend="gchar">gchar</link> *string,
162                                                          const <link linkend="gchar">gchar</link> *delimiter,
163                                                          <link linkend="gint">gint</link> max_tokens);
164 <link linkend="gchar">gchar</link> **            <link linkend="g-strsplit-set">g_strsplit_set</link>                      (const <link linkend="gchar">gchar</link> *string,
165                                                          const <link linkend="gchar">gchar</link> *delimiters,
166                                                          <link linkend="gint">gint</link> max_tokens);
167 <link linkend="void">void</link>                <link linkend="g-strfreev">g_strfreev</link>                          (<link linkend="gchar">gchar</link> **str_array);
168 <link linkend="gchar">gchar</link>*              <link linkend="g-strconcat">g_strconcat</link>                         (const <link linkend="gchar">gchar</link> *string1,
169                                                          ...);
170 <link linkend="gchar">gchar</link>*              <link linkend="g-strjoin">g_strjoin</link>                           (const <link linkend="gchar">gchar</link> *separator,
171                                                          ...);
172 <link linkend="gchar">gchar</link>*              <link linkend="g-strjoinv">g_strjoinv</link>                          (const <link linkend="gchar">gchar</link> *separator,
173                                                          <link linkend="gchar">gchar</link> **str_array);
174 <link linkend="guint">guint</link>               <link linkend="g-strv-length">g_strv_length</link>                       (<link linkend="gchar">gchar</link> **str_array);
175
176 const <link linkend="gchar">gchar</link>*        <link linkend="g-strerror">g_strerror</link>                          (<link linkend="gint">gint</link> errnum);
177 const <link linkend="gchar">gchar</link>*        <link linkend="g-strsignal">g_strsignal</link>                         (<link linkend="gint">gint</link> signum);
178 </synopsis>
179 </refsynopsisdiv>
180
181
182
183
184
185
186
187
188
189 <refsect1 id="glib-String-Utility-Functions.description" role="desc">
190 <title role="desc.title">Description</title>
191 <para>
192 This section describes a number of utility functions for creating,
193 duplicating, and manipulating strings.
194 </para>
195 <para>
196 Note that the functions <link linkend="g-printf"><function>g_printf()</function></link>, <link linkend="g-fprintf"><function>g_fprintf()</function></link>, <link linkend="g-sprintf"><function>g_sprintf()</function></link>, <link linkend="g-snprintf"><function>g_snprintf()</function></link>,
197 <link linkend="g-vprintf"><function>g_vprintf()</function></link>, <link linkend="g-vfprintf"><function>g_vfprintf()</function></link>, <link linkend="g-vsprintf"><function>g_vsprintf()</function></link> and <link linkend="g-vsnprintf"><function>g_vsnprintf()</function></link> are declared in
198 the header <filename>gprintf.h</filename> which is <emphasis>not</emphasis>
199 included in <filename>glib.h</filename> (otherwise using
200 <filename>glib.h</filename> would drag in <filename>stdio.h</filename>), so
201 you'll have to explicitly include <literal>&lt;glib/gprintf.h&gt;</literal>
202 in order to use the GLib <link linkend="printf"><function>printf()</function></link> functions.
203 </para>
204 <para id="string-precision">
205 While you may use the <link linkend="printf"><function>printf()</function></link> functions to format UTF-8 strings, notice that
206 the precision of a <literal>&percnt;Ns</literal> parameter is interpreted as the
207 number of <emphasis>bytes</emphasis>, not <emphasis>characters</emphasis> to print.
208 On top of that, the GNU libc implementation of the <link linkend="printf"><function>printf()</function></link> functions has the "feature"
209 that it checks that the string given for the <literal>&percnt;Ns</literal> parameter
210 consists of a whole number of characters in the current encoding. So, unless you
211 are sure you are always going to be in an UTF-8 locale or your know your text is restricted
212 to ASCII, avoid using <literal>&percnt;Ns</literal>.
213 If your intention is to format strings for a certain number of columns, then
214 <literal>&percnt;Ns</literal> is not a correct solution anyway, since it fails to take
215 wide characters (see <link linkend="g-unichar-iswide"><function>g_unichar_iswide()</function></link>) into account.
216 </para>
217 </refsect1>
218
219 <refsect1 id="glib-String-Utility-Functions.details" role="details">
220 <title role="details.title">Details</title>
221 <refsect2 id="g-strdup" role="function">
222 <title>g_strdup ()</title>
223 <indexterm zone="g-strdup"><primary sortas="strdup">g_strdup</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strdup                            (const <link linkend="gchar">gchar</link> *str);</programlisting>
224 <para>
225 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>.
226 The returned string should be freed with <link linkend="g-free"><function>g_free()</function></link> 
227 when no longer needed.</para>
228 <para>
229 </para><variablelist role="params">
230 <varlistentry><term><parameter>str</parameter>&#160;:</term>
231 <listitem><simpara> the string to duplicate
232 </simpara></listitem></varlistentry>
233 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated copy of <parameter>str</parameter>
234 </simpara></listitem></varlistentry>
235 </variablelist></refsect2>
236 <refsect2 id="g-strndup" role="function">
237 <title>g_strndup ()</title>
238 <indexterm zone="g-strndup"><primary sortas="strndup">g_strndup</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strndup                           (const <link linkend="gchar">gchar</link> *str,
239                                                          <link linkend="gsize">gsize</link> n);</programlisting>
240 <para>
241 Duplicates the first <parameter>n</parameter> bytes of a string, returning a newly-allocated
242 buffer <parameter>n</parameter> + 1 bytes long which will always be nul-terminated.
243 If <parameter>str</parameter> is less than <parameter>n</parameter> bytes long the buffer is padded with nuls.
244 If <parameter>str</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link> it returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
245 The returned value should be freed when no longer needed.
246 </para>
247 <para>
248 <note><para>
249 To copy a number of characters from a UTF-8 encoded string, use
250 <link linkend="g-utf8-strncpy"><function>g_utf8_strncpy()</function></link> instead.
251 </para></note></para>
252 <para>
253 </para><variablelist role="params">
254 <varlistentry><term><parameter>str</parameter>&#160;:</term>
255 <listitem><simpara> the string to duplicate
256 </simpara></listitem></varlistentry>
257 <varlistentry><term><parameter>n</parameter>&#160;:</term>
258 <listitem><simpara> the maximum number of bytes to copy from <parameter>str</parameter>
259 </simpara></listitem></varlistentry>
260 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated buffer containing the first <parameter>n</parameter> bytes 
261          of <parameter>str</parameter>, nul-terminated 
262 </simpara></listitem></varlistentry>
263 </variablelist></refsect2>
264 <refsect2 id="g-strdupv" role="function">
265 <title>g_strdupv ()</title>
266 <indexterm zone="g-strdupv"><primary sortas="strdupv">g_strdupv</primary></indexterm><programlisting><link linkend="gchar">gchar</link>**             g_strdupv                           (<link linkend="gchar">gchar</link> **str_array);</programlisting>
267 <para>
268 Copies <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings. The copy is a deep copy;
269 the new array should be freed by first freeing each string, then
270 the array itself. <link linkend="g-strfreev"><function>g_strfreev()</function></link> does this for you. If called
271 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>
272 <para>
273 </para><variablelist role="params">
274 <varlistentry><term><parameter>str_array</parameter>&#160;:</term>
275 <listitem><simpara> <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings.
276 </simpara></listitem></varlistentry>
277 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings.
278 </simpara></listitem></varlistentry>
279 </variablelist></refsect2>
280 <refsect2 id="g-strnfill" role="function">
281 <title>g_strnfill ()</title>
282 <indexterm zone="g-strnfill"><primary sortas="strnfill">g_strnfill</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strnfill                          (<link linkend="gsize">gsize</link> length,
283                                                          <link linkend="gchar">gchar</link> fill_char);</programlisting>
284 <para>
285 Creates a new string <parameter>length</parameter> bytes long filled with <parameter>fill_char</parameter>.
286 The returned string should be freed when no longer needed.</para>
287 <para>
288 </para><variablelist role="params">
289 <varlistentry><term><parameter>length</parameter>&#160;:</term>
290 <listitem><simpara> the length of the new string
291 </simpara></listitem></varlistentry>
292 <varlistentry><term><parameter>fill_char</parameter>&#160;:</term>
293 <listitem><simpara> the byte to fill the string with
294 </simpara></listitem></varlistentry>
295 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string filled the <parameter>fill_char</parameter>
296 </simpara></listitem></varlistentry>
297 </variablelist></refsect2>
298 <refsect2 id="g-stpcpy" role="function">
299 <title>g_stpcpy ()</title>
300 <indexterm zone="g-stpcpy"><primary sortas="stpcpy">g_stpcpy</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_stpcpy                            (<link linkend="gchar">gchar</link> *dest,
301                                                          const <link linkend="char">char</link> *src);</programlisting>
302 <para>
303 Copies a nul-terminated string into the dest buffer, include the
304 trailing nul, and return a pointer to the trailing nul byte.
305 This is useful for concatenating multiple strings together
306 without having to repeatedly scan for the end.</para>
307 <para>
308 </para><variablelist role="params">
309 <varlistentry><term><parameter>dest</parameter>&#160;:</term>
310 <listitem><simpara> destination buffer.
311 </simpara></listitem></varlistentry>
312 <varlistentry><term><parameter>src</parameter>&#160;:</term>
313 <listitem><simpara> source string.
314 </simpara></listitem></varlistentry>
315 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a pointer to trailing nul byte.
316 </simpara></listitem></varlistentry>
317 </variablelist></refsect2>
318 <refsect2 id="g-strstr-len" role="function">
319 <title>g_strstr_len ()</title>
320 <indexterm zone="g-strstr-len"><primary sortas="strstr_len">g_strstr_len</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             g_strstr_len                        (const <link linkend="gchar">gchar</link> *haystack,
321                                                          <link linkend="gssize">gssize</link> haystack_len,
322                                                          const <link linkend="gchar">gchar</link> *needle);</programlisting>
323 <para>
324 Searches the string <parameter>haystack</parameter> for the first occurrence
325 of the string <parameter>needle</parameter>, limiting the length of the search
326 to <parameter>haystack_len</parameter>.</para>
327 <para>
328 </para><variablelist role="params">
329 <varlistentry><term><parameter>haystack</parameter>&#160;:</term>
330 <listitem><simpara> a string.
331 </simpara></listitem></varlistentry>
332 <varlistentry><term><parameter>haystack_len</parameter>&#160;:</term>
333 <listitem><simpara> the maximum length of <parameter>haystack</parameter>. Note that -1 is
334 a valid length, if <parameter>haystack</parameter> is nul-terminated, meaning it will
335 search through the whole string.
336 </simpara></listitem></varlistentry>
337 <varlistentry><term><parameter>needle</parameter>&#160;:</term>
338 <listitem><simpara> the string to search for.
339 </simpara></listitem></varlistentry>
340 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a pointer to the found occurrence, or
341    <link linkend="NULL--CAPS"><literal>NULL</literal></link> if not found.
342 </simpara></listitem></varlistentry>
343 </variablelist></refsect2>
344 <refsect2 id="g-strrstr" role="function">
345 <title>g_strrstr ()</title>
346 <indexterm zone="g-strrstr"><primary sortas="strrstr">g_strrstr</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             g_strrstr                           (const <link linkend="gchar">gchar</link> *haystack,
347                                                          const <link linkend="gchar">gchar</link> *needle);</programlisting>
348 <para>
349 Searches the string <parameter>haystack</parameter> for the last occurrence
350 of the string <parameter>needle</parameter>.</para>
351 <para>
352 </para><variablelist role="params">
353 <varlistentry><term><parameter>haystack</parameter>&#160;:</term>
354 <listitem><simpara> a nul-terminated string.
355 </simpara></listitem></varlistentry>
356 <varlistentry><term><parameter>needle</parameter>&#160;:</term>
357 <listitem><simpara> the nul-terminated string to search for.
358 </simpara></listitem></varlistentry>
359 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a pointer to the found occurrence, or
360    <link linkend="NULL--CAPS"><literal>NULL</literal></link> if not found.
361 </simpara></listitem></varlistentry>
362 </variablelist></refsect2>
363 <refsect2 id="g-strrstr-len" role="function">
364 <title>g_strrstr_len ()</title>
365 <indexterm zone="g-strrstr-len"><primary sortas="strrstr_len">g_strrstr_len</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             g_strrstr_len                       (const <link linkend="gchar">gchar</link> *haystack,
366                                                          <link linkend="gssize">gssize</link> haystack_len,
367                                                          const <link linkend="gchar">gchar</link> *needle);</programlisting>
368 <para>
369 Searches the string <parameter>haystack</parameter> for the last occurrence
370 of the string <parameter>needle</parameter>, limiting the length of the search
371 to <parameter>haystack_len</parameter>.</para>
372 <para>
373 </para><variablelist role="params">
374 <varlistentry><term><parameter>haystack</parameter>&#160;:</term>
375 <listitem><simpara> a nul-terminated string.
376 </simpara></listitem></varlistentry>
377 <varlistentry><term><parameter>haystack_len</parameter>&#160;:</term>
378 <listitem><simpara> the maximum length of <parameter>haystack</parameter>.
379 </simpara></listitem></varlistentry>
380 <varlistentry><term><parameter>needle</parameter>&#160;:</term>
381 <listitem><simpara> the nul-terminated string to search for.
382 </simpara></listitem></varlistentry>
383 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a pointer to the found occurrence, or
384    <link linkend="NULL--CAPS"><literal>NULL</literal></link> if not found.
385 </simpara></listitem></varlistentry>
386 </variablelist></refsect2>
387 <refsect2 id="g-str-has-prefix" role="function" condition="since:2.2">
388 <title>g_str_has_prefix ()</title>
389 <indexterm zone="g-str-has-prefix" role="2.2"><primary sortas="str_has_prefix">g_str_has_prefix</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_str_has_prefix                    (const <link linkend="gchar">gchar</link> *str,
390                                                          const <link linkend="gchar">gchar</link> *prefix);</programlisting>
391 <para>
392 Looks whether the string <parameter>str</parameter> begins with <parameter>prefix</parameter>.</para>
393 <para>
394 </para><variablelist role="params">
395 <varlistentry><term><parameter>str</parameter>&#160;:</term>
396 <listitem><simpara> a nul-terminated string.
397 </simpara></listitem></varlistentry>
398 <varlistentry><term><parameter>prefix</parameter>&#160;:</term>
399 <listitem><simpara> the nul-terminated prefix to look for.
400 </simpara></listitem></varlistentry>
401 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter> begins with <parameter>prefix</parameter>, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
402
403 </simpara></listitem></varlistentry>
404 </variablelist><para role="since">Since 2.2</para></refsect2>
405 <refsect2 id="g-str-has-suffix" role="function" condition="since:2.2">
406 <title>g_str_has_suffix ()</title>
407 <indexterm zone="g-str-has-suffix" role="2.2"><primary sortas="str_has_suffix">g_str_has_suffix</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_str_has_suffix                    (const <link linkend="gchar">gchar</link> *str,
408                                                          const <link linkend="gchar">gchar</link> *suffix);</programlisting>
409 <para>
410 Looks whether the string <parameter>str</parameter> ends with <parameter>suffix</parameter>.</para>
411 <para>
412 </para><variablelist role="params">
413 <varlistentry><term><parameter>str</parameter>&#160;:</term>
414 <listitem><simpara> a nul-terminated string.
415 </simpara></listitem></varlistentry>
416 <varlistentry><term><parameter>suffix</parameter>&#160;:</term>
417 <listitem><simpara> the nul-terminated suffix to look for.
418 </simpara></listitem></varlistentry>
419 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>str</parameter> end with <parameter>suffix</parameter>, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
420
421 </simpara></listitem></varlistentry>
422 </variablelist><para role="since">Since 2.2</para></refsect2>
423 <refsect2 id="g-strcmp0" role="function" condition="since:2.16">
424 <title>g_strcmp0 ()</title>
425 <indexterm zone="g-strcmp0" role="2.16"><primary sortas="strcmp0">g_strcmp0</primary></indexterm><programlisting><link linkend="int">int</link>                 g_strcmp0                           (const <link linkend="char">char</link> *str1,
426                                                          const <link linkend="char">char</link> *str2);</programlisting>
427 <para>
428 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> 
429 gracefully by sorting it before non-<link linkend="NULL--CAPS"><literal>NULL</literal></link> strings.</para>
430 <para>
431 </para><variablelist role="params">
432 <varlistentry><term><parameter>str1</parameter>&#160;:</term>
433 <listitem><simpara> a C string or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
434 </simpara></listitem></varlistentry>
435 <varlistentry><term><parameter>str2</parameter>&#160;:</term>
436 <listitem><simpara> another C string or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
437 </simpara></listitem></varlistentry>
438 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> -1, 0 or 1, if <parameter>str1</parameter> is &lt;, == or &gt; than <parameter>str2</parameter>.
439
440 </simpara></listitem></varlistentry>
441 </variablelist><para role="since">Since 2.16</para></refsect2>
442 <refsect2 id="g-strlcpy" role="function">
443 <title>g_strlcpy ()</title>
444 <indexterm zone="g-strlcpy"><primary sortas="strlcpy">g_strlcpy</primary></indexterm><programlisting><link linkend="gsize">gsize</link>               g_strlcpy                           (<link linkend="gchar">gchar</link> *dest,
445                                                          const <link linkend="gchar">gchar</link> *src,
446                                                          <link linkend="gsize">gsize</link> dest_size);</programlisting>
447 <para>
448 Portability wrapper that calls <link linkend="strlcpy"><function>strlcpy()</function></link> on systems which have it, 
449 and emulates <link linkend="strlcpy"><function>strlcpy()</function></link> otherwise. Copies <parameter>src</parameter> to <parameter>dest</parameter>; <parameter>dest</parameter> is 
450 guaranteed to be nul-terminated; <parameter>src</parameter> must be nul-terminated; 
451 <parameter>dest_size</parameter> is the buffer size, not the number of chars to copy. 
452 </para>
453 <para>
454 At most dest_size - 1 characters will be copied. Always nul-terminates
455 (unless dest_size == 0). This function does <emphasis>not</emphasis> 
456 allocate memory. Unlike <link linkend="strncpy"><function>strncpy()</function></link>, this function doesn't pad dest (so 
457 it's often faster). It returns the size of the attempted result, 
458 strlen (src), so if <parameter>retval</parameter> &gt;= <parameter>dest_size</parameter>, truncation occurred.
459 </para>
460 <para>
461 <note><para>Caveat: <link linkend="strlcpy"><function>strlcpy()</function></link> is supposedly more secure than
462 <link linkend="strcpy"><function>strcpy()</function></link> or <link linkend="strncpy"><function>strncpy()</function></link>, but if you really want to avoid screwups, 
463 <link linkend="g-strdup"><function>g_strdup()</function></link> is an even better idea.</para></note></para>
464 <para>
465 </para><variablelist role="params">
466 <varlistentry><term><parameter>dest</parameter>&#160;:</term>
467 <listitem><simpara> destination buffer
468 </simpara></listitem></varlistentry>
469 <varlistentry><term><parameter>src</parameter>&#160;:</term>
470 <listitem><simpara> source buffer
471 </simpara></listitem></varlistentry>
472 <varlistentry><term><parameter>dest_size</parameter>&#160;:</term>
473 <listitem><simpara> length of <parameter>dest</parameter> in bytes
474 </simpara></listitem></varlistentry>
475 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> length of <parameter>src</parameter>
476 </simpara></listitem></varlistentry>
477 </variablelist></refsect2>
478 <refsect2 id="g-strlcat" role="function">
479 <title>g_strlcat ()</title>
480 <indexterm zone="g-strlcat"><primary sortas="strlcat">g_strlcat</primary></indexterm><programlisting><link linkend="gsize">gsize</link>               g_strlcat                           (<link linkend="gchar">gchar</link> *dest,
481                                                          const <link linkend="gchar">gchar</link> *src,
482                                                          <link linkend="gsize">gsize</link> dest_size);</programlisting>
483 <para>
484 Portability wrapper that calls <link linkend="strlcat"><function>strlcat()</function></link> on systems which have it, 
485 and emulates it otherwise. Appends nul-terminated <parameter>src</parameter> string to <parameter>dest</parameter>, 
486 guaranteeing nul-termination for <parameter>dest</parameter>. The total size of <parameter>dest</parameter> won't 
487 exceed <parameter>dest_size</parameter>. 
488 </para>
489 <para>
490 At most dest_size - 1 characters will be copied.
491 Unlike strncat, dest_size is the full size of dest, not the space left over.
492 This function does NOT allocate memory.
493 This always NUL terminates (unless siz == 0 or there were no NUL characters
494 in the dest_size characters of dest to start with).</para>
495 <para>
496 </para><variablelist role="params">
497 <varlistentry><term><parameter>dest</parameter>&#160;:</term>
498 <listitem><simpara> destination buffer, already containing one nul-terminated string
499 </simpara></listitem></varlistentry>
500 <varlistentry><term><parameter>src</parameter>&#160;:</term>
501 <listitem><simpara> source buffer
502 </simpara></listitem></varlistentry>
503 <varlistentry><term><parameter>dest_size</parameter>&#160;:</term>
504 <listitem><simpara> length of <parameter>dest</parameter> buffer in bytes (not length of existing string 
505     inside <parameter>dest</parameter>)
506 </simpara></listitem></varlistentry>
507 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>size of attempted result, which is
508 MIN (dest_size, strlen (original dest)) + strlen (src),
509 so if retval &gt;= dest_size, truncation occurred.
510
511 <note><para>Caveat: this is supposedly a more secure alternative to 
512 <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 
513 to mess up.</para></note>
514
515 </simpara></listitem></varlistentry>
516 </variablelist></refsect2>
517 <refsect2 id="g-strdup-printf" role="function">
518 <title>g_strdup_printf ()</title>
519 <indexterm zone="g-strdup-printf"><primary sortas="strdup_printf">g_strdup_printf</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strdup_printf                     (const <link linkend="gchar">gchar</link> *format,
520                                                          ...);</programlisting>
521 <para>
522 Similar to the standard C <link linkend="sprintf"><function>sprintf()</function></link> function but safer, since it 
523 calculates the maximum space required and allocates memory to hold 
524 the result. The returned string should be freed with <link linkend="g-free"><function>g_free()</function></link> when no 
525 longer needed.</para>
526 <para>
527 </para><variablelist role="params">
528 <varlistentry><term><parameter>format</parameter>&#160;:</term>
529 <listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
530     <link linkend="string-precision">string precision pitfalls</link>
531 </simpara></listitem></varlistentry>
532 <varlistentry><term><parameter>...</parameter>&#160;:</term>
533 <listitem><simpara> the parameters to insert into the format string
534 </simpara></listitem></varlistentry>
535 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string holding the result
536 </simpara></listitem></varlistentry>
537 </variablelist></refsect2>
538 <refsect2 id="g-strdup-vprintf" role="function">
539 <title>g_strdup_vprintf ()</title>
540 <indexterm zone="g-strdup-vprintf"><primary sortas="strdup_vprintf">g_strdup_vprintf</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strdup_vprintf                    (const <link linkend="gchar">gchar</link> *format,
541                                                          <link linkend="va-list">va_list</link> args);</programlisting>
542 <para>
543 Similar to the standard C <link linkend="vsprintf"><function>vsprintf()</function></link> function but safer, since it 
544 calculates the maximum space required and allocates memory to hold 
545 the result. The returned string should be freed with <link linkend="g-free"><function>g_free()</function></link> when 
546 no longer needed.
547 </para>
548 <para>
549 See also <link linkend="g-vasprintf"><function>g_vasprintf()</function></link>, which offers the same functionality, but 
550 additionally returns the length of the allocated string.</para>
551 <para>
552 </para><variablelist role="params">
553 <varlistentry><term><parameter>format</parameter>&#160;:</term>
554 <listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
555     <link linkend="string-precision">string precision pitfalls</link>
556 </simpara></listitem></varlistentry>
557 <varlistentry><term><parameter>args</parameter>&#160;:</term>
558 <listitem><simpara> the list of parameters to insert into the format string
559 </simpara></listitem></varlistentry>
560 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string holding the result
561 </simpara></listitem></varlistentry>
562 </variablelist></refsect2>
563 <refsect2 id="g-printf" role="function" condition="since:2.2">
564 <title>g_printf ()</title>
565 <indexterm zone="g-printf" role="2.2"><primary sortas="printf">g_printf</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_printf                            (<link linkend="gchar">gchar</link> const *format,
566                                                          ...);</programlisting>
567 <para>
568 An implementation of the standard <link linkend="printf"><function>printf()</function></link> function which supports 
569 positional parameters, as specified in the Single Unix Specification.</para>
570 <para>
571 </para><variablelist role="params">
572 <varlistentry><term><parameter>format</parameter>&#160;:</term>
573 <listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice 
574          <link linkend="string-precision">string precision pitfalls</link>.
575 </simpara></listitem></varlistentry>
576 <varlistentry><term><parameter>...</parameter>&#160;:</term>
577 <listitem><simpara> the arguments to insert in the output.
578 </simpara></listitem></varlistentry>
579 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.
580
581 </simpara></listitem></varlistentry>
582 </variablelist><para role="since">Since 2.2</para></refsect2>
583 <refsect2 id="g-vprintf" role="function" condition="since:2.2">
584 <title>g_vprintf ()</title>
585 <indexterm zone="g-vprintf" role="2.2"><primary sortas="vprintf">g_vprintf</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_vprintf                           (<link linkend="gchar">gchar</link> const *format,
586                                                          <link linkend="va-list">va_list</link> args);</programlisting>
587 <para>
588 An implementation of the standard <link linkend="vprintf"><function>vprintf()</function></link> function which supports 
589 positional parameters, as specified in the Single Unix Specification.</para>
590 <para>
591 </para><variablelist role="params">
592 <varlistentry><term><parameter>format</parameter>&#160;:</term>
593 <listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice 
594          <link linkend="string-precision">string precision pitfalls</link>.
595 </simpara></listitem></varlistentry>
596 <varlistentry><term><parameter>args</parameter>&#160;:</term>
597 <listitem><simpara> the list of arguments to insert in the output.
598 </simpara></listitem></varlistentry>
599 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.
600
601 </simpara></listitem></varlistentry>
602 </variablelist><para role="since">Since 2.2</para></refsect2>
603 <refsect2 id="g-fprintf" role="function" condition="since:2.2">
604 <title>g_fprintf ()</title>
605 <indexterm zone="g-fprintf" role="2.2"><primary sortas="fprintf">g_fprintf</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_fprintf                           (<link linkend="FILE--CAPS">FILE</link> *file,
606                                                          <link linkend="gchar">gchar</link> const *format,
607                                                          ...);</programlisting>
608 <para>
609 An implementation of the standard <link linkend="fprintf"><function>fprintf()</function></link> function which supports 
610 positional parameters, as specified in the Single Unix Specification.</para>
611 <para>
612 </para><variablelist role="params">
613 <varlistentry><term><parameter>file</parameter>&#160;:</term>
614 <listitem><simpara> the stream to write to.
615 </simpara></listitem></varlistentry>
616 <varlistentry><term><parameter>format</parameter>&#160;:</term>
617 <listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice 
618          <link linkend="string-precision">string precision pitfalls</link>.
619 </simpara></listitem></varlistentry>
620 <varlistentry><term><parameter>...</parameter>&#160;:</term>
621 <listitem><simpara> the arguments to insert in the output.
622 </simpara></listitem></varlistentry>
623 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.
624
625 </simpara></listitem></varlistentry>
626 </variablelist><para role="since">Since 2.2</para></refsect2>
627 <refsect2 id="g-vfprintf" role="function" condition="since:2.2">
628 <title>g_vfprintf ()</title>
629 <indexterm zone="g-vfprintf" role="2.2"><primary sortas="vfprintf">g_vfprintf</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_vfprintf                          (<link linkend="FILE--CAPS">FILE</link> *file,
630                                                          <link linkend="gchar">gchar</link> const *format,
631                                                          <link linkend="va-list">va_list</link> args);</programlisting>
632 <para>
633 An implementation of the standard <link linkend="fprintf"><function>fprintf()</function></link> function which supports 
634 positional parameters, as specified in the Single Unix Specification.</para>
635 <para>
636 </para><variablelist role="params">
637 <varlistentry><term><parameter>file</parameter>&#160;:</term>
638 <listitem><simpara> the stream to write to.
639 </simpara></listitem></varlistentry>
640 <varlistentry><term><parameter>format</parameter>&#160;:</term>
641 <listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice 
642          <link linkend="string-precision">string precision pitfalls</link>.
643 </simpara></listitem></varlistentry>
644 <varlistentry><term><parameter>args</parameter>&#160;:</term>
645 <listitem><simpara> the list of arguments to insert in the output.
646 </simpara></listitem></varlistentry>
647 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.
648
649 </simpara></listitem></varlistentry>
650 </variablelist><para role="since">Since 2.2</para></refsect2>
651 <refsect2 id="g-sprintf" role="function" condition="since:2.2">
652 <title>g_sprintf ()</title>
653 <indexterm zone="g-sprintf" role="2.2"><primary sortas="sprintf">g_sprintf</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_sprintf                           (<link linkend="gchar">gchar</link> *string,
654                                                          <link linkend="gchar">gchar</link> const *format,
655                                                          ...);</programlisting>
656 <para>
657 An implementation of the standard <link linkend="sprintf"><function>sprintf()</function></link> function which supports 
658 positional parameters, as specified in the Single Unix Specification.</para>
659 <para>
660 </para><variablelist role="params">
661 <varlistentry><term><parameter>string</parameter>&#160;:</term>
662 <listitem><simpara> A pointer to a memory buffer to contain the resulting string. It 
663          is up to the caller to ensure that the allocated buffer is large 
664          enough to hold the formatted result
665 </simpara></listitem></varlistentry>
666 <varlistentry><term><parameter>format</parameter>&#160;:</term>
667 <listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice 
668          <link linkend="string-precision">string precision pitfalls</link>.
669 </simpara></listitem></varlistentry>
670 <varlistentry><term><parameter>...</parameter>&#160;:</term>
671 <listitem><simpara> the arguments to insert in the output.
672 </simpara></listitem></varlistentry>
673 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.
674
675 </simpara></listitem></varlistentry>
676 </variablelist><para role="since">Since 2.2</para></refsect2>
677 <refsect2 id="g-vsprintf" role="function" condition="since:2.2">
678 <title>g_vsprintf ()</title>
679 <indexterm zone="g-vsprintf" role="2.2"><primary sortas="vsprintf">g_vsprintf</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_vsprintf                          (<link linkend="gchar">gchar</link> *string,
680                                                          <link linkend="gchar">gchar</link> const *format,
681                                                          <link linkend="va-list">va_list</link> args);</programlisting>
682 <para>
683 An implementation of the standard <link linkend="vsprintf"><function>vsprintf()</function></link> function which supports 
684 positional parameters, as specified in the Single Unix Specification.</para>
685 <para>
686 </para><variablelist role="params">
687 <varlistentry><term><parameter>string</parameter>&#160;:</term>
688 <listitem><simpara> the buffer to hold the output.
689 </simpara></listitem></varlistentry>
690 <varlistentry><term><parameter>format</parameter>&#160;:</term>
691 <listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice 
692          <link linkend="string-precision">string precision pitfalls</link>.
693 </simpara></listitem></varlistentry>
694 <varlistentry><term><parameter>args</parameter>&#160;:</term>
695 <listitem><simpara> the list of arguments to insert in the output.
696 </simpara></listitem></varlistentry>
697 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.
698
699 </simpara></listitem></varlistentry>
700 </variablelist><para role="since">Since 2.2</para></refsect2>
701 <refsect2 id="g-snprintf" role="function">
702 <title>g_snprintf ()</title>
703 <indexterm zone="g-snprintf"><primary sortas="snprintf">g_snprintf</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_snprintf                          (<link linkend="gchar">gchar</link> *string,
704                                                          <link linkend="gulong">gulong</link> n,
705                                                          <link linkend="gchar">gchar</link> const *format,
706                                                          ...);</programlisting>
707 <para>
708 A safer form of the standard <link linkend="sprintf"><function>sprintf()</function></link> function. The output is guaranteed
709 to not exceed <parameter>n</parameter> characters (including the terminating nul character), so 
710 it is easy to ensure that a buffer overflow cannot occur.
711 </para>
712 <para>
713 See also <link linkend="g-strdup-printf"><function>g_strdup_printf()</function></link>.
714 </para>
715 <para>
716 In versions of GLib prior to 1.2.3, this function may return -1 if the 
717 output was truncated, and the truncated string may not be nul-terminated. 
718 In versions prior to 1.3.12, this function returns the length of the output 
719 string.
720 </para>
721 <para>
722 The return value of <link linkend="g-snprintf"><function>g_snprintf()</function></link> conforms to the <link linkend="snprintf"><function>snprintf()</function></link>
723 function as standardized in ISO C99. Note that this is different from 
724 traditional <link linkend="snprintf"><function>snprintf()</function></link>, which returns the length of the output string.
725 </para>
726 <para>
727 The format string may contain positional parameters, as specified in 
728 the Single Unix Specification.</para>
729 <para>
730 </para><variablelist role="params">
731 <varlistentry><term><parameter>string</parameter>&#160;:</term>
732 <listitem><simpara> the buffer to hold the output.
733 </simpara></listitem></varlistentry>
734 <varlistentry><term><parameter>n</parameter>&#160;:</term>
735 <listitem><simpara> the maximum number of bytes to produce (including the 
736     terminating nul character).
737 </simpara></listitem></varlistentry>
738 <varlistentry><term><parameter>format</parameter>&#160;:</term>
739 <listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice 
740          <link linkend="string-precision">string precision pitfalls</link>.
741 </simpara></listitem></varlistentry>
742 <varlistentry><term><parameter>...</parameter>&#160;:</term>
743 <listitem><simpara> the arguments to insert in the output.
744 </simpara></listitem></varlistentry>
745 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes which would be produced if the buffer 
746     was large enough.
747 </simpara></listitem></varlistentry>
748 </variablelist></refsect2>
749 <refsect2 id="g-vsnprintf" role="function">
750 <title>g_vsnprintf ()</title>
751 <indexterm zone="g-vsnprintf"><primary sortas="vsnprintf">g_vsnprintf</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_vsnprintf                         (<link linkend="gchar">gchar</link> *string,
752                                                          <link linkend="gulong">gulong</link> n,
753                                                          <link linkend="gchar">gchar</link> const *format,
754                                                          <link linkend="va-list">va_list</link> args);</programlisting>
755 <para>
756 A safer form of the standard <link linkend="vsprintf"><function>vsprintf()</function></link> function. The output is guaranteed
757 to not exceed <parameter>n</parameter> characters (including the terminating nul character), so 
758 it is easy to ensure that a buffer overflow cannot occur.
759 </para>
760 <para>
761 See also <link linkend="g-strdup-vprintf"><function>g_strdup_vprintf()</function></link>.
762 </para>
763 <para>
764 In versions of GLib prior to 1.2.3, this function may return -1 if the 
765 output was truncated, and the truncated string may not be nul-terminated.
766 In versions prior to 1.3.12, this function returns the length of the output 
767 string.
768 </para>
769 <para>
770 The return value of <link linkend="g-vsnprintf"><function>g_vsnprintf()</function></link> conforms to the <link linkend="vsnprintf"><function>vsnprintf()</function></link> function 
771 as standardized in ISO C99. Note that this is different from traditional 
772 <link linkend="vsnprintf"><function>vsnprintf()</function></link>, which returns the length of the output string.
773 </para>
774 <para>
775 The format string may contain positional parameters, as specified in 
776 the Single Unix Specification.</para>
777 <para>
778 </para><variablelist role="params">
779 <varlistentry><term><parameter>string</parameter>&#160;:</term>
780 <listitem><simpara> the buffer to hold the output.
781 </simpara></listitem></varlistentry>
782 <varlistentry><term><parameter>n</parameter>&#160;:</term>
783 <listitem><simpara> the maximum number of bytes to produce (including the 
784     terminating nul character).
785 </simpara></listitem></varlistentry>
786 <varlistentry><term><parameter>format</parameter>&#160;:</term>
787 <listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice 
788          <link linkend="string-precision">string precision pitfalls</link>.
789 </simpara></listitem></varlistentry>
790 <varlistentry><term><parameter>args</parameter>&#160;:</term>
791 <listitem><simpara> the list of arguments to insert in the output.
792 </simpara></listitem></varlistentry>
793 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes which would be produced if the buffer 
794  was large enough.
795 </simpara></listitem></varlistentry>
796 </variablelist></refsect2>
797 <refsect2 id="g-vasprintf" role="function" condition="since:2.4">
798 <title>g_vasprintf ()</title>
799 <indexterm zone="g-vasprintf" role="2.4"><primary sortas="vasprintf">g_vasprintf</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_vasprintf                         (<link linkend="gchar">gchar</link> **string,
800                                                          <link linkend="gchar">gchar</link> const *format,
801                                                          <link linkend="va-list">va_list</link> args);</programlisting>
802 <para>
803 An implementation of the GNU <link linkend="vasprintf"><function>vasprintf()</function></link> function which supports 
804 positional parameters, as specified in the Single Unix Specification.
805 This function is similar to <link linkend="g-vsprintf"><function>g_vsprintf()</function></link>, except that it allocates a 
806 string to hold the output, instead of putting the output in a buffer 
807 you allocate in advance.</para>
808 <para>
809 </para><variablelist role="params">
810 <varlistentry><term><parameter>string</parameter>&#160;:</term>
811 <listitem><simpara> the return location for the newly-allocated string.
812 </simpara></listitem></varlistentry>
813 <varlistentry><term><parameter>format</parameter>&#160;:</term>
814 <listitem><simpara> a standard <link linkend="printf"><function>printf()</function></link> format string, but notice
815          <link linkend="string-precision">string precision pitfalls</link>.
816 </simpara></listitem></varlistentry>
817 <varlistentry><term><parameter>args</parameter>&#160;:</term>
818 <listitem><simpara> the list of arguments to insert in the output.
819 </simpara></listitem></varlistentry>
820 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of bytes printed.
821
822 </simpara></listitem></varlistentry>
823 </variablelist><para role="since">Since 2.4</para></refsect2>
824 <refsect2 id="g-printf-string-upper-bound" role="function">
825 <title>g_printf_string_upper_bound ()</title>
826 <indexterm zone="g-printf-string-upper-bound"><primary sortas="printf_string_upper_bound">g_printf_string_upper_bound</primary></indexterm><programlisting><link linkend="gsize">gsize</link>               g_printf_string_upper_bound         (const <link linkend="gchar">gchar</link> *format,
827                                                          <link linkend="va-list">va_list</link> args);</programlisting>
828 <para>
829 Calculates the maximum space needed to store the output of the <link linkend="sprintf"><function>sprintf()</function></link>
830 function.
831 </para><variablelist role="params">
832 <varlistentry><term><parameter>format</parameter>&#160;:</term>
833 <listitem><simpara>the format string. See the <link linkend="printf"><function>printf()</function></link> documentation.
834 </simpara></listitem></varlistentry>
835 <varlistentry><term><parameter>args</parameter>&#160;:</term>
836 <listitem><simpara>the parameters to be inserted into the format string.
837 </simpara></listitem></varlistentry>
838 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the maximum space needed to store the formatted string.
839 </simpara></listitem></varlistentry>
840 </variablelist></refsect2>
841 <refsect2 id="g-ascii-isalnum" role="function">
842 <title>g_ascii_isalnum ()</title>
843 <indexterm zone="g-ascii-isalnum"><primary sortas="ascii_isalnum">g_ascii_isalnum</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_ascii_isalnum                     (<link linkend="gchar">gchar</link> c);</programlisting>
844 <para>
845 Determines whether a character is alphanumeric.
846 </para>
847 <para>
848 Unlike the standard C library <link linkend="isalnum"><function>isalnum()</function></link> function, this only
849 recognizes standard ASCII letters and ignores the locale, returning
850 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also unlike the standard
851 library function, this takes a <type>char</type>, not an <type>int</type>,
852 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
853 possibly non-ASCII character in.
854 </para><variablelist role="params">
855 <varlistentry><term><parameter>c</parameter>&#160;:</term>
856 <listitem><simpara>any character
857 </simpara></listitem></varlistentry>
858 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII alphanumeric character
859 </simpara></listitem></varlistentry>
860 </variablelist></refsect2>
861 <refsect2 id="g-ascii-isalpha" role="function">
862 <title>g_ascii_isalpha ()</title>
863 <indexterm zone="g-ascii-isalpha"><primary sortas="ascii_isalpha">g_ascii_isalpha</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_ascii_isalpha                     (<link linkend="gchar">gchar</link> c);</programlisting>
864 <para>
865 Determines whether a character is alphabetic (i.e. a letter).
866 </para>
867 <para>
868 Unlike the standard C library <link linkend="isalpha"><function>isalpha()</function></link> function, this only
869 recognizes standard ASCII letters and ignores the locale, returning
870 <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also unlike the standard
871 library function, this takes a <type>char</type>, not an <type>int</type>,
872 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
873 possibly non-ASCII character in.
874 </para><variablelist role="params">
875 <varlistentry><term><parameter>c</parameter>&#160;:</term>
876 <listitem><simpara>any character
877 </simpara></listitem></varlistentry>
878 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII alphabetic character
879 </simpara></listitem></varlistentry>
880 </variablelist></refsect2>
881 <refsect2 id="g-ascii-iscntrl" role="function">
882 <title>g_ascii_iscntrl ()</title>
883 <indexterm zone="g-ascii-iscntrl"><primary sortas="ascii_iscntrl">g_ascii_iscntrl</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_ascii_iscntrl                     (<link linkend="gchar">gchar</link> c);</programlisting>
884 <para>
885 Determines whether a character is a control character.
886 </para>
887 <para>
888 Unlike the standard C library <link linkend="iscntrl"><function>iscntrl()</function></link> function, this only
889 recognizes standard ASCII control characters and ignores the locale,
890 returning <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also unlike the standard
891 library function, this takes a <type>char</type>, not an <type>int</type>,
892 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
893 possibly non-ASCII character in.
894 </para><variablelist role="params">
895 <varlistentry><term><parameter>c</parameter>&#160;:</term>
896 <listitem><simpara>any character
897 </simpara></listitem></varlistentry>
898 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII control character.
899 </simpara></listitem></varlistentry>
900 </variablelist></refsect2>
901 <refsect2 id="g-ascii-isdigit" role="function">
902 <title>g_ascii_isdigit ()</title>
903 <indexterm zone="g-ascii-isdigit"><primary sortas="ascii_isdigit">g_ascii_isdigit</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_ascii_isdigit                     (<link linkend="gchar">gchar</link> c);</programlisting>
904 <para>
905 Determines whether a character is digit (0-9).
906 </para>
907 <para>
908 Unlike the standard C library <link linkend="isdigit"><function>isdigit()</function></link> function,
909 this takes a <type>char</type>, not an <type>int</type>, so don't call it
910 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
911 non-ASCII character in.
912 </para><variablelist role="params">
913 <varlistentry><term><parameter>c</parameter>&#160;:</term>
914 <listitem><simpara>any character
915 </simpara></listitem></varlistentry>
916 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII digit.
917 </simpara></listitem></varlistentry>
918 </variablelist></refsect2>
919 <refsect2 id="g-ascii-isgraph" role="function">
920 <title>g_ascii_isgraph ()</title>
921 <indexterm zone="g-ascii-isgraph"><primary sortas="ascii_isgraph">g_ascii_isgraph</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_ascii_isgraph                     (<link linkend="gchar">gchar</link> c);</programlisting>
922 <para>
923 Determines whether a character is a printing character and not a space.
924 </para>
925 <para>
926 Unlike the standard C library <link linkend="isgraph"><function>isgraph()</function></link> function,
927 this only recognizes standard ASCII characters and ignores the locale,
928 returning <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also unlike the standard
929 library function, this takes a <type>char</type>, not an <type>int</type>,
930 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
931 possibly non-ASCII character in.
932 </para><variablelist role="params">
933 <varlistentry><term><parameter>c</parameter>&#160;:</term>
934 <listitem><simpara>any character
935 </simpara></listitem></varlistentry>
936 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII printing character other than space.
937 </simpara></listitem></varlistentry>
938 </variablelist></refsect2>
939 <refsect2 id="g-ascii-islower" role="function">
940 <title>g_ascii_islower ()</title>
941 <indexterm zone="g-ascii-islower"><primary sortas="ascii_islower">g_ascii_islower</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_ascii_islower                     (<link linkend="gchar">gchar</link> c);</programlisting>
942 <para>
943 Determines whether a character is an ASCII lower case letter.
944 </para>
945 <para>
946 Unlike the standard C library <link linkend="islower"><function>islower()</function></link> function,
947 this only recognizes standard ASCII letters and ignores the locale,
948 returning <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also unlike the standard
949 library function, this takes a <type>char</type>, not an <type>int</type>,
950 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>
951 before passing a possibly non-ASCII character in.
952 </para><variablelist role="params">
953 <varlistentry><term><parameter>c</parameter>&#160;:</term>
954 <listitem><simpara>any character
955 </simpara></listitem></varlistentry>
956 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII lower case letter
957 </simpara></listitem></varlistentry>
958 </variablelist></refsect2>
959 <refsect2 id="g-ascii-isprint" role="function">
960 <title>g_ascii_isprint ()</title>
961 <indexterm zone="g-ascii-isprint"><primary sortas="ascii_isprint">g_ascii_isprint</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_ascii_isprint                     (<link linkend="gchar">gchar</link> c);</programlisting>
962 <para>
963 Determines whether a character is a printing character.
964 </para>
965 <para>
966 Unlike the standard C library <link linkend="isprint"><function>isprint()</function></link> function,
967 this only recognizes standard ASCII characters and ignores the locale,
968 returning <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also unlike the standard
969 library function, this takes a <type>char</type>, not an <type>int</type>,
970 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
971 possibly non-ASCII character in.
972 </para><variablelist role="params">
973 <varlistentry><term><parameter>c</parameter>&#160;:</term>
974 <listitem><simpara>any character
975 </simpara></listitem></varlistentry>
976 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII printing character.
977 </simpara></listitem></varlistentry>
978 </variablelist></refsect2>
979 <refsect2 id="g-ascii-ispunct" role="function">
980 <title>g_ascii_ispunct ()</title>
981 <indexterm zone="g-ascii-ispunct"><primary sortas="ascii_ispunct">g_ascii_ispunct</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_ascii_ispunct                     (<link linkend="gchar">gchar</link> c);</programlisting>
982 <para>
983 Determines whether a character is a punctuation character.
984 </para>
985 <para>
986 Unlike the standard C library <link linkend="ispunct"><function>ispunct()</function></link> function,
987 this only recognizes standard ASCII letters and ignores the locale,
988 returning <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also unlike the standard
989 library function, this takes a <type>char</type>, not an <type>int</type>,
990 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
991 possibly non-ASCII character in.
992 </para><variablelist role="params">
993 <varlistentry><term><parameter>c</parameter>&#160;:</term>
994 <listitem><simpara>any character
995 </simpara></listitem></varlistentry>
996 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII punctuation character.
997 </simpara></listitem></varlistentry>
998 </variablelist></refsect2>
999 <refsect2 id="g-ascii-isspace" role="function">
1000 <title>g_ascii_isspace ()</title>
1001 <indexterm zone="g-ascii-isspace"><primary sortas="ascii_isspace">g_ascii_isspace</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_ascii_isspace                     (<link linkend="gchar">gchar</link> c);</programlisting>
1002 <para>
1003 Determines whether a character is a white-space character.
1004 </para>
1005 <para>
1006 Unlike the standard C library <link linkend="isspace"><function>isspace()</function></link> function,
1007 this only recognizes standard ASCII white-space and ignores the locale,
1008 returning <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also unlike the standard
1009 library function, this takes a <type>char</type>, not an <type>int</type>,
1010 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
1011 possibly non-ASCII character in.
1012 </para><variablelist role="params">
1013 <varlistentry><term><parameter>c</parameter>&#160;:</term>
1014 <listitem><simpara>any character
1015 </simpara></listitem></varlistentry>
1016 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII white-space character
1017 </simpara></listitem></varlistentry>
1018 </variablelist></refsect2>
1019 <refsect2 id="g-ascii-isupper" role="function">
1020 <title>g_ascii_isupper ()</title>
1021 <indexterm zone="g-ascii-isupper"><primary sortas="ascii_isupper">g_ascii_isupper</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_ascii_isupper                     (<link linkend="gchar">gchar</link> c);</programlisting>
1022 <para>
1023 Determines whether a character is an ASCII upper case letter.
1024 </para>
1025 <para>
1026 Unlike the standard C library <link linkend="isupper"><function>isupper()</function></link> function,
1027 this only recognizes standard ASCII letters and ignores the locale,
1028 returning <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> for all non-ASCII characters. Also unlike the standard
1029 library function, this takes a <type>char</type>, not an <type>int</type>,
1030 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>
1031 before passing a possibly non-ASCII character in.
1032 </para><variablelist role="params">
1033 <varlistentry><term><parameter>c</parameter>&#160;:</term>
1034 <listitem><simpara>any character
1035 </simpara></listitem></varlistentry>
1036 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII upper case letter
1037 </simpara></listitem></varlistentry>
1038 </variablelist></refsect2>
1039 <refsect2 id="g-ascii-isxdigit" role="function">
1040 <title>g_ascii_isxdigit ()</title>
1041 <indexterm zone="g-ascii-isxdigit"><primary sortas="ascii_isxdigit">g_ascii_isxdigit</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_ascii_isxdigit                    (<link linkend="gchar">gchar</link> c);</programlisting>
1042 <para>
1043 Determines whether a character is a hexadecimal-digit character.
1044 </para>
1045 <para>
1046 Unlike the standard C library <link linkend="isxdigit"><function>isxdigit()</function></link> function,
1047 this takes a <type>char</type>, not an <type>int</type>, so
1048 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
1049 possibly non-ASCII character in.
1050 </para><variablelist role="params">
1051 <varlistentry><term><parameter>c</parameter>&#160;:</term>
1052 <listitem><simpara>any character
1053 </simpara></listitem></varlistentry>
1054 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>c</parameter> is an ASCII hexadecimal-digit character.
1055 </simpara></listitem></varlistentry>
1056 </variablelist></refsect2>
1057 <refsect2 id="g-ascii-digit-value" role="function">
1058 <title>g_ascii_digit_value ()</title>
1059 <indexterm zone="g-ascii-digit-value"><primary sortas="ascii_digit_value">g_ascii_digit_value</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_ascii_digit_value                 (<link linkend="gchar">gchar</link> c);</programlisting>
1060 <para>
1061 Determines the numeric value of a character as a decimal
1062 digit. Differs from <link linkend="g-unichar-digit-value"><function>g_unichar_digit_value()</function></link> because it takes
1063 a char, so there's no worry about sign extension if characters
1064 are signed.</para>
1065 <para>
1066 </para><variablelist role="params">
1067 <varlistentry><term><parameter>c</parameter>&#160;:</term>
1068 <listitem><simpara> an ASCII character.
1069 </simpara></listitem></varlistentry>
1070 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> If <parameter>c</parameter> is a decimal digit (according to
1071 <link linkend="g-ascii-isdigit"><function>g_ascii_isdigit()</function></link>), its numeric value. Otherwise, -1.
1072 </simpara></listitem></varlistentry>
1073 </variablelist></refsect2>
1074 <refsect2 id="g-ascii-xdigit-value" role="function">
1075 <title>g_ascii_xdigit_value ()</title>
1076 <indexterm zone="g-ascii-xdigit-value"><primary sortas="ascii_xdigit_value">g_ascii_xdigit_value</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_ascii_xdigit_value                (<link linkend="gchar">gchar</link> c);</programlisting>
1077 <para>
1078 Determines the numeric value of a character as a hexidecimal
1079 digit. Differs from <link linkend="g-unichar-xdigit-value"><function>g_unichar_xdigit_value()</function></link> because it takes
1080 a char, so there's no worry about sign extension if characters
1081 are signed.</para>
1082 <para>
1083 </para><variablelist role="params">
1084 <varlistentry><term><parameter>c</parameter>&#160;:</term>
1085 <listitem><simpara> an ASCII character.
1086 </simpara></listitem></varlistentry>
1087 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> If <parameter>c</parameter> is a hex digit (according to
1088 <link linkend="g-ascii-isxdigit"><function>g_ascii_isxdigit()</function></link>), its numeric value. Otherwise, -1.
1089 </simpara></listitem></varlistentry>
1090 </variablelist></refsect2>
1091 <refsect2 id="g-ascii-strcasecmp" role="function">
1092 <title>g_ascii_strcasecmp ()</title>
1093 <indexterm zone="g-ascii-strcasecmp"><primary sortas="ascii_strcasecmp">g_ascii_strcasecmp</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_ascii_strcasecmp                  (const <link linkend="gchar">gchar</link> *s1,
1094                                                          const <link linkend="gchar">gchar</link> *s2);</programlisting>
1095 <para>
1096 Compare two strings, ignoring the case of ASCII characters.
1097 </para>
1098 <para>
1099 Unlike the BSD <link linkend="strcasecmp"><function>strcasecmp()</function></link> function, this only recognizes standard
1100 ASCII letters and ignores the locale, treating all non-ASCII
1101 bytes as if they are not letters.
1102 </para>
1103 <para>
1104 This function should be used only on strings that are known to be
1105 in encodings where the bytes corresponding to ASCII letters always
1106 represent themselves. This includes UTF-8 and the ISO-8859-*
1107 charsets, but not for instance double-byte encodings like the
1108 Windows Codepage 932, where the trailing bytes of double-byte
1109 characters include all ASCII letters. If you compare two CP932
1110 strings using this function, you will get false matches.</para>
1111 <para>
1112 </para><variablelist role="params">
1113 <varlistentry><term><parameter>s1</parameter>&#160;:</term>
1114 <listitem><simpara> string to compare with <parameter>s2</parameter>.
1115 </simpara></listitem></varlistentry>
1116 <varlistentry><term><parameter>s2</parameter>&#160;:</term>
1117 <listitem><simpara> string to compare with <parameter>s1</parameter>.
1118 </simpara></listitem></varlistentry>
1119 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> 0 if the strings match, a negative value if <parameter>s1</parameter> &lt; <parameter>s2</parameter>, 
1120   or a positive value if <parameter>s1</parameter> &gt; <parameter>s2</parameter>.
1121 </simpara></listitem></varlistentry>
1122 </variablelist></refsect2>
1123 <refsect2 id="g-ascii-strncasecmp" role="function">
1124 <title>g_ascii_strncasecmp ()</title>
1125 <indexterm zone="g-ascii-strncasecmp"><primary sortas="ascii_strncasecmp">g_ascii_strncasecmp</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_ascii_strncasecmp                 (const <link linkend="gchar">gchar</link> *s1,
1126                                                          const <link linkend="gchar">gchar</link> *s2,
1127                                                          <link linkend="gsize">gsize</link> n);</programlisting>
1128 <para>
1129 Compare <parameter>s1</parameter> and <parameter>s2</parameter>, ignoring the case of ASCII characters and any
1130 characters after the first <parameter>n</parameter> in each string.
1131 </para>
1132 <para>
1133 Unlike the BSD <link linkend="strcasecmp"><function>strcasecmp()</function></link> function, this only recognizes standard
1134 ASCII letters and ignores the locale, treating all non-ASCII
1135 characters as if they are not letters.
1136 </para>
1137 <para>
1138 The same warning as in <link linkend="g-ascii-strcasecmp"><function>g_ascii_strcasecmp()</function></link> applies: Use this
1139 function only on strings known to be in encodings where bytes
1140 corresponding to ASCII letters always represent themselves.</para>
1141 <para>
1142 </para><variablelist role="params">
1143 <varlistentry><term><parameter>s1</parameter>&#160;:</term>
1144 <listitem><simpara> string to compare with <parameter>s2</parameter>.
1145 </simpara></listitem></varlistentry>
1146 <varlistentry><term><parameter>s2</parameter>&#160;:</term>
1147 <listitem><simpara> string to compare with <parameter>s1</parameter>.
1148 </simpara></listitem></varlistentry>
1149 <varlistentry><term><parameter>n</parameter>&#160;:</term>
1150 <listitem><simpara>  number of characters to compare.
1151 </simpara></listitem></varlistentry>
1152 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> 0 if the strings match, a negative value if <parameter>s1</parameter> &lt; <parameter>s2</parameter>, 
1153   or a positive value if <parameter>s1</parameter> &gt; <parameter>s2</parameter>.
1154 </simpara></listitem></varlistentry>
1155 </variablelist></refsect2>
1156 <refsect2 id="g-ascii-strup" role="function">
1157 <title>g_ascii_strup ()</title>
1158 <indexterm zone="g-ascii-strup"><primary sortas="ascii_strup">g_ascii_strup</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_ascii_strup                       (const <link linkend="gchar">gchar</link> *str,
1159                                                          <link linkend="gssize">gssize</link> len);</programlisting>
1160 <para>
1161 Converts all lower case ASCII letters to upper case ASCII letters.</para>
1162 <para>
1163 </para><variablelist role="params">
1164 <varlistentry><term><parameter>str</parameter>&#160;:</term>
1165 <listitem><simpara> a string.
1166 </simpara></listitem></varlistentry>
1167 <varlistentry><term><parameter>len</parameter>&#160;:</term>
1168 <listitem><simpara> length of <parameter>str</parameter> in bytes, or -1 if <parameter>str</parameter> is nul-terminated.
1169 </simpara></listitem></varlistentry>
1170 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly allocated string, with all the lower case
1171               characters in <parameter>str</parameter> converted to upper case, with
1172               semantics that exactly match <link linkend="g-ascii-toupper"><function>g_ascii_toupper()</function></link>. (Note
1173               that this is unlike the old <link linkend="g-strup"><function>g_strup()</function></link>, which modified
1174               the string in place.)
1175 </simpara></listitem></varlistentry>
1176 </variablelist></refsect2>
1177 <refsect2 id="g-ascii-strdown" role="function">
1178 <title>g_ascii_strdown ()</title>
1179 <indexterm zone="g-ascii-strdown"><primary sortas="ascii_strdown">g_ascii_strdown</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_ascii_strdown                     (const <link linkend="gchar">gchar</link> *str,
1180                                                          <link linkend="gssize">gssize</link> len);</programlisting>
1181 <para>
1182 Converts all upper case ASCII letters to lower case ASCII letters.</para>
1183 <para>
1184 </para><variablelist role="params">
1185 <varlistentry><term><parameter>str</parameter>&#160;:</term>
1186 <listitem><simpara> a string.
1187 </simpara></listitem></varlistentry>
1188 <varlistentry><term><parameter>len</parameter>&#160;:</term>
1189 <listitem><simpara> length of <parameter>str</parameter> in bytes, or -1 if <parameter>str</parameter> is nul-terminated.
1190 </simpara></listitem></varlistentry>
1191 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string, with all the upper case
1192               characters in <parameter>str</parameter> converted to lower case, with
1193               semantics that exactly match <link linkend="g-ascii-tolower"><function>g_ascii_tolower()</function></link>. (Note
1194               that this is unlike the old <link linkend="g-strdown"><function>g_strdown()</function></link>, which modified
1195               the string in place.)
1196 </simpara></listitem></varlistentry>
1197 </variablelist></refsect2>
1198 <refsect2 id="g-ascii-tolower" role="function">
1199 <title>g_ascii_tolower ()</title>
1200 <indexterm zone="g-ascii-tolower"><primary sortas="ascii_tolower">g_ascii_tolower</primary></indexterm><programlisting><link linkend="gchar">gchar</link>               g_ascii_tolower                     (<link linkend="gchar">gchar</link> c);</programlisting>
1201 <para>
1202 Convert a character to ASCII lower case.
1203 </para>
1204 <para>
1205 Unlike the standard C library <link linkend="tolower"><function>tolower()</function></link> function, this only
1206 recognizes standard ASCII letters and ignores the locale, returning
1207 all non-ASCII characters unchanged, even if they are lower case
1208 letters in a particular character set. Also unlike the standard
1209 library function, this takes and returns a char, not an int, so
1210 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>
1211 before passing a possibly non-ASCII character in.</para>
1212 <para>
1213 </para><variablelist role="params">
1214 <varlistentry><term><parameter>c</parameter>&#160;:</term>
1215 <listitem><simpara> any character.
1216 </simpara></listitem></varlistentry>
1217 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the result of converting <parameter>c</parameter> to lower case.
1218               If <parameter>c</parameter> is not an ASCII upper case letter,
1219               <parameter>c</parameter> is returned unchanged.
1220 </simpara></listitem></varlistentry>
1221 </variablelist></refsect2>
1222 <refsect2 id="g-ascii-toupper" role="function">
1223 <title>g_ascii_toupper ()</title>
1224 <indexterm zone="g-ascii-toupper"><primary sortas="ascii_toupper">g_ascii_toupper</primary></indexterm><programlisting><link linkend="gchar">gchar</link>               g_ascii_toupper                     (<link linkend="gchar">gchar</link> c);</programlisting>
1225 <para>
1226 Convert a character to ASCII upper case.
1227 </para>
1228 <para>
1229 Unlike the standard C library <link linkend="toupper"><function>toupper()</function></link> function, this only
1230 recognizes standard ASCII letters and ignores the locale, returning
1231 all non-ASCII characters unchanged, even if they are upper case
1232 letters in a particular character set. Also unlike the standard
1233 library function, this takes and returns a char, not an int, so
1234 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>
1235 before passing a possibly non-ASCII character in.</para>
1236 <para>
1237 </para><variablelist role="params">
1238 <varlistentry><term><parameter>c</parameter>&#160;:</term>
1239 <listitem><simpara> any character.
1240 </simpara></listitem></varlistentry>
1241 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the result of converting <parameter>c</parameter> to upper case.
1242               If <parameter>c</parameter> is not an ASCII lower case letter,
1243               <parameter>c</parameter> is returned unchanged.
1244 </simpara></listitem></varlistentry>
1245 </variablelist></refsect2>
1246 <refsect2 id="g-string-ascii-up" role="function">
1247 <title>g_string_ascii_up ()</title>
1248 <indexterm zone="g-string-ascii-up"><primary sortas="string_ascii_up">g_string_ascii_up</primary></indexterm><programlisting><link linkend="GString">GString</link>*            g_string_ascii_up                   (<link linkend="GString">GString</link> *string);</programlisting>
1249 <para>
1250 Converts all lower case ASCII letters to upper case ASCII letters.</para>
1251 <para>
1252 </para><variablelist role="params">
1253 <varlistentry><term><parameter>string</parameter>&#160;:</term>
1254 <listitem><simpara> a GString
1255 </simpara></listitem></varlistentry>
1256 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> passed-in <parameter>string</parameter> pointer, with all the lower case
1257               characters converted to upper case in place, with
1258               semantics that exactly match <link linkend="g-ascii-toupper"><function>g_ascii_toupper()</function></link>.
1259 </simpara></listitem></varlistentry>
1260 </variablelist></refsect2>
1261 <refsect2 id="g-string-ascii-down" role="function">
1262 <title>g_string_ascii_down ()</title>
1263 <indexterm zone="g-string-ascii-down"><primary sortas="string_ascii_down">g_string_ascii_down</primary></indexterm><programlisting><link linkend="GString">GString</link>*            g_string_ascii_down                 (<link linkend="GString">GString</link> *string);</programlisting>
1264 <para>
1265 Converts all upper case ASCII letters to lower case ASCII letters.</para>
1266 <para>
1267 </para><variablelist role="params">
1268 <varlistentry><term><parameter>string</parameter>&#160;:</term>
1269 <listitem><simpara> a GString
1270 </simpara></listitem></varlistentry>
1271 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> passed-in <parameter>string</parameter> pointer, with all the upper case
1272               characters converted to lower case in place, with
1273               semantics that exactly match <link linkend="g-ascii-tolower"><function>g_ascii_tolower()</function></link>.
1274 </simpara></listitem></varlistentry>
1275 </variablelist></refsect2>
1276 <refsect2 id="g-strup" role="function" condition="deprecated">
1277 <title>g_strup ()</title>
1278 <indexterm zone="g-strup" role="deprecated"><primary sortas="strup">g_strup</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strup                             (<link linkend="gchar">gchar</link> *string);</programlisting>
1279 <warning><para><literal>g_strup</literal> has been deprecated since version 2.2 and should not be used in newly-written code. This function is totally broken for the reasons discussed 
1280 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>
1281 <para>
1282 Converts a string to upper case.</para>
1283 <para>
1284 </para><variablelist role="params">
1285 <varlistentry><term><parameter>string</parameter>&#160;:</term>
1286 <listitem><simpara> the string to convert.
1287 </simpara></listitem></varlistentry>
1288 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the string
1289
1290 </simpara></listitem></varlistentry>
1291 </variablelist></refsect2>
1292 <refsect2 id="g-strdown" role="function" condition="deprecated">
1293 <title>g_strdown ()</title>
1294 <indexterm zone="g-strdown" role="deprecated"><primary sortas="strdown">g_strdown</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strdown                           (<link linkend="gchar">gchar</link> *string);</programlisting>
1295 <warning><para><literal>g_strdown</literal> has been deprecated since version 2.2 and should not be used in newly-written code. This function is totally broken for the reasons discussed 
1296 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> 
1297 instead.</para></warning>
1298 <para>
1299 Converts a string to lower case.</para>
1300 <para>
1301 </para><variablelist role="params">
1302 <varlistentry><term><parameter>string</parameter>&#160;:</term>
1303 <listitem><simpara> the string to convert.
1304 </simpara></listitem></varlistentry>
1305 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the string 
1306
1307 </simpara></listitem></varlistentry>
1308 </variablelist></refsect2>
1309 <refsect2 id="g-strcasecmp" role="function" condition="deprecated">
1310 <title>g_strcasecmp ()</title>
1311 <indexterm zone="g-strcasecmp" role="deprecated"><primary sortas="strcasecmp">g_strcasecmp</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_strcasecmp                        (const <link linkend="gchar">gchar</link> *s1,
1312                                                          const <link linkend="gchar">gchar</link> *s2);</programlisting>
1313 <warning><para><literal>g_strcasecmp</literal> has been deprecated since version 2.2 and should not be used in newly-written code. See <link linkend="g-strncasecmp"><function>g_strncasecmp()</function></link> for a discussion of why this function 
1314   is deprecated and how to replace it.</para></warning>
1315 <para>
1316 A case-insensitive string comparison, corresponding to the standard
1317 <link linkend="strcasecmp"><function>strcasecmp()</function></link> function on platforms which support it.</para>
1318 <para>
1319 </para><variablelist role="params">
1320 <varlistentry><term><parameter>s1</parameter>&#160;:</term>
1321 <listitem><simpara> a string.
1322 </simpara></listitem></varlistentry>
1323 <varlistentry><term><parameter>s2</parameter>&#160;:</term>
1324 <listitem><simpara> a string to compare with <parameter>s1</parameter>.
1325 </simpara></listitem></varlistentry>
1326 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> 0 if the strings match, a negative value if <parameter>s1</parameter> &lt; <parameter>s2</parameter>, 
1327   or a positive value if <parameter>s1</parameter> &gt; <parameter>s2</parameter>.
1328
1329 </simpara></listitem></varlistentry>
1330 </variablelist></refsect2>
1331 <refsect2 id="g-strncasecmp" role="function" condition="deprecated">
1332 <title>g_strncasecmp ()</title>
1333 <indexterm zone="g-strncasecmp" role="deprecated"><primary sortas="strncasecmp">g_strncasecmp</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_strncasecmp                       (const <link linkend="gchar">gchar</link> *s1,
1334                                                          const <link linkend="gchar">gchar</link> *s2,
1335                                                          <link linkend="guint">guint</link> n);</programlisting>
1336 <warning><para><literal>g_strncasecmp</literal> has been deprecated since version 2.2 and should not be used in newly-written code. The problem with <link linkend="g-strncasecmp"><function>g_strncasecmp()</function></link> is that it does the 
1337 comparison by calling <link linkend="toupper"><function>toupper()</function></link>/<link linkend="tolower"><function>tolower()</function></link>. These functions are
1338 locale-specific and operate on single bytes. However, it is impossible
1339 to handle things correctly from an I18N standpoint by operating on
1340 bytes, since characters may be multibyte. Thus <link linkend="g-strncasecmp"><function>g_strncasecmp()</function></link> is
1341 broken if your string is guaranteed to be ASCII, since it's
1342 locale-sensitive, and it's broken if your string is localized, since
1343 it doesn't work on many encodings at all, including UTF-8, EUC-JP,
1344 etc.
1345 </para>
1346 <para>
1347 There are therefore two replacement functions: <link linkend="g-ascii-strncasecmp"><function>g_ascii_strncasecmp()</function></link>,
1348 which only works on ASCII and is not locale-sensitive, and
1349 <link linkend="g-utf8-casefold"><function>g_utf8_casefold()</function></link>, which is good for case-insensitive sorting of UTF-8.</para></warning>
1350 <para>
1351 A case-insensitive string comparison, corresponding to the standard
1352 <link linkend="strncasecmp"><function>strncasecmp()</function></link> function on platforms which support it.
1353 It is similar to <link linkend="g-strcasecmp"><function>g_strcasecmp()</function></link> except it only compares the first <parameter>n</parameter> 
1354 characters of the strings.</para>
1355 <para>
1356 </para><variablelist role="params">
1357 <varlistentry><term><parameter>s1</parameter>&#160;:</term>
1358 <listitem><simpara> a string.
1359 </simpara></listitem></varlistentry>
1360 <varlistentry><term><parameter>s2</parameter>&#160;:</term>
1361 <listitem><simpara> a string to compare with <parameter>s1</parameter>.
1362 </simpara></listitem></varlistentry>
1363 <varlistentry><term><parameter>n</parameter>&#160;:</term>
1364 <listitem><simpara> the maximum number of characters to compare.
1365 </simpara></listitem></varlistentry>
1366 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> 0 if the strings match, a negative value if <parameter>s1</parameter> &lt; <parameter>s2</parameter>, 
1367   or a positive value if <parameter>s1</parameter> &gt; <parameter>s2</parameter>.
1368
1369 </simpara></listitem></varlistentry>
1370 </variablelist></refsect2>
1371 <refsect2 id="g-strreverse" role="function">
1372 <title>g_strreverse ()</title>
1373 <indexterm zone="g-strreverse"><primary sortas="strreverse">g_strreverse</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strreverse                        (<link linkend="gchar">gchar</link> *string);</programlisting>
1374 <para>
1375 Reverses all of the bytes in a string. For example, 
1376 <literal>g_strreverse ("abcdef")</literal> will result 
1377 in "fedcba".
1378 </para>
1379 <para>
1380 Note that <link linkend="g-strreverse"><function>g_strreverse()</function></link> doesn't work on UTF-8 strings 
1381 containing multibyte characters. For that purpose, use 
1382 <link linkend="g-utf8-strreverse"><function>g_utf8_strreverse()</function></link>.</para>
1383 <para>
1384 </para><variablelist role="params">
1385 <varlistentry><term><parameter>string</parameter>&#160;:</term>
1386 <listitem><simpara> the string to reverse 
1387 </simpara></listitem></varlistentry>
1388 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the same pointer passed in as <parameter>string</parameter>
1389 </simpara></listitem></varlistentry>
1390 </variablelist></refsect2>
1391 <refsect2 id="g-ascii-strtoll" role="function" condition="since:2.12">
1392 <title>g_ascii_strtoll ()</title>
1393 <indexterm zone="g-ascii-strtoll" role="2.12"><primary sortas="ascii_strtoll">g_ascii_strtoll</primary></indexterm><programlisting><link linkend="gint64">gint64</link>              g_ascii_strtoll                     (const <link linkend="gchar">gchar</link> *nptr,
1394                                                          <link linkend="gchar">gchar</link> **endptr,
1395                                                          <link linkend="guint">guint</link> base);</programlisting>
1396 <para>
1397 Converts a string to a <link linkend="gint64"><type>gint64</type></link> value.
1398 This function behaves like the standard <link linkend="strtoll"><function>strtoll()</function></link> function
1399 does in the C locale. It does this without actually
1400 changing the current locale, since that would not be
1401 thread-safe.
1402 </para>
1403 <para>
1404 This function is typically used when reading configuration
1405 files or other non-user input that should be locale independent.
1406 To handle input from the user you should normally use the
1407 locale-sensitive system <link linkend="strtoll"><function>strtoll()</function></link> function.
1408 </para>
1409 <para>
1410 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>
1411 is returned, and <link linkend="ERANGE--CAPS"><literal>ERANGE</literal></link> is stored in <link linkend="errno"><literal>errno</literal></link>.  If the base is
1412 outside the valid range, zero is returned, and <link linkend="EINVAL--CAPS"><literal>EINVAL</literal></link> is stored
1413 in <link linkend="errno"><literal>errno</literal></link>.  If the string conversion fails, zero is returned, and
1414 <parameter>endptr</parameter> returns <parameter>nptr</parameter> (if <parameter>endptr</parameter> is non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>).</para>
1415 <para>
1416 </para><variablelist role="params">
1417 <varlistentry><term><parameter>nptr</parameter>&#160;:</term>
1418 <listitem><simpara>    the string to convert to a numeric value.
1419 </simpara></listitem></varlistentry>
1420 <varlistentry><term><parameter>endptr</parameter>&#160;:</term>
1421 <listitem><simpara>  if non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, it returns the character after
1422           the last character used in the conversion.
1423 </simpara></listitem></varlistentry>
1424 <varlistentry><term><parameter>base</parameter>&#160;:</term>
1425 <listitem><simpara>    to be used for the conversion, 2..36 or 0
1426 </simpara></listitem></varlistentry>
1427 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="gint64"><type>gint64</type></link> value or zero on error.
1428
1429 </simpara></listitem></varlistentry>
1430 </variablelist><para role="since">Since 2.12</para></refsect2>
1431 <refsect2 id="g-ascii-strtoull" role="function" condition="since:2.2">
1432 <title>g_ascii_strtoull ()</title>
1433 <indexterm zone="g-ascii-strtoull" role="2.2"><primary sortas="ascii_strtoull">g_ascii_strtoull</primary></indexterm><programlisting><link linkend="guint64">guint64</link>             g_ascii_strtoull                    (const <link linkend="gchar">gchar</link> *nptr,
1434                                                          <link linkend="gchar">gchar</link> **endptr,
1435                                                          <link linkend="guint">guint</link> base);</programlisting>
1436 <para>
1437 Converts a string to a <link linkend="guint64"><type>guint64</type></link> value.
1438 This function behaves like the standard <link linkend="strtoull"><function>strtoull()</function></link> function
1439 does in the C locale. It does this without actually
1440 changing the current locale, since that would not be
1441 thread-safe.
1442 </para>
1443 <para>
1444 This function is typically used when reading configuration
1445 files or other non-user input that should be locale independent.
1446 To handle input from the user you should normally use the
1447 locale-sensitive system <link linkend="strtoull"><function>strtoull()</function></link> function.
1448 </para>
1449 <para>
1450 If the correct value would cause overflow, <link linkend="G-MAXUINT64--CAPS"><literal>G_MAXUINT64</literal></link>
1451 is returned, and <link linkend="ERANGE--CAPS"><literal>ERANGE</literal></link> is stored in <link linkend="errno"><literal>errno</literal></link>.  If the base is
1452 outside the valid range, zero is returned, and <link linkend="EINVAL--CAPS"><literal>EINVAL</literal></link> is stored
1453 in <link linkend="errno"><literal>errno</literal></link>.  If the string conversion fails, zero is returned, and
1454 <parameter>endptr</parameter> returns <parameter>nptr</parameter> (if <parameter>endptr</parameter> is non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>).</para>
1455 <para>
1456 </para><variablelist role="params">
1457 <varlistentry><term><parameter>nptr</parameter>&#160;:</term>
1458 <listitem><simpara>    the string to convert to a numeric value.
1459 </simpara></listitem></varlistentry>
1460 <varlistentry><term><parameter>endptr</parameter>&#160;:</term>
1461 <listitem><simpara>  if non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, it returns the character after
1462           the last character used in the conversion.
1463 </simpara></listitem></varlistentry>
1464 <varlistentry><term><parameter>base</parameter>&#160;:</term>
1465 <listitem><simpara>    to be used for the conversion, 2..36 or 0
1466 </simpara></listitem></varlistentry>
1467 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="guint64"><type>guint64</type></link> value or zero on error.
1468
1469 </simpara></listitem></varlistentry>
1470 </variablelist><para role="since">Since 2.2</para></refsect2>
1471 <refsect2 id="G-ASCII-DTOSTR-BUF-SIZE--CAPS" role="macro">
1472 <title>G_ASCII_DTOSTR_BUF_SIZE</title>
1473 <indexterm zone="G-ASCII-DTOSTR-BUF-SIZE--CAPS"><primary sortas="ASCII_DTOSTR_BUF_SIZE">G_ASCII_DTOSTR_BUF_SIZE</primary></indexterm><programlisting>#define G_ASCII_DTOSTR_BUF_SIZE (29 + 10)
1474 </programlisting>
1475 <para>
1476 A good size for a buffer to be passed into <link linkend="g-ascii-dtostr"><function>g_ascii_dtostr()</function></link>.
1477 It is guaranteed to be enough for all output of that function on systems with
1478  64bit IEEE-compatible doubles.
1479 </para>
1480 <para>
1481 The typical usage would be something like:
1482 <informalexample><programlisting>
1483   char buf[G_ASCII_DTOSTR_BUF_SIZE];
1484   fprintf (out, "value=&percnt;s\n", g_ascii_dtostr (buf, sizeof (buf), value));
1485 </programlisting></informalexample>
1486 </para></refsect2>
1487 <refsect2 id="g-ascii-strtod" role="function">
1488 <title>g_ascii_strtod ()</title>
1489 <indexterm zone="g-ascii-strtod"><primary sortas="ascii_strtod">g_ascii_strtod</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link>             g_ascii_strtod                      (const <link linkend="gchar">gchar</link> *nptr,
1490                                                          <link linkend="gchar">gchar</link> **endptr);</programlisting>
1491 <para>
1492 Converts a string to a <link linkend="gdouble"><type>gdouble</type></link> value.
1493 </para>
1494 <para>
1495 This function behaves like the standard <link linkend="strtod"><function>strtod()</function></link> function
1496 does in the C locale. It does this without actually changing 
1497 the current locale, since that would not be thread-safe. 
1498 A limitation of the implementation is that this function
1499 will still accept localized versions of infinities and NANs. 
1500 </para>
1501 <para>
1502 This function is typically used when reading configuration
1503 files or other non-user input that should be locale independent.
1504 To handle input from the user you should normally use the
1505 locale-sensitive system <link linkend="strtod"><function>strtod()</function></link> function.
1506 </para>
1507 <para>
1508 To convert from a <link linkend="gdouble"><type>gdouble</type></link> to a string in a locale-insensitive
1509 way, use <link linkend="g-ascii-dtostr"><function>g_ascii_dtostr()</function></link>.
1510 </para>
1511 <para>
1512 If the correct value would cause overflow, plus or minus <link linkend="HUGE-VAL--CAPS"><literal>HUGE_VAL</literal></link>
1513 is returned (according to the sign of the value), and <link linkend="ERANGE--CAPS"><literal>ERANGE</literal></link> is
1514 stored in <link linkend="errno"><literal>errno</literal></link>. If the correct value would cause underflow,
1515 zero is returned and <link linkend="ERANGE--CAPS"><literal>ERANGE</literal></link> is stored in <link linkend="errno"><literal>errno</literal></link>.
1516 </para>
1517 <para>
1518 This function resets <link linkend="errno"><literal>errno</literal></link> before calling <link linkend="strtod"><function>strtod()</function></link> so that
1519 you can reliably detect overflow and underflow.</para>
1520 <para>
1521 </para><variablelist role="params">
1522 <varlistentry><term><parameter>nptr</parameter>&#160;:</term>
1523 <listitem><simpara>    the string to convert to a numeric value.
1524 </simpara></listitem></varlistentry>
1525 <varlistentry><term><parameter>endptr</parameter>&#160;:</term>
1526 <listitem><simpara>  if non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, it returns the character after
1527           the last character used in the conversion.
1528 </simpara></listitem></varlistentry>
1529 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="gdouble"><type>gdouble</type></link> value.
1530 </simpara></listitem></varlistentry>
1531 </variablelist></refsect2>
1532 <refsect2 id="g-ascii-dtostr" role="function">
1533 <title>g_ascii_dtostr ()</title>
1534 <indexterm zone="g-ascii-dtostr"><primary sortas="ascii_dtostr">g_ascii_dtostr</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             g_ascii_dtostr                      (<link linkend="gchar">gchar</link> *buffer,
1535                                                          <link linkend="gint">gint</link> buf_len,
1536                                                          <link linkend="gdouble">gdouble</link> d);</programlisting>
1537 <para>
1538 Converts a <link linkend="gdouble"><type>gdouble</type></link> to a string, using the '.' as
1539 decimal point. 
1540 </para>
1541 <para>
1542 This functions generates enough precision that converting
1543 the string back using <link linkend="g-ascii-strtod"><function>g_ascii_strtod()</function></link> gives the same machine-number
1544 (on machines with IEEE compatible 64bit doubles). It is
1545 guaranteed that the size of the resulting string will never
1546 be larger than <parameter>G_ASCII_DTOSTR_BUF_SIZE</parameter> bytes.</para>
1547 <para>
1548 </para><variablelist role="params">
1549 <varlistentry><term><parameter>buffer</parameter>&#160;:</term>
1550 <listitem><simpara> A buffer to place the resulting string in
1551 </simpara></listitem></varlistentry>
1552 <varlistentry><term><parameter>buf_len</parameter>&#160;:</term>
1553 <listitem><simpara> The length of the buffer.
1554 </simpara></listitem></varlistentry>
1555 <varlistentry><term><parameter>d</parameter>&#160;:</term>
1556 <listitem><simpara> The <link linkend="gdouble"><type>gdouble</type></link> to convert
1557 </simpara></listitem></varlistentry>
1558 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The pointer to the buffer with the converted string.
1559 </simpara></listitem></varlistentry>
1560 </variablelist></refsect2>
1561 <refsect2 id="g-ascii-formatd" role="function">
1562 <title>g_ascii_formatd ()</title>
1563 <indexterm zone="g-ascii-formatd"><primary sortas="ascii_formatd">g_ascii_formatd</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             g_ascii_formatd                     (<link linkend="gchar">gchar</link> *buffer,
1564                                                          <link linkend="gint">gint</link> buf_len,
1565                                                          const <link linkend="gchar">gchar</link> *format,
1566                                                          <link linkend="gdouble">gdouble</link> d);</programlisting>
1567 <para>
1568 Converts a <link linkend="gdouble"><type>gdouble</type></link> to a string, using the '.' as
1569 decimal point. To format the number you pass in
1570 a <link linkend="printf"><function>printf()</function></link>-style format string. Allowed conversion
1571 specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'. 
1572 </para>
1573 <para>
1574 If you just want to want to serialize the value into a
1575 string, use <link linkend="g-ascii-dtostr"><function>g_ascii_dtostr()</function></link>.</para>
1576 <para>
1577 </para><variablelist role="params">
1578 <varlistentry><term><parameter>buffer</parameter>&#160;:</term>
1579 <listitem><simpara> A buffer to place the resulting string in
1580 </simpara></listitem></varlistentry>
1581 <varlistentry><term><parameter>buf_len</parameter>&#160;:</term>
1582 <listitem><simpara> The length of the buffer.
1583 </simpara></listitem></varlistentry>
1584 <varlistentry><term><parameter>format</parameter>&#160;:</term>
1585 <listitem><simpara> The <link linkend="printf"><function>printf()</function></link>-style format to use for the
1586          code to use for converting. 
1587 </simpara></listitem></varlistentry>
1588 <varlistentry><term><parameter>d</parameter>&#160;:</term>
1589 <listitem><simpara> The <link linkend="gdouble"><type>gdouble</type></link> to convert
1590 </simpara></listitem></varlistentry>
1591 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The pointer to the buffer with the converted string.
1592 </simpara></listitem></varlistentry>
1593 </variablelist></refsect2>
1594 <refsect2 id="g-strtod" role="function">
1595 <title>g_strtod ()</title>
1596 <indexterm zone="g-strtod"><primary sortas="strtod">g_strtod</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link>             g_strtod                            (const <link linkend="gchar">gchar</link> *nptr,
1597                                                          <link linkend="gchar">gchar</link> **endptr);</programlisting>
1598 <para>
1599 Converts a string to a <link linkend="gdouble"><type>gdouble</type></link> value.
1600 It calls the standard <link linkend="strtod"><function>strtod()</function></link> function to handle the conversion, but
1601 if the string is not completely converted it attempts the conversion
1602 again with <link linkend="g-ascii-strtod"><function>g_ascii_strtod()</function></link>, and returns the best match.
1603 </para>
1604 <para>
1605 This function should seldomly be used. The normal situation when reading
1606 numbers not for human consumption is to use <link linkend="g-ascii-strtod"><function>g_ascii_strtod()</function></link>. Only when
1607 you know that you must expect both locale formatted and C formatted numbers
1608 should you use this. Make sure that you don't pass strings such as comma
1609 separated lists of values, since the commas may be interpreted as a decimal
1610 point in some locales, causing unexpected results.</para>
1611 <para>
1612 </para><variablelist role="params">
1613 <varlistentry><term><parameter>nptr</parameter>&#160;:</term>
1614 <listitem><simpara>    the string to convert to a numeric value.
1615 </simpara></listitem></varlistentry>
1616 <varlistentry><term><parameter>endptr</parameter>&#160;:</term>
1617 <listitem><simpara>  if non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, it returns the character after
1618           the last character used in the conversion.
1619 </simpara></listitem></varlistentry>
1620 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="gdouble"><type>gdouble</type></link> value.
1621 </simpara></listitem></varlistentry>
1622 </variablelist></refsect2>
1623 <refsect2 id="g-strchug" role="function">
1624 <title>g_strchug ()</title>
1625 <indexterm zone="g-strchug"><primary sortas="strchug">g_strchug</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strchug                           (<link linkend="gchar">gchar</link> *string);</programlisting>
1626 <para>
1627 Removes leading whitespace from a string, by moving the rest of the
1628 characters forward.
1629 </para>
1630 <para>
1631 This function doesn't allocate or reallocate any memory; it modifies <parameter>string</parameter>
1632 in place. The pointer to <parameter>string</parameter> is returned to allow the nesting of functions.
1633 </para>
1634 <para>
1635 Also see <link linkend="g-strchomp"><function>g_strchomp()</function></link> and <link linkend="g-strstrip"><function>g_strstrip()</function></link>.
1636 </para><variablelist role="params">
1637 <varlistentry><term><parameter>string</parameter>&#160;:</term>
1638 <listitem><simpara>a string to remove the leading whitespace from.
1639 </simpara></listitem></varlistentry>
1640 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>@string.
1641 </simpara></listitem></varlistentry>
1642 </variablelist></refsect2>
1643 <refsect2 id="g-strchomp" role="function">
1644 <title>g_strchomp ()</title>
1645 <indexterm zone="g-strchomp"><primary sortas="strchomp">g_strchomp</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strchomp                          (<link linkend="gchar">gchar</link> *string);</programlisting>
1646 <para>
1647 Removes trailing whitespace from a string.
1648 </para>
1649 <para>
1650 This function doesn't allocate or reallocate any memory; it modifies <parameter>string</parameter> in
1651 place. The pointer to <parameter>string</parameter> is returned to allow the nesting of functions.
1652 </para>
1653 <para>
1654 Also see <link linkend="g-strchug"><function>g_strchug()</function></link> and <link linkend="g-strstrip"><function>g_strstrip()</function></link>.
1655 </para><variablelist role="params">
1656 <varlistentry><term><parameter>string</parameter>&#160;:</term>
1657 <listitem><simpara>a string to remove the trailing whitespace from.
1658 </simpara></listitem></varlistentry>
1659 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>@string.
1660 </simpara></listitem></varlistentry>
1661 </variablelist></refsect2>
1662 <refsect2 id="g-strstrip" role="macro">
1663 <title>g_strstrip()</title>
1664 <indexterm zone="g-strstrip"><primary sortas="strstrip">g_strstrip</primary></indexterm><programlisting>#define             g_strstrip( string )</programlisting>
1665 <para>
1666 Removes leading and trailing whitespace from a string. See <link linkend="g-strchomp"><function>g_strchomp()</function></link> and
1667 <link linkend="g-strchug"><function>g_strchug()</function></link>.
1668 </para><variablelist role="params">
1669 <varlistentry><term><parameter>string</parameter>&#160;:</term>
1670 <listitem><simpara>a string to remove the leading and trailing whitespace from.
1671 </simpara></listitem></varlistentry>
1672 </variablelist></refsect2>
1673 <refsect2 id="g-strdelimit" role="function">
1674 <title>g_strdelimit ()</title>
1675 <indexterm zone="g-strdelimit"><primary sortas="strdelimit">g_strdelimit</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strdelimit                        (<link linkend="gchar">gchar</link> *string,
1676                                                          const <link linkend="gchar">gchar</link> *delimiters,
1677                                                          <link linkend="gchar">gchar</link> new_delimiter);</programlisting>
1678 <para>
1679 Converts any delimiter characters in <parameter>string</parameter> to <parameter>new_delimiter</parameter>.
1680 Any characters in <parameter>string</parameter> which are found in <parameter>delimiters</parameter> are changed
1681 to the <parameter>new_delimiter</parameter> character. Modifies <parameter>string</parameter> in place, and returns
1682 <parameter>string</parameter> itself, not a copy. The return value is to allow nesting such as
1683 <literal>g_ascii_strup (g_strdelimit (str, "abc", '?'))</literal>.
1684 </para><variablelist role="params">
1685 <varlistentry><term><parameter>string</parameter>&#160;:</term>
1686 <listitem><simpara>the string to convert.
1687 </simpara></listitem></varlistentry>
1688 <varlistentry><term><parameter>delimiters</parameter>&#160;:</term>
1689 <listitem><simpara>a string containing the current delimiters, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to use the
1690 standard delimiters defined in <link linkend="G-STR-DELIMITERS--CAPS"><type>G_STR_DELIMITERS</type></link>.
1691 </simpara></listitem></varlistentry>
1692 <varlistentry><term><parameter>new_delimiter</parameter>&#160;:</term>
1693 <listitem><simpara>the new delimiter character.
1694 </simpara></listitem></varlistentry>
1695 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>@string.
1696 </simpara></listitem></varlistentry>
1697 </variablelist></refsect2>
1698 <refsect2 id="G-STR-DELIMITERS--CAPS" role="macro">
1699 <title>G_STR_DELIMITERS</title>
1700 <indexterm zone="G-STR-DELIMITERS--CAPS"><primary sortas="STR_DELIMITERS">G_STR_DELIMITERS</primary></indexterm><programlisting>#define  G_STR_DELIMITERS       "_-|&gt; &lt;."
1701 </programlisting>
1702 <para>
1703 The standard delimiters, used in <link linkend="g-strdelimit"><function>g_strdelimit()</function></link>.
1704 </para></refsect2>
1705 <refsect2 id="g-strescape" role="function">
1706 <title>g_strescape ()</title>
1707 <indexterm zone="g-strescape"><primary sortas="strescape">g_strescape</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strescape                         (const <link linkend="gchar">gchar</link> *source,
1708                                                          const <link linkend="gchar">gchar</link> *exceptions);</programlisting>
1709 <para>
1710 Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\' and
1711 '&quot;' in the string <parameter>source</parameter> by inserting a '\' before
1712 them. Additionally all characters in the range 0x01-0x1F (everything
1713 below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
1714 replaced with a '\' followed by their octal representation. Characters
1715 supplied in <parameter>exceptions</parameter> are not escaped.
1716 </para>
1717 <para>
1718 <link linkend="g-strcompress"><function>g_strcompress()</function></link> does the reverse conversion.
1719 </para><variablelist role="params">
1720 <varlistentry><term><parameter>source</parameter>&#160;:</term>
1721 <listitem><simpara>a string to escape.
1722 </simpara></listitem></varlistentry>
1723 <varlistentry><term><parameter>exceptions</parameter>&#160;:</term>
1724 <listitem><simpara>a string of characters not to escape in <parameter>source</parameter>.
1725 </simpara></listitem></varlistentry>
1726 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated copy of <parameter>source</parameter> with certain
1727 characters escaped. See above.
1728 </simpara></listitem></varlistentry>
1729 </variablelist></refsect2>
1730 <refsect2 id="g-strcompress" role="function">
1731 <title>g_strcompress ()</title>
1732 <indexterm zone="g-strcompress"><primary sortas="strcompress">g_strcompress</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strcompress                       (const <link linkend="gchar">gchar</link> *source);</programlisting>
1733 <para>
1734 Replaces all escaped characters with their one byte equivalent. It
1735 does the reverse conversion of <link linkend="g-strescape"><function>g_strescape()</function></link>.
1736 </para><variablelist role="params">
1737 <varlistentry><term><parameter>source</parameter>&#160;:</term>
1738 <listitem><simpara>a string to compress.
1739 </simpara></listitem></varlistentry>
1740 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a newly-allocated copy of <parameter>source</parameter> with all escaped 
1741 character compressed.
1742 </simpara></listitem></varlistentry>
1743 </variablelist></refsect2>
1744 <refsect2 id="g-strcanon" role="function">
1745 <title>g_strcanon ()</title>
1746 <indexterm zone="g-strcanon"><primary sortas="strcanon">g_strcanon</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strcanon                          (<link linkend="gchar">gchar</link> *string,
1747                                                          const <link linkend="gchar">gchar</link> *valid_chars,
1748                                                          <link linkend="gchar">gchar</link> substitutor);</programlisting>
1749 <para>
1750 For each character in <parameter>string</parameter>, if the character is not in <parameter>valid_chars</parameter>,
1751 replaces the character with <parameter>substitutor</parameter>. Modifies <parameter>string</parameter> in place,
1752 and return <parameter>string</parameter> itself, not a copy. The return value is to allow
1753 nesting such as <literal>g_ascii_strup (g_strcanon (str, "abc", '?'))</literal>.
1754 </para><variablelist role="params">
1755 <varlistentry><term><parameter>string</parameter>&#160;:</term>
1756 <listitem><simpara>a nul-terminated array of bytes.
1757 </simpara></listitem></varlistentry>
1758 <varlistentry><term><parameter>valid_chars</parameter>&#160;:</term>
1759 <listitem><simpara>bytes permitted in <parameter>string</parameter>.
1760 </simpara></listitem></varlistentry>
1761 <varlistentry><term><parameter>substitutor</parameter>&#160;:</term>
1762 <listitem><simpara>replacement character for disallowed bytes.
1763 </simpara></listitem></varlistentry>
1764 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>@string.
1765 </simpara></listitem></varlistentry>
1766 </variablelist></refsect2>
1767 <refsect2 id="g-strsplit" role="function">
1768 <title>g_strsplit ()</title>
1769 <indexterm zone="g-strsplit"><primary sortas="strsplit">g_strsplit</primary></indexterm><programlisting><link linkend="gchar">gchar</link>**             g_strsplit                          (const <link linkend="gchar">gchar</link> *string,
1770                                                          const <link linkend="gchar">gchar</link> *delimiter,
1771                                                          <link linkend="gint">gint</link> max_tokens);</programlisting>
1772 <para>
1773 Splits a string into a maximum of <parameter>max_tokens</parameter> pieces, using the given
1774 <parameter>delimiter</parameter>. If <parameter>max_tokens</parameter> is reached, the remainder of <parameter>string</parameter> is appended
1775 to the last token. 
1776 </para>
1777 <para>
1778 As a special case, the result of splitting the empty string "" is an empty
1779 vector, not a vector containing a single string. The reason for this
1780 special case is that being able to represent a empty vector is typically
1781 more useful than consistent handling of empty elements. If you do need
1782 to represent empty elements, you'll need to check for the empty string
1783 before calling <link linkend="g-strsplit"><function>g_strsplit()</function></link>.</para>
1784 <para>
1785 </para><variablelist role="params">
1786 <varlistentry><term><parameter>string</parameter>&#160;:</term>
1787 <listitem><simpara> a string to split.
1788 </simpara></listitem></varlistentry>
1789 <varlistentry><term><parameter>delimiter</parameter>&#160;:</term>
1790 <listitem><simpara> a string which specifies the places at which to split the string.
1791     The delimiter is not included in any of the resulting strings, unless
1792     <parameter>max_tokens</parameter> is reached.
1793 </simpara></listitem></varlistentry>
1794 <varlistentry><term><parameter>max_tokens</parameter>&#160;:</term>
1795 <listitem><simpara> the maximum number of pieces to split <parameter>string</parameter> into. If this is
1796              less than 1, the string is split completely.
1797 </simpara></listitem></varlistentry>
1798 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings. Use 
1799    <link linkend="g-strfreev"><function>g_strfreev()</function></link> to free it.
1800 </simpara></listitem></varlistentry>
1801 </variablelist></refsect2>
1802 <refsect2 id="g-strsplit-set" role="function" condition="since:2.4">
1803 <title>g_strsplit_set ()</title>
1804 <indexterm zone="g-strsplit-set" role="2.4"><primary sortas="strsplit_set">g_strsplit_set</primary></indexterm><programlisting><link linkend="gchar">gchar</link> **            g_strsplit_set                      (const <link linkend="gchar">gchar</link> *string,
1805                                                          const <link linkend="gchar">gchar</link> *delimiters,
1806                                                          <link linkend="gint">gint</link> max_tokens);</programlisting>
1807 <para>
1808 Splits <parameter>string</parameter> into a number of tokens not containing any of the characters
1809 in <parameter>delimiter</parameter>. A token is the (possibly empty) longest string that does not
1810 contain any of the characters in <parameter>delimiters</parameter>. If <parameter>max_tokens</parameter> is reached, the
1811 remainder is appended to the last token.
1812 </para>
1813 <para>
1814 For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
1815 <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated vector containing the three strings "abc", "def", 
1816 and "ghi".
1817 </para>
1818 <para>
1819 The result if g_strsplit_set (":def/ghi:", ":/", -1) is a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated
1820 vector containing the four strings "", "def", "ghi", and "".
1821 </para>
1822 <para>
1823 As a special case, the result of splitting the empty string "" is an empty
1824 vector, not a vector containing a single string. The reason for this
1825 special case is that being able to represent a empty vector is typically
1826 more useful than consistent handling of empty elements. If you do need
1827 to represent empty elements, you'll need to check for the empty string
1828 before calling <link linkend="g-strsplit-set"><function>g_strsplit_set()</function></link>.
1829 </para>
1830 <para>
1831 Note that this function works on bytes not characters, so it can't be used 
1832 to delimit UTF-8 strings for anything but ASCII characters.</para>
1833 <para>
1834 </para><variablelist role="params">
1835 <varlistentry><term><parameter>string</parameter>&#160;:</term>
1836 <listitem><simpara> The string to be tokenized
1837 </simpara></listitem></varlistentry>
1838 <varlistentry><term><parameter>delimiters</parameter>&#160;:</term>
1839 <listitem><simpara> A nul-terminated string containing bytes that are used
1840              to split the string.
1841 </simpara></listitem></varlistentry>
1842 <varlistentry><term><parameter>max_tokens</parameter>&#160;:</term>
1843 <listitem><simpara> The maximum number of tokens to split <parameter>string</parameter> into. 
1844              If this is less than 1, the string is split completely
1845 </simpara></listitem></varlistentry>
1846 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings. Use 
1847    <link linkend="g-strfreev"><function>g_strfreev()</function></link> to free it.
1848
1849 </simpara></listitem></varlistentry>
1850 </variablelist><para role="since">Since 2.4</para></refsect2>
1851 <refsect2 id="g-strfreev" role="function">
1852 <title>g_strfreev ()</title>
1853 <indexterm zone="g-strfreev"><primary sortas="strfreev">g_strfreev</primary></indexterm><programlisting><link linkend="void">void</link>                g_strfreev                          (<link linkend="gchar">gchar</link> **str_array);</programlisting>
1854 <para>
1855 Frees a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings, and the array itself.
1856 If called on a <link linkend="NULL--CAPS"><literal>NULL</literal></link> value, <link linkend="g-strfreev"><function>g_strfreev()</function></link> simply returns.</para>
1857 <para>
1858 </para><variablelist role="params">
1859 <varlistentry><term><parameter>str_array</parameter>&#160;:</term>
1860 <listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings to free.
1861 </simpara></listitem></varlistentry>
1862 </variablelist></refsect2>
1863 <refsect2 id="g-strconcat" role="function">
1864 <title>g_strconcat ()</title>
1865 <indexterm zone="g-strconcat"><primary sortas="strconcat">g_strconcat</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strconcat                         (const <link linkend="gchar">gchar</link> *string1,
1866                                                          ...);</programlisting>
1867 <para>
1868 Concatenates all of the given strings into one long string.
1869 The returned string should be freed with <link linkend="g-free"><function>g_free()</function></link> when no longer needed.
1870 </para>
1871 <para>
1872 <warning><para>The variable argument list <emphasis>must</emphasis> end 
1873 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
1874 random memory junk to your string.</para></warning></para>
1875 <para>
1876 </para><variablelist role="params">
1877 <varlistentry><term><parameter>string1</parameter>&#160;:</term>
1878 <listitem><simpara> the first string to add, which must not be <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1879 </simpara></listitem></varlistentry>
1880 <varlistentry><term><parameter>...</parameter>&#160;:</term>
1881 <listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated list of strings to append to the string
1882 </simpara></listitem></varlistentry>
1883 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string containing all the string arguments
1884 </simpara></listitem></varlistentry>
1885 </variablelist></refsect2>
1886 <refsect2 id="g-strjoin" role="function">
1887 <title>g_strjoin ()</title>
1888 <indexterm zone="g-strjoin"><primary sortas="strjoin">g_strjoin</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strjoin                           (const <link linkend="gchar">gchar</link> *separator,
1889                                                          ...);</programlisting>
1890 <para>
1891 Joins a number of strings together to form one long string, with the 
1892 optional <parameter>separator</parameter> inserted between each of them. The returned string
1893 should be freed with <link linkend="g-free"><function>g_free()</function></link>.</para>
1894 <para>
1895 </para><variablelist role="params">
1896 <varlistentry><term><parameter>separator</parameter>&#160;:</term>
1897 <listitem><simpara> a string to insert between each of the strings, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1898 </simpara></listitem></varlistentry>
1899 <varlistentry><term><parameter>...</parameter>&#160;:</term>
1900 <listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated list of strings to join
1901 </simpara></listitem></varlistentry>
1902 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string containing all of the strings joined
1903     together, with <parameter>separator</parameter> between them
1904 </simpara></listitem></varlistentry>
1905 </variablelist></refsect2>
1906 <refsect2 id="g-strjoinv" role="function">
1907 <title>g_strjoinv ()</title>
1908 <indexterm zone="g-strjoinv"><primary sortas="strjoinv">g_strjoinv</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_strjoinv                          (const <link linkend="gchar">gchar</link> *separator,
1909                                                          <link linkend="gchar">gchar</link> **str_array);</programlisting>
1910 <para>
1911 Joins a number of strings together to form one long string, with the 
1912 optional <parameter>separator</parameter> inserted between each of them. The returned string
1913 should be freed with <link linkend="g-free"><function>g_free()</function></link>.</para>
1914 <para>
1915 </para><variablelist role="params">
1916 <varlistentry><term><parameter>separator</parameter>&#160;:</term>
1917 <listitem><simpara> a string to insert between each of the strings, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
1918 </simpara></listitem></varlistentry>
1919 <varlistentry><term><parameter>str_array</parameter>&#160;:</term>
1920 <listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings to join
1921 </simpara></listitem></varlistentry>
1922 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string containing all of the strings joined
1923     together, with <parameter>separator</parameter> between them
1924 </simpara></listitem></varlistentry>
1925 </variablelist></refsect2>
1926 <refsect2 id="g-strv-length" role="function" condition="since:2.6">
1927 <title>g_strv_length ()</title>
1928 <indexterm zone="g-strv-length" role="2.6"><primary sortas="strv_length">g_strv_length</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_strv_length                       (<link linkend="gchar">gchar</link> **str_array);</programlisting>
1929 <para>
1930 Returns the length of the given <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated 
1931 string array <parameter>str_array</parameter>.</para>
1932 <para>
1933 </para><variablelist role="params">
1934 <varlistentry><term><parameter>str_array</parameter>&#160;:</term>
1935 <listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings.
1936 </simpara></listitem></varlistentry>
1937 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> length of <parameter>str_array</parameter>.
1938
1939 </simpara></listitem></varlistentry>
1940 </variablelist><para role="since">Since 2.6</para></refsect2>
1941 <refsect2 id="g-strerror" role="function">
1942 <title>g_strerror ()</title>
1943 <indexterm zone="g-strerror"><primary sortas="strerror">g_strerror</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_strerror                          (<link linkend="gint">gint</link> errnum);</programlisting>
1944 <para>
1945 Returns a string corresponding to the given error code, e.g. 
1946 "no such process". You should use this function in preference to 
1947 <link linkend="strerror"><function>strerror()</function></link>, because it returns a string in UTF-8 encoding, and since 
1948 not all platforms support the <link linkend="strerror"><function>strerror()</function></link> function.</para>
1949 <para>
1950 </para><variablelist role="params">
1951 <varlistentry><term><parameter>errnum</parameter>&#160;:</term>
1952 <listitem><simpara> the system error number. See the standard C <link linkend="errno"><literal>errno</literal></link>
1953     documentation
1954 </simpara></listitem></varlistentry>
1955 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a UTF-8 string describing the error code. If the error code 
1956     is unknown, it returns "unknown error (&lt;code&gt;)". The string 
1957     can only be used until the next call to <link linkend="g-strerror"><function>g_strerror()</function></link>
1958 </simpara></listitem></varlistentry>
1959 </variablelist></refsect2>
1960 <refsect2 id="g-strsignal" role="function">
1961 <title>g_strsignal ()</title>
1962 <indexterm zone="g-strsignal"><primary sortas="strsignal">g_strsignal</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_strsignal                         (<link linkend="gint">gint</link> signum);</programlisting>
1963 <para>
1964 Returns a string describing the given signal, e.g. "Segmentation fault".
1965 You should use this function in preference to <link linkend="strsignal"><function>strsignal()</function></link>, because it 
1966 returns a string in UTF-8 encoding, and since not all platforms support
1967 the <link linkend="strsignal"><function>strsignal()</function></link> function.</para>
1968 <para>
1969 </para><variablelist role="params">
1970 <varlistentry><term><parameter>signum</parameter>&#160;:</term>
1971 <listitem><simpara> the signal number. See the <literal>signal</literal>
1972     documentation
1973 </simpara></listitem></varlistentry>
1974 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a UTF-8 string describing the signal. If the signal is unknown,
1975     it returns "unknown signal (&lt;signum&gt;)". The string can only be 
1976     used until the next call to <link linkend="g-strsignal"><function>g_strsignal()</function></link>
1977 </simpara></listitem></varlistentry>
1978 </variablelist></refsect2>
1979
1980 </refsect1>
1981
1982
1983
1984
1985 </refentry>