docs/reference/glib/html/glib-String-Utility-Functions.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>String Utility Functions</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-utilities.html" title="GLib Utilities">
   9 <link rel="prev" href="glib-utilities.html" title="GLib Utilities">
  10 <link rel="next" href="glib-Character-Set-Conversion.html" title="Character Set Conversion">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="glib-utilities.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="glib-utilities.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GLib Reference Manual</th>
  21 <td><a accesskey="n" href="glib-Character-Set-Conversion.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#glib-String-Utility-Functions.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#glib-String-Utility-Functions.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="glib-String-Utility-Functions"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="glib-String-Utility-Functions.top_of_page"></a>String Utility Functions</span></h2>
  34 <p>String Utility Functions — various string-related functions</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="glib-String-Utility-Functions.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis">
  41 #include &lt;glib.h&gt;
  42 #include &lt;glib/gprintf.h&gt;
  43
  44 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strdup" title="g_strdup ()">g_strdup</a>                            (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>);
  45 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strndup" title="g_strndup ()">g_strndup</a>                           (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
  46                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> n</code></em>);
  47 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            <a class="link" href="glib-String-Utility-Functions.html#g-strdupv" title="g_strdupv ()">g_strdupv</a>                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **str_array</code></em>);
  48 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strnfill" title="g_strnfill ()">g_strnfill</a>                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> length</code></em>,
  49                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> fill_char</code></em>);
  50 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-stpcpy" title="g_stpcpy ()">g_stpcpy</a>                            (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *dest</code></em>,
  51                                                          <em class="parameter"><code>const <span class="type">char</span> *src</code></em>);
  52 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strstr-len" title="g_strstr_len ()">g_strstr_len</a>                        (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *haystack</code></em>,
  53                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> haystack_len</code></em>,
  54                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *needle</code></em>);
  55 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strrstr" title="g_strrstr ()">g_strrstr</a>                           (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *haystack</code></em>,
  56                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *needle</code></em>);
  57 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strrstr-len" title="g_strrstr_len ()">g_strrstr_len</a>                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *haystack</code></em>,
  58                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> haystack_len</code></em>,
  59                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *needle</code></em>);
  60 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-String-Utility-Functions.html#g-str-has-prefix" title="g_str_has_prefix ()">g_str_has_prefix</a>                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
  61                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *prefix</code></em>);
  62 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-String-Utility-Functions.html#g-str-has-suffix" title="g_str_has_suffix ()">g_str_has_suffix</a>                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
  63                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *suffix</code></em>);
  64 <span class="returnvalue">int</span>                 <a class="link" href="glib-String-Utility-Functions.html#g-strcmp0" title="g_strcmp0 ()">g_strcmp0</a>                           (<em class="parameter"><code>const <span class="type">char</span> *str1</code></em>,
  65                                                          <em class="parameter"><code>const <span class="type">char</span> *str2</code></em>);
  66
  67 <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               <a class="link" href="glib-String-Utility-Functions.html#g-strlcpy" title="g_strlcpy ()">g_strlcpy</a>                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *dest</code></em>,
  68                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *src</code></em>,
  69                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> dest_size</code></em>);
  70 <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               <a class="link" href="glib-String-Utility-Functions.html#g-strlcat" title="g_strlcat ()">g_strlcat</a>                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *dest</code></em>,
  71                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *src</code></em>,
  72                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> dest_size</code></em>);
  73
  74 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strdup-printf" title="g_strdup_printf ()">g_strdup_printf</a>                     (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
  75                                                          <em class="parameter"><code>...</code></em>);
  76 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strdup-vprintf" title="g_strdup_vprintf ()">g_strdup_vprintf</a>                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
  77                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);
  78 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-printf" title="g_printf ()">g_printf</a>                            (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
  79                                                          <em class="parameter"><code>...</code></em>);
  80 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-vprintf" title="g_vprintf ()">g_vprintf</a>                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
  81                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);
  82 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-fprintf" title="g_fprintf ()">g_fprintf</a>                           (<em class="parameter"><code><span class="type">FILE</span> *file</code></em>,
  83                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
  84                                                          <em class="parameter"><code>...</code></em>);
  85 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-vfprintf" title="g_vfprintf ()">g_vfprintf</a>                          (<em class="parameter"><code><span class="type">FILE</span> *file</code></em>,
  86                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
  87                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);
  88 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-sprintf" title="g_sprintf ()">g_sprintf</a>                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
  89                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
  90                                                          <em class="parameter"><code>...</code></em>);
  91 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-vsprintf" title="g_vsprintf ()">g_vsprintf</a>                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
  92                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
  93                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);
  94 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-snprintf" title="g_snprintf ()">g_snprintf</a>                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
  95                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> n</code></em>,
  96                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
  97                                                          <em class="parameter"><code>...</code></em>);
  98 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-vsnprintf" title="g_vsnprintf ()">g_vsnprintf</a>                         (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
  99                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> n</code></em>,
 100                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
 101                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);
 102 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-vasprintf" title="g_vasprintf ()">g_vasprintf</a>                         (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **string</code></em>,
 103                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
 104                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);
 105 <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               <a class="link" href="glib-String-Utility-Functions.html#g-printf-string-upper-bound" title="g_printf_string_upper_bound ()">g_printf_string_upper_bound</a>         (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
 106                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);
 107
 108 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-String-Utility-Functions.html#g-ascii-isalnum" title="g_ascii_isalnum ()">g_ascii_isalnum</a>                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 109 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-String-Utility-Functions.html#g-ascii-isalpha" title="g_ascii_isalpha ()">g_ascii_isalpha</a>                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 110 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-String-Utility-Functions.html#g-ascii-iscntrl" title="g_ascii_iscntrl ()">g_ascii_iscntrl</a>                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 111 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-String-Utility-Functions.html#g-ascii-isdigit" title="g_ascii_isdigit ()">g_ascii_isdigit</a>                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 112 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-String-Utility-Functions.html#g-ascii-isgraph" title="g_ascii_isgraph ()">g_ascii_isgraph</a>                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 113 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-String-Utility-Functions.html#g-ascii-islower" title="g_ascii_islower ()">g_ascii_islower</a>                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 114 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-String-Utility-Functions.html#g-ascii-isprint" title="g_ascii_isprint ()">g_ascii_isprint</a>                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 115 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-String-Utility-Functions.html#g-ascii-ispunct" title="g_ascii_ispunct ()">g_ascii_ispunct</a>                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 116 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-String-Utility-Functions.html#g-ascii-isspace" title="g_ascii_isspace ()">g_ascii_isspace</a>                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 117 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-String-Utility-Functions.html#g-ascii-isupper" title="g_ascii_isupper ()">g_ascii_isupper</a>                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 118 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-String-Utility-Functions.html#g-ascii-isxdigit" title="g_ascii_isxdigit ()">g_ascii_isxdigit</a>                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 119
 120 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-ascii-digit-value" title="g_ascii_digit_value ()">g_ascii_digit_value</a>                 (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 121 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-ascii-xdigit-value" title="g_ascii_xdigit_value ()">g_ascii_xdigit_value</a>                (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 122
 123 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strcasecmp" title="g_ascii_strcasecmp ()">g_ascii_strcasecmp</a>                  (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s1</code></em>,
 124                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s2</code></em>);
 125 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strncasecmp" title="g_ascii_strncasecmp ()">g_ascii_strncasecmp</a>                 (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s1</code></em>,
 126                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s2</code></em>,
 127                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> n</code></em>);
 128
 129 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strup" title="g_ascii_strup ()">g_ascii_strup</a>                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
 130                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>);
 131 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strdown" title="g_ascii_strdown ()">g_ascii_strdown</a>                     (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
 132                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>);
 133
 134 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a>               <a class="link" href="glib-String-Utility-Functions.html#g-ascii-tolower" title="g_ascii_tolower ()">g_ascii_tolower</a>                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 135 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a>               <a class="link" href="glib-String-Utility-Functions.html#g-ascii-toupper" title="g_ascii_toupper ()">g_ascii_toupper</a>                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);
 136
 137 <a class="link" href="glib-Strings.html#GString" title="struct GString"><span class="returnvalue">GString</span></a> *           <a class="link" href="glib-String-Utility-Functions.html#g-string-ascii-up" title="g_string_ascii_up ()">g_string_ascii_up</a>                   (<em class="parameter"><code><a class="link" href="glib-Strings.html#GString" title="struct GString"><span class="type">GString</span></a> *string</code></em>);
 138 <a class="link" href="glib-Strings.html#GString" title="struct GString"><span class="returnvalue">GString</span></a> *           <a class="link" href="glib-String-Utility-Functions.html#g-string-ascii-down" title="g_string_ascii_down ()">g_string_ascii_down</a>                 (<em class="parameter"><code><a class="link" href="glib-Strings.html#GString" title="struct GString"><span class="type">GString</span></a> *string</code></em>);
 139
 140 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strup" title="g_strup ()">g_strup</a>                             (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>);
 141 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strdown" title="g_strdown ()">g_strdown</a>                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>);
 142
 143 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-strcasecmp" title="g_strcasecmp ()">g_strcasecmp</a>                        (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s1</code></em>,
 144                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s2</code></em>);
 145 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-String-Utility-Functions.html#g-strncasecmp" title="g_strncasecmp ()">g_strncasecmp</a>                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s1</code></em>,
 146                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s2</code></em>,
 147                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> n</code></em>);
 148
 149 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strreverse" title="g_strreverse ()">g_strreverse</a>                        (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>);
 150
 151 <a class="link" href="glib-Basic-Types.html#gint64" title="gint64"><span class="returnvalue">gint64</span></a>              <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strtoll" title="g_ascii_strtoll ()">g_ascii_strtoll</a>                     (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *nptr</code></em>,
 152                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **endptr</code></em>,
 153                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> base</code></em>);
 154 <a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="returnvalue">guint64</span></a>             <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strtoull" title="g_ascii_strtoull ()">g_ascii_strtoull</a>                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *nptr</code></em>,
 155                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **endptr</code></em>,
 156                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> base</code></em>);
 157 #define             <a class="link" href="glib-String-Utility-Functions.html#G-ASCII-DTOSTR-BUF-SIZE:CAPS" title="G_ASCII_DTOSTR_BUF_SIZE">G_ASCII_DTOSTR_BUF_SIZE</a>
 158 <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="returnvalue">gdouble</span></a>             <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strtod" title="g_ascii_strtod ()">g_ascii_strtod</a>                      (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *nptr</code></em>,
 159                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **endptr</code></em>);
 160 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-ascii-dtostr" title="g_ascii_dtostr ()">g_ascii_dtostr</a>                      (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *buffer</code></em>,
 161                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> buf_len</code></em>,
 162                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> d</code></em>);
 163 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-ascii-formatd" title="g_ascii_formatd ()">g_ascii_formatd</a>                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *buffer</code></em>,
 164                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> buf_len</code></em>,
 165                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
 166                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> d</code></em>);
 167 <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="returnvalue">gdouble</span></a>             <a class="link" href="glib-String-Utility-Functions.html#g-strtod" title="g_strtod ()">g_strtod</a>                            (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *nptr</code></em>,
 168                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **endptr</code></em>);
 169
 170 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strchug" title="g_strchug ()">g_strchug</a>                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>);
 171 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strchomp" title="g_strchomp ()">g_strchomp</a>                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>);
 172 #define             <a class="link" href="glib-String-Utility-Functions.html#g-strstrip" title="g_strstrip()">g_strstrip</a>                          (string)
 173
 174 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strdelimit" title="g_strdelimit ()">g_strdelimit</a>                        (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
 175                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *delimiters</code></em>,
 176                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> new_delimiter</code></em>);
 177 #define             <a class="link" href="glib-String-Utility-Functions.html#G-STR-DELIMITERS:CAPS" title="G_STR_DELIMITERS">G_STR_DELIMITERS</a>
 178 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strescape" title="g_strescape ()">g_strescape</a>                         (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *source</code></em>,
 179                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *exceptions</code></em>);
 180 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strcompress" title="g_strcompress ()">g_strcompress</a>                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *source</code></em>);
 181 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strcanon" title="g_strcanon ()">g_strcanon</a>                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
 182                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *valid_chars</code></em>,
 183                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> substitutor</code></em>);
 184 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            <a class="link" href="glib-String-Utility-Functions.html#g-strsplit" title="g_strsplit ()">g_strsplit</a>                          (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
 185                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *delimiter</code></em>,
 186                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> max_tokens</code></em>);
 187 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            <a class="link" href="glib-String-Utility-Functions.html#g-strsplit-set" title="g_strsplit_set ()">g_strsplit_set</a>                      (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
 188                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *delimiters</code></em>,
 189                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> max_tokens</code></em>);
 190 <span class="returnvalue">void</span>                <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()">g_strfreev</a>                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **str_array</code></em>);
 191 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strconcat" title="g_strconcat ()">g_strconcat</a>                         (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string1</code></em>,
 192                                                          <em class="parameter"><code>...</code></em>);
 193 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strjoin" title="g_strjoin ()">g_strjoin</a>                           (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *separator</code></em>,
 194                                                          <em class="parameter"><code>...</code></em>);
 195 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-String-Utility-Functions.html#g-strjoinv" title="g_strjoinv ()">g_strjoinv</a>                          (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *separator</code></em>,
 196                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **str_array</code></em>);
 197 <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               <a class="link" href="glib-String-Utility-Functions.html#g-strv-length" title="g_strv_length ()">g_strv_length</a>                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **str_array</code></em>);
 198
 199 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-String-Utility-Functions.html#g-strerror" title="g_strerror ()">g_strerror</a>                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> errnum</code></em>);
 200 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-String-Utility-Functions.html#g-strsignal" title="g_strsignal ()">g_strsignal</a>                         (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> signum</code></em>);
 201 </pre>
 202 </div>
 203 <div class="refsect1">
 204 <a name="glib-String-Utility-Functions.description"></a><h2>Description</h2>
 205 <p>
 206 This section describes a number of utility functions for creating,
 207 duplicating, and manipulating strings.
 208 </p>
 209 <p>
 210 Note that the functions <a class="link" href="glib-String-Utility-Functions.html#g-printf" title="g_printf ()"><code class="function">g_printf()</code></a>, <a class="link" href="glib-String-Utility-Functions.html#g-fprintf" title="g_fprintf ()"><code class="function">g_fprintf()</code></a>, <a class="link" href="glib-String-Utility-Functions.html#g-sprintf" title="g_sprintf ()"><code class="function">g_sprintf()</code></a>,
 211 <a class="link" href="glib-String-Utility-Functions.html#g-snprintf" title="g_snprintf ()"><code class="function">g_snprintf()</code></a>, <a class="link" href="glib-String-Utility-Functions.html#g-vprintf" title="g_vprintf ()"><code class="function">g_vprintf()</code></a>, <a class="link" href="glib-String-Utility-Functions.html#g-vfprintf" title="g_vfprintf ()"><code class="function">g_vfprintf()</code></a>, <a class="link" href="glib-String-Utility-Functions.html#g-vsprintf" title="g_vsprintf ()"><code class="function">g_vsprintf()</code></a> and <a class="link" href="glib-String-Utility-Functions.html#g-vsnprintf" title="g_vsnprintf ()"><code class="function">g_vsnprintf()</code></a>
 212 are declared in the header <code class="filename">gprintf.h</code> which is
 213 <span class="emphasis"><em>not</em></span> included in <code class="filename">glib.h</code>
 214 (otherwise using <code class="filename">glib.h</code> would drag in
 215 <code class="filename">stdio.h</code>), so you'll have to explicitly include
 216 <code class="literal">&lt;glib/gprintf.h&gt;</code> in order to use the GLib
 217 <code class="function">printf()</code> functions.
 218 </p>
 219 <p>
 220 </p>
 221 <p><a name="string-precision"></a>While you may use the <code class="function">printf()</code> functions
 222 to format UTF-8 strings, notice that the precision of a
 223 <code class="literal">%Ns</code> parameter is interpreted as the
 224 number of <span class="emphasis"><em>bytes</em></span>, not <span class="emphasis"><em>characters</em></span>
 225 to print. On top of that, the GNU libc implementation of the <code class="function">printf()</code>
 226 functions has the "feature" that it checks that the string given for
 227 the <code class="literal">%Ns</code> parameter consists of a whole number
 228 of characters in the current encoding. So, unless you are sure you are
 229 always going to be in an UTF-8 locale or your know your text is restricted
 230 to ASCII, avoid using <code class="literal">%Ns</code>. If your intention is
 231 to format strings for a certain number of columns, then
 232 <code class="literal">%Ns</code> is not a correct solution anyway, since it
 233 fails to take wide characters (see <a class="link" href="glib-Unicode-Manipulation.html#g-unichar-iswide" title="g_unichar_iswide ()"><code class="function">g_unichar_iswide()</code></a>) into account.
 234 </p>
 235 <p>
 236 </p>
 237 </div>
 238 <div class="refsect1">
 239 <a name="glib-String-Utility-Functions.details"></a><h2>Details</h2>
 240 <div class="refsect2">
 241 <a name="g-strdup"></a><h3>g_strdup ()</h3>
 242 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strdup                            (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>);</pre>
 243 <p>
 244 Duplicates a string. If <em class="parameter"><code>str</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> it returns <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
 245 The returned string should be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>
 246 when no longer needed.
 247 </p>
 248 <div class="variablelist"><table border="0">
 249 <col align="left" valign="top">
 250 <tbody>
 251 <tr>
 252 <td><p><span class="term"><em class="parameter"><code>str</code></em> :</span></p></td>
 253 <td>the string to duplicate</td>
 254 </tr>
 255 <tr>
 256 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 257 <td>a newly-allocated copy of <em class="parameter"><code>str</code></em>
 258 </td>
 259 </tr>
 260 </tbody>
 261 </table></div>
 262 </div>
 263 <hr>
 264 <div class="refsect2">
 265 <a name="g-strndup"></a><h3>g_strndup ()</h3>
 266 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strndup                           (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
 267                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> n</code></em>);</pre>
 268 <p>
 269 Duplicates the first <em class="parameter"><code>n</code></em> bytes of a string, returning a newly-allocated
 270 buffer <em class="parameter"><code>n</code></em> + 1 bytes long which will always be nul-terminated.
 271 If <em class="parameter"><code>str</code></em> is less than <em class="parameter"><code>n</code></em> bytes long the buffer is padded with nuls.
 272 If <em class="parameter"><code>str</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> it returns <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
 273 The returned value should be freed when no longer needed.
 274 </p>
 275 <p>
 276 </p>
 277 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 278 <h3 class="title">Note</h3>
 279 <p>
 280 To copy a number of characters from a UTF-8 encoded string, use
 281 <a class="link" href="glib-Unicode-Manipulation.html#g-utf8-strncpy" title="g_utf8_strncpy ()"><code class="function">g_utf8_strncpy()</code></a> instead.
 282 </p>
 283 </div>
 284 <p>
 285 </p>
 286 <div class="variablelist"><table border="0">
 287 <col align="left" valign="top">
 288 <tbody>
 289 <tr>
 290 <td><p><span class="term"><em class="parameter"><code>str</code></em> :</span></p></td>
 291 <td>the string to duplicate</td>
 292 </tr>
 293 <tr>
 294 <td><p><span class="term"><em class="parameter"><code>n</code></em> :</span></p></td>
 295 <td>the maximum number of bytes to copy from <em class="parameter"><code>str</code></em>
 296 </td>
 297 </tr>
 298 <tr>
 299 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 300 <td>a newly-allocated buffer containing the first <em class="parameter"><code>n</code></em> bytes
 301 of <em class="parameter"><code>str</code></em>, nul-terminated</td>
 302 </tr>
 303 </tbody>
 304 </table></div>
 305 </div>
 306 <hr>
 307 <div class="refsect2">
 308 <a name="g-strdupv"></a><h3>g_strdupv ()</h3>
 309 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            g_strdupv                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **str_array</code></em>);</pre>
 310 <p>
 311 Copies <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings. The copy is a deep copy;
 312 the new array should be freed by first freeing each string, then
 313 the array itself. <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a> does this for you. If called
 314 on a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> value, <a class="link" href="glib-String-Utility-Functions.html#g-strdupv" title="g_strdupv ()"><code class="function">g_strdupv()</code></a> simply returns <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
 315 </p>
 316 <div class="variablelist"><table border="0">
 317 <col align="left" valign="top">
 318 <tbody>
 319 <tr>
 320 <td><p><span class="term"><em class="parameter"><code>str_array</code></em> :</span></p></td>
 321 <td>a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings</td>
 322 </tr>
 323 <tr>
 324 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 325 <td>a new <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings.</td>
 326 </tr>
 327 </tbody>
 328 </table></div>
 329 </div>
 330 <hr>
 331 <div class="refsect2">
 332 <a name="g-strnfill"></a><h3>g_strnfill ()</h3>
 333 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strnfill                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> length</code></em>,
 334                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> fill_char</code></em>);</pre>
 335 <p>
 336 Creates a new string <em class="parameter"><code>length</code></em> bytes long filled with <em class="parameter"><code>fill_char</code></em>.
 337 The returned string should be freed when no longer needed.
 338 </p>
 339 <div class="variablelist"><table border="0">
 340 <col align="left" valign="top">
 341 <tbody>
 342 <tr>
 343 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
 344 <td>the length of the new string</td>
 345 </tr>
 346 <tr>
 347 <td><p><span class="term"><em class="parameter"><code>fill_char</code></em> :</span></p></td>
 348 <td>the byte to fill the string with</td>
 349 </tr>
 350 <tr>
 351 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 352 <td>a newly-allocated string filled the <em class="parameter"><code>fill_char</code></em>
 353 </td>
 354 </tr>
 355 </tbody>
 356 </table></div>
 357 </div>
 358 <hr>
 359 <div class="refsect2">
 360 <a name="g-stpcpy"></a><h3>g_stpcpy ()</h3>
 361 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_stpcpy                            (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *dest</code></em>,
 362                                                          <em class="parameter"><code>const <span class="type">char</span> *src</code></em>);</pre>
 363 <p>
 364 Copies a nul-terminated string into the dest buffer, include the
 365 trailing nul, and return a pointer to the trailing nul byte.
 366 This is useful for concatenating multiple strings together
 367 without having to repeatedly scan for the end.
 368 </p>
 369 <div class="variablelist"><table border="0">
 370 <col align="left" valign="top">
 371 <tbody>
 372 <tr>
 373 <td><p><span class="term"><em class="parameter"><code>dest</code></em> :</span></p></td>
 374 <td>destination buffer.</td>
 375 </tr>
 376 <tr>
 377 <td><p><span class="term"><em class="parameter"><code>src</code></em> :</span></p></td>
 378 <td>source string.</td>
 379 </tr>
 380 <tr>
 381 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 382 <td>a pointer to trailing nul byte.</td>
 383 </tr>
 384 </tbody>
 385 </table></div>
 386 </div>
 387 <hr>
 388 <div class="refsect2">
 389 <a name="g-strstr-len"></a><h3>g_strstr_len ()</h3>
 390 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strstr_len                        (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *haystack</code></em>,
 391                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> haystack_len</code></em>,
 392                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *needle</code></em>);</pre>
 393 <p>
 394 Searches the string <em class="parameter"><code>haystack</code></em> for the first occurrence
 395 of the string <em class="parameter"><code>needle</code></em>, limiting the length of the search
 396 to <em class="parameter"><code>haystack_len</code></em>.
 397 </p>
 398 <div class="variablelist"><table border="0">
 399 <col align="left" valign="top">
 400 <tbody>
 401 <tr>
 402 <td><p><span class="term"><em class="parameter"><code>haystack</code></em> :</span></p></td>
 403 <td>a string</td>
 404 </tr>
 405 <tr>
 406 <td><p><span class="term"><em class="parameter"><code>haystack_len</code></em> :</span></p></td>
 407 <td>the maximum length of <em class="parameter"><code>haystack</code></em>. Note that -1 is
 408 a valid length, if <em class="parameter"><code>haystack</code></em> is nul-terminated, meaning it will
 409 search through the whole string.</td>
 410 </tr>
 411 <tr>
 412 <td><p><span class="term"><em class="parameter"><code>needle</code></em> :</span></p></td>
 413 <td>the string to search for</td>
 414 </tr>
 415 <tr>
 416 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 417 <td>a pointer to the found occurrence, or
 418 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if not found.</td>
 419 </tr>
 420 </tbody>
 421 </table></div>
 422 </div>
 423 <hr>
 424 <div class="refsect2">
 425 <a name="g-strrstr"></a><h3>g_strrstr ()</h3>
 426 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strrstr                           (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *haystack</code></em>,
 427                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *needle</code></em>);</pre>
 428 <p>
 429 Searches the string <em class="parameter"><code>haystack</code></em> for the last occurrence
 430 of the string <em class="parameter"><code>needle</code></em>.
 431 </p>
 432 <div class="variablelist"><table border="0">
 433 <col align="left" valign="top">
 434 <tbody>
 435 <tr>
 436 <td><p><span class="term"><em class="parameter"><code>haystack</code></em> :</span></p></td>
 437 <td>a nul-terminated string</td>
 438 </tr>
 439 <tr>
 440 <td><p><span class="term"><em class="parameter"><code>needle</code></em> :</span></p></td>
 441 <td>the nul-terminated string to search for</td>
 442 </tr>
 443 <tr>
 444 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 445 <td>a pointer to the found occurrence, or
 446 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if not found.</td>
 447 </tr>
 448 </tbody>
 449 </table></div>
 450 </div>
 451 <hr>
 452 <div class="refsect2">
 453 <a name="g-strrstr-len"></a><h3>g_strrstr_len ()</h3>
 454 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strrstr_len                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *haystack</code></em>,
 455                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> haystack_len</code></em>,
 456                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *needle</code></em>);</pre>
 457 <p>
 458 Searches the string <em class="parameter"><code>haystack</code></em> for the last occurrence
 459 of the string <em class="parameter"><code>needle</code></em>, limiting the length of the search
 460 to <em class="parameter"><code>haystack_len</code></em>.
 461 </p>
 462 <div class="variablelist"><table border="0">
 463 <col align="left" valign="top">
 464 <tbody>
 465 <tr>
 466 <td><p><span class="term"><em class="parameter"><code>haystack</code></em> :</span></p></td>
 467 <td>a nul-terminated string</td>
 468 </tr>
 469 <tr>
 470 <td><p><span class="term"><em class="parameter"><code>haystack_len</code></em> :</span></p></td>
 471 <td>the maximum length of <em class="parameter"><code>haystack</code></em>
 472 </td>
 473 </tr>
 474 <tr>
 475 <td><p><span class="term"><em class="parameter"><code>needle</code></em> :</span></p></td>
 476 <td>the nul-terminated string to search for</td>
 477 </tr>
 478 <tr>
 479 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 480 <td>a pointer to the found occurrence, or
 481 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if not found.</td>
 482 </tr>
 483 </tbody>
 484 </table></div>
 485 </div>
 486 <hr>
 487 <div class="refsect2">
 488 <a name="g-str-has-prefix"></a><h3>g_str_has_prefix ()</h3>
 489 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_str_has_prefix                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
 490                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *prefix</code></em>);</pre>
 491 <p>
 492 Looks whether the string <em class="parameter"><code>str</code></em> begins with <em class="parameter"><code>prefix</code></em>.
 493 </p>
 494 <div class="variablelist"><table border="0">
 495 <col align="left" valign="top">
 496 <tbody>
 497 <tr>
 498 <td><p><span class="term"><em class="parameter"><code>str</code></em> :</span></p></td>
 499 <td>a nul-terminated string</td>
 500 </tr>
 501 <tr>
 502 <td><p><span class="term"><em class="parameter"><code>prefix</code></em> :</span></p></td>
 503 <td>the nul-terminated prefix to look for</td>
 504 </tr>
 505 <tr>
 506 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 507 <td>
 508 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>str</code></em> begins with <em class="parameter"><code>prefix</code></em>, <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> otherwise.</td>
 509 </tr>
 510 </tbody>
 511 </table></div>
 512 <p class="since">Since 2.2</p>
 513 </div>
 514 <hr>
 515 <div class="refsect2">
 516 <a name="g-str-has-suffix"></a><h3>g_str_has_suffix ()</h3>
 517 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_str_has_suffix                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
 518                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *suffix</code></em>);</pre>
 519 <p>
 520 Looks whether the string <em class="parameter"><code>str</code></em> ends with <em class="parameter"><code>suffix</code></em>.
 521 </p>
 522 <div class="variablelist"><table border="0">
 523 <col align="left" valign="top">
 524 <tbody>
 525 <tr>
 526 <td><p><span class="term"><em class="parameter"><code>str</code></em> :</span></p></td>
 527 <td>a nul-terminated string</td>
 528 </tr>
 529 <tr>
 530 <td><p><span class="term"><em class="parameter"><code>suffix</code></em> :</span></p></td>
 531 <td>the nul-terminated suffix to look for</td>
 532 </tr>
 533 <tr>
 534 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 535 <td>
 536 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>str</code></em> end with <em class="parameter"><code>suffix</code></em>, <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> otherwise.</td>
 537 </tr>
 538 </tbody>
 539 </table></div>
 540 <p class="since">Since 2.2</p>
 541 </div>
 542 <hr>
 543 <div class="refsect2">
 544 <a name="g-strcmp0"></a><h3>g_strcmp0 ()</h3>
 545 <pre class="programlisting"><span class="returnvalue">int</span>                 g_strcmp0                           (<em class="parameter"><code>const <span class="type">char</span> *str1</code></em>,
 546                                                          <em class="parameter"><code>const <span class="type">char</span> *str2</code></em>);</pre>
 547 <p>
 548 Compares <em class="parameter"><code>str1</code></em> and <em class="parameter"><code>str2</code></em> like <code class="function">strcmp()</code>. Handles <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
 549 gracefully by sorting it before non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> strings.
 550 Comparing two <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> pointers returns 0.
 551 </p>
 552 <div class="variablelist"><table border="0">
 553 <col align="left" valign="top">
 554 <tbody>
 555 <tr>
 556 <td><p><span class="term"><em class="parameter"><code>str1</code></em> :</span></p></td>
 557 <td>a C string or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 558 </td>
 559 </tr>
 560 <tr>
 561 <td><p><span class="term"><em class="parameter"><code>str2</code></em> :</span></p></td>
 562 <td>another C string or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 563 </td>
 564 </tr>
 565 <tr>
 566 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 567 <td>-1, 0 or 1, if <em class="parameter"><code>str1</code></em> is &lt;, == or &gt; than <em class="parameter"><code>str2</code></em>.</td>
 568 </tr>
 569 </tbody>
 570 </table></div>
 571 <p class="since">Since 2.16</p>
 572 </div>
 573 <hr>
 574 <div class="refsect2">
 575 <a name="g-strlcpy"></a><h3>g_strlcpy ()</h3>
 576 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               g_strlcpy                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *dest</code></em>,
 577                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *src</code></em>,
 578                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> dest_size</code></em>);</pre>
 579 <p>
 580 Portability wrapper that calls <code class="function">strlcpy()</code> on systems which have it,
 581 and emulates <code class="function">strlcpy()</code> otherwise. Copies <em class="parameter"><code>src</code></em> to <em class="parameter"><code>dest</code></em>; <em class="parameter"><code>dest</code></em> is
 582 guaranteed to be nul-terminated; <em class="parameter"><code>src</code></em> must be nul-terminated;
 583 <em class="parameter"><code>dest_size</code></em> is the buffer size, not the number of chars to copy.
 584 </p>
 585 <p>
 586 At most dest_size - 1 characters will be copied. Always nul-terminates
 587 (unless dest_size == 0). This function does <span class="emphasis"><em>not</em></span>
 588 allocate memory. Unlike <code class="function">strncpy()</code>, this function doesn't pad dest (so
 589 it's often faster). It returns the size of the attempted result,
 590 strlen (src), so if <em class="parameter"><code>retval</code></em> &gt;= <em class="parameter"><code>dest_size</code></em>, truncation occurred.
 591 </p>
 592 <p>
 593 </p>
 594 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 595 <h3 class="title">Note</h3>
 596 <p>Caveat: <code class="function">strlcpy()</code> is supposedly more secure than
 597 <code class="function">strcpy()</code> or <code class="function">strncpy()</code>, but if you really want to avoid screwups,
 598 <a class="link" href="glib-String-Utility-Functions.html#g-strdup" title="g_strdup ()"><code class="function">g_strdup()</code></a> is an even better idea.</p>
 599 </div>
 600 <p>
 601 </p>
 602 <div class="variablelist"><table border="0">
 603 <col align="left" valign="top">
 604 <tbody>
 605 <tr>
 606 <td><p><span class="term"><em class="parameter"><code>dest</code></em> :</span></p></td>
 607 <td>destination buffer</td>
 608 </tr>
 609 <tr>
 610 <td><p><span class="term"><em class="parameter"><code>src</code></em> :</span></p></td>
 611 <td>source buffer</td>
 612 </tr>
 613 <tr>
 614 <td><p><span class="term"><em class="parameter"><code>dest_size</code></em> :</span></p></td>
 615 <td>length of <em class="parameter"><code>dest</code></em> in bytes</td>
 616 </tr>
 617 <tr>
 618 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 619 <td>length of <em class="parameter"><code>src</code></em>
 620 </td>
 621 </tr>
 622 </tbody>
 623 </table></div>
 624 </div>
 625 <hr>
 626 <div class="refsect2">
 627 <a name="g-strlcat"></a><h3>g_strlcat ()</h3>
 628 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               g_strlcat                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *dest</code></em>,
 629                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *src</code></em>,
 630                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> dest_size</code></em>);</pre>
 631 <p>
 632 Portability wrapper that calls <code class="function">strlcat()</code> on systems which have it,
 633 and emulates it otherwise. Appends nul-terminated <em class="parameter"><code>src</code></em> string to <em class="parameter"><code>dest</code></em>,
 634 guaranteeing nul-termination for <em class="parameter"><code>dest</code></em>. The total size of <em class="parameter"><code>dest</code></em> won't
 635 exceed <em class="parameter"><code>dest_size</code></em>.
 636 </p>
 637 <p>
 638 At most dest_size - 1 characters will be copied.
 639 Unlike strncat, dest_size is the full size of dest, not the space left over.
 640 This function does NOT allocate memory.
 641 This always NUL terminates (unless siz == 0 or there were no NUL characters
 642 in the dest_size characters of dest to start with).
 643 </p>
 644 <p>
 645 </p>
 646 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 647 <h3 class="title">Note</h3>
 648 <p>Caveat: this is supposedly a more secure alternative to
 649 <code class="function">strcat()</code> or <code class="function">strncat()</code>, but for real security <a class="link" href="glib-String-Utility-Functions.html#g-strconcat" title="g_strconcat ()"><code class="function">g_strconcat()</code></a> is harder
 650 to mess up.</p>
 651 </div>
 652 <p>
 653 </p>
 654 <div class="variablelist"><table border="0">
 655 <col align="left" valign="top">
 656 <tbody>
 657 <tr>
 658 <td><p><span class="term"><em class="parameter"><code>dest</code></em> :</span></p></td>
 659 <td>destination buffer, already containing one nul-terminated string</td>
 660 </tr>
 661 <tr>
 662 <td><p><span class="term"><em class="parameter"><code>src</code></em> :</span></p></td>
 663 <td>source buffer</td>
 664 </tr>
 665 <tr>
 666 <td><p><span class="term"><em class="parameter"><code>dest_size</code></em> :</span></p></td>
 667 <td>length of <em class="parameter"><code>dest</code></em> buffer in bytes (not length of existing string
 668 inside <em class="parameter"><code>dest</code></em>)</td>
 669 </tr>
 670 <tr>
 671 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 672 <td>size of attempted result, which is MIN (dest_size, strlen
 673 (original dest)) + strlen (src), so if retval &gt;= dest_size,
 674 truncation occurred.</td>
 675 </tr>
 676 </tbody>
 677 </table></div>
 678 </div>
 679 <hr>
 680 <div class="refsect2">
 681 <a name="g-strdup-printf"></a><h3>g_strdup_printf ()</h3>
 682 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strdup_printf                     (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
 683                                                          <em class="parameter"><code>...</code></em>);</pre>
 684 <p>
 685 Similar to the standard C <code class="function">sprintf()</code> function but safer, since it
 686 calculates the maximum space required and allocates memory to hold
 687 the result. The returned string should be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a> when no
 688 longer needed.
 689 </p>
 690 <div class="variablelist"><table border="0">
 691 <col align="left" valign="top">
 692 <tbody>
 693 <tr>
 694 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
 695 <td>a standard <code class="function">printf()</code> format string, but notice
 696 <a class="link" href="glib-String-Utility-Functions.html#string-precision">string precision pitfalls</a>
 697 </td>
 698 </tr>
 699 <tr>
 700 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
 701 <td>the parameters to insert into the format string</td>
 702 </tr>
 703 <tr>
 704 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 705 <td>a newly-allocated string holding the result</td>
 706 </tr>
 707 </tbody>
 708 </table></div>
 709 </div>
 710 <hr>
 711 <div class="refsect2">
 712 <a name="g-strdup-vprintf"></a><h3>g_strdup_vprintf ()</h3>
 713 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strdup_vprintf                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
 714                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);</pre>
 715 <p>
 716 Similar to the standard C <code class="function">vsprintf()</code> function but safer, since it
 717 calculates the maximum space required and allocates memory to hold
 718 the result. The returned string should be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a> when
 719 no longer needed.
 720 </p>
 721 <p>
 722 See also <a class="link" href="glib-String-Utility-Functions.html#g-vasprintf" title="g_vasprintf ()"><code class="function">g_vasprintf()</code></a>, which offers the same functionality, but
 723 additionally returns the length of the allocated string.
 724 </p>
 725 <div class="variablelist"><table border="0">
 726 <col align="left" valign="top">
 727 <tbody>
 728 <tr>
 729 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
 730 <td>a standard <code class="function">printf()</code> format string, but notice
 731 <a class="link" href="glib-String-Utility-Functions.html#string-precision">string precision pitfalls</a>
 732 </td>
 733 </tr>
 734 <tr>
 735 <td><p><span class="term"><em class="parameter"><code>args</code></em> :</span></p></td>
 736 <td>the list of parameters to insert into the format string</td>
 737 </tr>
 738 <tr>
 739 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 740 <td>a newly-allocated string holding the result</td>
 741 </tr>
 742 </tbody>
 743 </table></div>
 744 </div>
 745 <hr>
 746 <div class="refsect2">
 747 <a name="g-printf"></a><h3>g_printf ()</h3>
 748 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_printf                            (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
 749                                                          <em class="parameter"><code>...</code></em>);</pre>
 750 <p>
 751 An implementation of the standard <code class="function">printf()</code> function which supports
 752 positional parameters, as specified in the Single Unix Specification.
 753 </p>
 754 <div class="variablelist"><table border="0">
 755 <col align="left" valign="top">
 756 <tbody>
 757 <tr>
 758 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
 759 <td>a standard <code class="function">printf()</code> format string, but notice
 760 <a class="link" href="glib-String-Utility-Functions.html#string-precision">string precision pitfalls</a>.</td>
 761 </tr>
 762 <tr>
 763 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
 764 <td>the arguments to insert in the output.</td>
 765 </tr>
 766 <tr>
 767 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 768 <td>the number of bytes printed.</td>
 769 </tr>
 770 </tbody>
 771 </table></div>
 772 <p class="since">Since 2.2</p>
 773 </div>
 774 <hr>
 775 <div class="refsect2">
 776 <a name="g-vprintf"></a><h3>g_vprintf ()</h3>
 777 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_vprintf                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
 778                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);</pre>
 779 <p>
 780 An implementation of the standard <code class="function">vprintf()</code> function which supports
 781 positional parameters, as specified in the Single Unix Specification.
 782 </p>
 783 <div class="variablelist"><table border="0">
 784 <col align="left" valign="top">
 785 <tbody>
 786 <tr>
 787 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
 788 <td>a standard <code class="function">printf()</code> format string, but notice
 789 <a class="link" href="glib-String-Utility-Functions.html#string-precision">string precision pitfalls</a>.</td>
 790 </tr>
 791 <tr>
 792 <td><p><span class="term"><em class="parameter"><code>args</code></em> :</span></p></td>
 793 <td>the list of arguments to insert in the output.</td>
 794 </tr>
 795 <tr>
 796 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 797 <td>the number of bytes printed.</td>
 798 </tr>
 799 </tbody>
 800 </table></div>
 801 <p class="since">Since 2.2</p>
 802 </div>
 803 <hr>
 804 <div class="refsect2">
 805 <a name="g-fprintf"></a><h3>g_fprintf ()</h3>
 806 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_fprintf                           (<em class="parameter"><code><span class="type">FILE</span> *file</code></em>,
 807                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
 808                                                          <em class="parameter"><code>...</code></em>);</pre>
 809 <p>
 810 An implementation of the standard <code class="function">fprintf()</code> function which supports
 811 positional parameters, as specified in the Single Unix Specification.
 812 </p>
 813 <div class="variablelist"><table border="0">
 814 <col align="left" valign="top">
 815 <tbody>
 816 <tr>
 817 <td><p><span class="term"><em class="parameter"><code>file</code></em> :</span></p></td>
 818 <td>the stream to write to.</td>
 819 </tr>
 820 <tr>
 821 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
 822 <td>a standard <code class="function">printf()</code> format string, but notice
 823 <a class="link" href="glib-String-Utility-Functions.html#string-precision">string precision pitfalls</a>.</td>
 824 </tr>
 825 <tr>
 826 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
 827 <td>the arguments to insert in the output.</td>
 828 </tr>
 829 <tr>
 830 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 831 <td>the number of bytes printed.</td>
 832 </tr>
 833 </tbody>
 834 </table></div>
 835 <p class="since">Since 2.2</p>
 836 </div>
 837 <hr>
 838 <div class="refsect2">
 839 <a name="g-vfprintf"></a><h3>g_vfprintf ()</h3>
 840 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_vfprintf                          (<em class="parameter"><code><span class="type">FILE</span> *file</code></em>,
 841                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
 842                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);</pre>
 843 <p>
 844 An implementation of the standard <code class="function">fprintf()</code> function which supports
 845 positional parameters, as specified in the Single Unix Specification.
 846 </p>
 847 <div class="variablelist"><table border="0">
 848 <col align="left" valign="top">
 849 <tbody>
 850 <tr>
 851 <td><p><span class="term"><em class="parameter"><code>file</code></em> :</span></p></td>
 852 <td>the stream to write to.</td>
 853 </tr>
 854 <tr>
 855 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
 856 <td>a standard <code class="function">printf()</code> format string, but notice
 857 <a class="link" href="glib-String-Utility-Functions.html#string-precision">string precision pitfalls</a>.</td>
 858 </tr>
 859 <tr>
 860 <td><p><span class="term"><em class="parameter"><code>args</code></em> :</span></p></td>
 861 <td>the list of arguments to insert in the output.</td>
 862 </tr>
 863 <tr>
 864 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 865 <td>the number of bytes printed.</td>
 866 </tr>
 867 </tbody>
 868 </table></div>
 869 <p class="since">Since 2.2</p>
 870 </div>
 871 <hr>
 872 <div class="refsect2">
 873 <a name="g-sprintf"></a><h3>g_sprintf ()</h3>
 874 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_sprintf                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
 875                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
 876                                                          <em class="parameter"><code>...</code></em>);</pre>
 877 <p>
 878 An implementation of the standard <code class="function">sprintf()</code> function which supports
 879 positional parameters, as specified in the Single Unix Specification.
 880 </p>
 881 <p>
 882 Note that it is usually better to use <a class="link" href="glib-String-Utility-Functions.html#g-snprintf" title="g_snprintf ()"><code class="function">g_snprintf()</code></a>, to avoid the
 883 risk of buffer overflow.
 884 </p>
 885 <p>
 886 See also <a class="link" href="glib-String-Utility-Functions.html#g-strdup-printf" title="g_strdup_printf ()"><code class="function">g_strdup_printf()</code></a>.
 887 </p>
 888 <div class="variablelist"><table border="0">
 889 <col align="left" valign="top">
 890 <tbody>
 891 <tr>
 892 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
 893 <td>A pointer to a memory buffer to contain the resulting string. It
 894 is up to the caller to ensure that the allocated buffer is large
 895 enough to hold the formatted result</td>
 896 </tr>
 897 <tr>
 898 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
 899 <td>a standard <code class="function">printf()</code> format string, but notice
 900 <a class="link" href="glib-String-Utility-Functions.html#string-precision">string precision pitfalls</a>.</td>
 901 </tr>
 902 <tr>
 903 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
 904 <td>the arguments to insert in the output.</td>
 905 </tr>
 906 <tr>
 907 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 908 <td>the number of bytes printed.</td>
 909 </tr>
 910 </tbody>
 911 </table></div>
 912 <p class="since">Since 2.2</p>
 913 </div>
 914 <hr>
 915 <div class="refsect2">
 916 <a name="g-vsprintf"></a><h3>g_vsprintf ()</h3>
 917 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_vsprintf                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
 918                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
 919                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);</pre>
 920 <p>
 921 An implementation of the standard <code class="function">vsprintf()</code> function which supports
 922 positional parameters, as specified in the Single Unix Specification.
 923 </p>
 924 <div class="variablelist"><table border="0">
 925 <col align="left" valign="top">
 926 <tbody>
 927 <tr>
 928 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
 929 <td>the buffer to hold the output.</td>
 930 </tr>
 931 <tr>
 932 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
 933 <td>a standard <code class="function">printf()</code> format string, but notice
 934 <a class="link" href="glib-String-Utility-Functions.html#string-precision">string precision pitfalls</a>.</td>
 935 </tr>
 936 <tr>
 937 <td><p><span class="term"><em class="parameter"><code>args</code></em> :</span></p></td>
 938 <td>the list of arguments to insert in the output.</td>
 939 </tr>
 940 <tr>
 941 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 942 <td>the number of bytes printed.</td>
 943 </tr>
 944 </tbody>
 945 </table></div>
 946 <p class="since">Since 2.2</p>
 947 </div>
 948 <hr>
 949 <div class="refsect2">
 950 <a name="g-snprintf"></a><h3>g_snprintf ()</h3>
 951 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_snprintf                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
 952                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> n</code></em>,
 953                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
 954                                                          <em class="parameter"><code>...</code></em>);</pre>
 955 <p>
 956 A safer form of the standard <code class="function">sprintf()</code> function. The output is guaranteed
 957 to not exceed <em class="parameter"><code>n</code></em> characters (including the terminating nul character), so
 958 it is easy to ensure that a buffer overflow cannot occur.
 959 </p>
 960 <p>
 961 See also <a class="link" href="glib-String-Utility-Functions.html#g-strdup-printf" title="g_strdup_printf ()"><code class="function">g_strdup_printf()</code></a>.
 962 </p>
 963 <p>
 964 In versions of GLib prior to 1.2.3, this function may return -1 if the
 965 output was truncated, and the truncated string may not be nul-terminated.
 966 In versions prior to 1.3.12, this function returns the length of the output
 967 string.
 968 </p>
 969 <p>
 970 The return value of <a class="link" href="glib-String-Utility-Functions.html#g-snprintf" title="g_snprintf ()"><code class="function">g_snprintf()</code></a> conforms to the <code class="function">snprintf()</code>
 971 function as standardized in ISO C99. Note that this is different from
 972 traditional <code class="function">snprintf()</code>, which returns the length of the output string.
 973 </p>
 974 <p>
 975 The format string may contain positional parameters, as specified in
 976 the Single Unix Specification.
 977 </p>
 978 <div class="variablelist"><table border="0">
 979 <col align="left" valign="top">
 980 <tbody>
 981 <tr>
 982 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
 983 <td>the buffer to hold the output.</td>
 984 </tr>
 985 <tr>
 986 <td><p><span class="term"><em class="parameter"><code>n</code></em> :</span></p></td>
 987 <td>the maximum number of bytes to produce (including the
 988 terminating nul character).</td>
 989 </tr>
 990 <tr>
 991 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
 992 <td>a standard <code class="function">printf()</code> format string, but notice
 993 <a class="link" href="glib-String-Utility-Functions.html#string-precision">string precision pitfalls</a>.</td>
 994 </tr>
 995 <tr>
 996 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
 997 <td>the arguments to insert in the output.</td>
 998 </tr>
 999 <tr>
1000 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1001 <td>the number of bytes which would be produced if the buffer
1002 was large enough.</td>
1003 </tr>
1004 </tbody>
1005 </table></div>
1006 </div>
1007 <hr>
1008 <div class="refsect2">
1009 <a name="g-vsnprintf"></a><h3>g_vsnprintf ()</h3>
1010 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_vsnprintf                         (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
1011                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> n</code></em>,
1012                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
1013                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);</pre>
1014 <p>
1015 A safer form of the standard <code class="function">vsprintf()</code> function. The output is guaranteed
1016 to not exceed <em class="parameter"><code>n</code></em> characters (including the terminating nul character), so
1017 it is easy to ensure that a buffer overflow cannot occur.
1018 </p>
1019 <p>
1020 See also <a class="link" href="glib-String-Utility-Functions.html#g-strdup-vprintf" title="g_strdup_vprintf ()"><code class="function">g_strdup_vprintf()</code></a>.
1021 </p>
1022 <p>
1023 In versions of GLib prior to 1.2.3, this function may return -1 if the
1024 output was truncated, and the truncated string may not be nul-terminated.
1025 In versions prior to 1.3.12, this function returns the length of the output
1026 string.
1027 </p>
1028 <p>
1029 The return value of <a class="link" href="glib-String-Utility-Functions.html#g-vsnprintf" title="g_vsnprintf ()"><code class="function">g_vsnprintf()</code></a> conforms to the <code class="function">vsnprintf()</code> function
1030 as standardized in ISO C99. Note that this is different from traditional
1031 <code class="function">vsnprintf()</code>, which returns the length of the output string.
1032 </p>
1033 <p>
1034 The format string may contain positional parameters, as specified in
1035 the Single Unix Specification.
1036 </p>
1037 <div class="variablelist"><table border="0">
1038 <col align="left" valign="top">
1039 <tbody>
1040 <tr>
1041 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
1042 <td>the buffer to hold the output.</td>
1043 </tr>
1044 <tr>
1045 <td><p><span class="term"><em class="parameter"><code>n</code></em> :</span></p></td>
1046 <td>the maximum number of bytes to produce (including the
1047 terminating nul character).</td>
1048 </tr>
1049 <tr>
1050 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
1051 <td>a standard <code class="function">printf()</code> format string, but notice
1052 <a class="link" href="glib-String-Utility-Functions.html#string-precision">string precision pitfalls</a>.</td>
1053 </tr>
1054 <tr>
1055 <td><p><span class="term"><em class="parameter"><code>args</code></em> :</span></p></td>
1056 <td>the list of arguments to insert in the output.</td>
1057 </tr>
1058 <tr>
1059 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1060 <td>the number of bytes which would be produced if the buffer
1061 was large enough.</td>
1062 </tr>
1063 </tbody>
1064 </table></div>
1065 </div>
1066 <hr>
1067 <div class="refsect2">
1068 <a name="g-vasprintf"></a><h3>g_vasprintf ()</h3>
1069 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_vasprintf                         (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **string</code></em>,
1070                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> const *format</code></em>,
1071                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);</pre>
1072 <p>
1073 An implementation of the GNU <code class="function">vasprintf()</code> function which supports
1074 positional parameters, as specified in the Single Unix Specification.
1075 This function is similar to <a class="link" href="glib-String-Utility-Functions.html#g-vsprintf" title="g_vsprintf ()"><code class="function">g_vsprintf()</code></a>, except that it allocates a
1076 string to hold the output, instead of putting the output in a buffer
1077 you allocate in advance.
1078 </p>
1079 <div class="variablelist"><table border="0">
1080 <col align="left" valign="top">
1081 <tbody>
1082 <tr>
1083 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
1084 <td>the return location for the newly-allocated string.</td>
1085 </tr>
1086 <tr>
1087 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
1088 <td>a standard <code class="function">printf()</code> format string, but notice
1089 <a class="link" href="glib-String-Utility-Functions.html#string-precision">string precision pitfalls</a>.</td>
1090 </tr>
1091 <tr>
1092 <td><p><span class="term"><em class="parameter"><code>args</code></em> :</span></p></td>
1093 <td>the list of arguments to insert in the output.</td>
1094 </tr>
1095 <tr>
1096 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1097 <td>the number of bytes printed.</td>
1098 </tr>
1099 </tbody>
1100 </table></div>
1101 <p class="since">Since 2.4</p>
1102 </div>
1103 <hr>
1104 <div class="refsect2">
1105 <a name="g-printf-string-upper-bound"></a><h3>g_printf_string_upper_bound ()</h3>
1106 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               g_printf_string_upper_bound         (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
1107                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);</pre>
1108 <p>
1109 Calculates the maximum space needed to store the output
1110 of the <code class="function">sprintf()</code> function.
1111 </p>
1112 <div class="variablelist"><table border="0">
1113 <col align="left" valign="top">
1114 <tbody>
1115 <tr>
1116 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
1117 <td>the format string. See the <code class="function">printf()</code> documentation</td>
1118 </tr>
1119 <tr>
1120 <td><p><span class="term"><em class="parameter"><code>args</code></em> :</span></p></td>
1121 <td>the parameters to be inserted into the format string</td>
1122 </tr>
1123 <tr>
1124 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1125 <td>the maximum space needed to store the formatted string</td>
1126 </tr>
1127 </tbody>
1128 </table></div>
1129 </div>
1130 <hr>
1131 <div class="refsect2">
1132 <a name="g-ascii-isalnum"></a><h3>g_ascii_isalnum ()</h3>
1133 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_ascii_isalnum                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1134 <p>
1135 Determines whether a character is alphanumeric.
1136 </p>
1137 <p>
1138 Unlike the standard C library <code class="function">isalnum()</code> function, this only
1139 recognizes standard ASCII letters and ignores the locale,
1140 returning <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> for all non-ASCII characters. Also, unlike
1141 the standard library function, this takes a <span class="type">char</span>,
1142 not an <span class="type">int</span>, so don't call it on <code class="literal">EOF</code>, but no need to
1143 cast to <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a> before passing a possibly non-ASCII character in.
1144 </p>
1145 <div class="variablelist"><table border="0">
1146 <col align="left" valign="top">
1147 <tbody>
1148 <tr>
1149 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1150 <td>any character</td>
1151 </tr>
1152 <tr>
1153 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1154 <td>
1155 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>c</code></em> is an ASCII alphanumeric character</td>
1156 </tr>
1157 </tbody>
1158 </table></div>
1159 </div>
1160 <hr>
1161 <div class="refsect2">
1162 <a name="g-ascii-isalpha"></a><h3>g_ascii_isalpha ()</h3>
1163 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_ascii_isalpha                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1164 <p>
1165 Determines whether a character is alphabetic (i.e. a letter).
1166 </p>
1167 <p>
1168 Unlike the standard C library <code class="function">isalpha()</code> function, this only
1169 recognizes standard ASCII letters and ignores the locale,
1170 returning <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> for all non-ASCII characters. Also, unlike
1171 the standard library function, this takes a <span class="type">char</span>,
1172 not an <span class="type">int</span>, so don't call it on <code class="literal">EOF</code>, but no need to
1173 cast to <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a> before passing a possibly non-ASCII character in.
1174 </p>
1175 <div class="variablelist"><table border="0">
1176 <col align="left" valign="top">
1177 <tbody>
1178 <tr>
1179 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1180 <td>any character</td>
1181 </tr>
1182 <tr>
1183 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1184 <td>
1185 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>c</code></em> is an ASCII alphabetic character</td>
1186 </tr>
1187 </tbody>
1188 </table></div>
1189 </div>
1190 <hr>
1191 <div class="refsect2">
1192 <a name="g-ascii-iscntrl"></a><h3>g_ascii_iscntrl ()</h3>
1193 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_ascii_iscntrl                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1194 <p>
1195 Determines whether a character is a control character.
1196 </p>
1197 <p>
1198 Unlike the standard C library <code class="function">iscntrl()</code> function, this only
1199 recognizes standard ASCII control characters and ignores the
1200 locale, returning <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> for all non-ASCII characters. Also,
1201 unlike the standard library function, this takes a <span class="type">char</span>,
1202 not an <span class="type">int</span>, so don't call it on <code class="literal">EOF</code>, but no need to
1203 cast to <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a> before passing a possibly non-ASCII character in.
1204 </p>
1205 <div class="variablelist"><table border="0">
1206 <col align="left" valign="top">
1207 <tbody>
1208 <tr>
1209 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1210 <td>any character</td>
1211 </tr>
1212 <tr>
1213 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1214 <td>
1215 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>c</code></em> is an ASCII control character.</td>
1216 </tr>
1217 </tbody>
1218 </table></div>
1219 </div>
1220 <hr>
1221 <div class="refsect2">
1222 <a name="g-ascii-isdigit"></a><h3>g_ascii_isdigit ()</h3>
1223 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_ascii_isdigit                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1224 <p>
1225 Determines whether a character is digit (0-9).
1226 </p>
1227 <p>
1228 Unlike the standard C library <code class="function">isdigit()</code> function, this takes
1229 a <span class="type">char</span>, not an <span class="type">int</span>, so don't call it
1230 on <code class="literal">EOF</code>, but no need to cast to <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a> before passing a possibly
1231 non-ASCII character in.
1232 </p>
1233 <div class="variablelist"><table border="0">
1234 <col align="left" valign="top">
1235 <tbody>
1236 <tr>
1237 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1238 <td>any character</td>
1239 </tr>
1240 <tr>
1241 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1242 <td>
1243 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>c</code></em> is an ASCII digit.</td>
1244 </tr>
1245 </tbody>
1246 </table></div>
1247 </div>
1248 <hr>
1249 <div class="refsect2">
1250 <a name="g-ascii-isgraph"></a><h3>g_ascii_isgraph ()</h3>
1251 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_ascii_isgraph                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1252 <p>
1253 Determines whether a character is a printing character and not a space.
1254 </p>
1255 <p>
1256 Unlike the standard C library <code class="function">isgraph()</code> function, this only
1257 recognizes standard ASCII characters and ignores the locale,
1258 returning <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> for all non-ASCII characters. Also, unlike
1259 the standard library function, this takes a <span class="type">char</span>,
1260 not an <span class="type">int</span>, so don't call it on <code class="literal">EOF</code>, but no need
1261 to cast to <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a> before passing a possibly non-ASCII character in.
1262 </p>
1263 <div class="variablelist"><table border="0">
1264 <col align="left" valign="top">
1265 <tbody>
1266 <tr>
1267 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1268 <td>any character</td>
1269 </tr>
1270 <tr>
1271 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1272 <td>
1273 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>c</code></em> is an ASCII printing character other than space.</td>
1274 </tr>
1275 </tbody>
1276 </table></div>
1277 </div>
1278 <hr>
1279 <div class="refsect2">
1280 <a name="g-ascii-islower"></a><h3>g_ascii_islower ()</h3>
1281 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_ascii_islower                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1282 <p>
1283 Determines whether a character is an ASCII lower case letter.
1284 </p>
1285 <p>
1286 Unlike the standard C library <code class="function">islower()</code> function, this only
1287 recognizes standard ASCII letters and ignores the locale,
1288 returning <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> for all non-ASCII characters. Also, unlike
1289 the standard library function, this takes a <span class="type">char</span>,
1290 not an <span class="type">int</span>, so don't call it on <code class="literal">EOF</code>, but no need
1291 to worry about casting to <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a> before passing a possibly
1292 non-ASCII character in.
1293 </p>
1294 <div class="variablelist"><table border="0">
1295 <col align="left" valign="top">
1296 <tbody>
1297 <tr>
1298 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1299 <td>any character</td>
1300 </tr>
1301 <tr>
1302 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1303 <td>
1304 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>c</code></em> is an ASCII lower case letter</td>
1305 </tr>
1306 </tbody>
1307 </table></div>
1308 </div>
1309 <hr>
1310 <div class="refsect2">
1311 <a name="g-ascii-isprint"></a><h3>g_ascii_isprint ()</h3>
1312 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_ascii_isprint                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1313 <p>
1314 Determines whether a character is a printing character.
1315 </p>
1316 <p>
1317 Unlike the standard C library <code class="function">isprint()</code> function, this only
1318 recognizes standard ASCII characters and ignores the locale,
1319 returning <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> for all non-ASCII characters. Also, unlike
1320 the standard library function, this takes a <span class="type">char</span>,
1321 not an <span class="type">int</span>, so don't call it on <code class="literal">EOF</code>, but no need
1322 to cast to <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a> before passing a possibly non-ASCII character in.
1323 </p>
1324 <div class="variablelist"><table border="0">
1325 <col align="left" valign="top">
1326 <tbody>
1327 <tr>
1328 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1329 <td>any character</td>
1330 </tr>
1331 <tr>
1332 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1333 <td>
1334 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>c</code></em> is an ASCII printing character.</td>
1335 </tr>
1336 </tbody>
1337 </table></div>
1338 </div>
1339 <hr>
1340 <div class="refsect2">
1341 <a name="g-ascii-ispunct"></a><h3>g_ascii_ispunct ()</h3>
1342 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_ascii_ispunct                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1343 <p>
1344 Determines whether a character is a punctuation character.
1345 </p>
1346 <p>
1347 Unlike the standard C library <code class="function">ispunct()</code> function, this only
1348 recognizes standard ASCII letters and ignores the locale,
1349 returning <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> for all non-ASCII characters. Also, unlike
1350 the standard library function, this takes a <span class="type">char</span>,
1351 not an <span class="type">int</span>, so don't call it on <code class="literal">EOF</code>, but no need to
1352 cast to <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a> before passing a possibly non-ASCII character in.
1353 </p>
1354 <div class="variablelist"><table border="0">
1355 <col align="left" valign="top">
1356 <tbody>
1357 <tr>
1358 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1359 <td>any character</td>
1360 </tr>
1361 <tr>
1362 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1363 <td>
1364 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>c</code></em> is an ASCII punctuation character.</td>
1365 </tr>
1366 </tbody>
1367 </table></div>
1368 </div>
1369 <hr>
1370 <div class="refsect2">
1371 <a name="g-ascii-isspace"></a><h3>g_ascii_isspace ()</h3>
1372 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_ascii_isspace                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1373 <p>
1374 Determines whether a character is a white-space character.
1375 </p>
1376 <p>
1377 Unlike the standard C library <code class="function">isspace()</code> function, this only
1378 recognizes standard ASCII white-space and ignores the locale,
1379 returning <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> for all non-ASCII characters. Also, unlike
1380 the standard library function, this takes a <span class="type">char</span>,
1381 not an <span class="type">int</span>, so don't call it on <code class="literal">EOF</code>, but no need to
1382 cast to <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a> before passing a possibly non-ASCII character in.
1383 </p>
1384 <div class="variablelist"><table border="0">
1385 <col align="left" valign="top">
1386 <tbody>
1387 <tr>
1388 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1389 <td>any character</td>
1390 </tr>
1391 <tr>
1392 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1393 <td>
1394 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>c</code></em> is an ASCII white-space character</td>
1395 </tr>
1396 </tbody>
1397 </table></div>
1398 </div>
1399 <hr>
1400 <div class="refsect2">
1401 <a name="g-ascii-isupper"></a><h3>g_ascii_isupper ()</h3>
1402 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_ascii_isupper                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1403 <p>
1404 Determines whether a character is an ASCII upper case letter.
1405 </p>
1406 <p>
1407 Unlike the standard C library <code class="function">isupper()</code> function, this only
1408 recognizes standard ASCII letters and ignores the locale,
1409 returning <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> for all non-ASCII characters. Also, unlike
1410 the standard library function, this takes a <span class="type">char</span>,
1411 not an <span class="type">int</span>, so don't call it on <code class="literal">EOF</code>, but no need to
1412 worry about casting to <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a> before passing a possibly non-ASCII
1413 character in.
1414 </p>
1415 <div class="variablelist"><table border="0">
1416 <col align="left" valign="top">
1417 <tbody>
1418 <tr>
1419 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1420 <td>any character</td>
1421 </tr>
1422 <tr>
1423 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1424 <td>
1425 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>c</code></em> is an ASCII upper case letter</td>
1426 </tr>
1427 </tbody>
1428 </table></div>
1429 </div>
1430 <hr>
1431 <div class="refsect2">
1432 <a name="g-ascii-isxdigit"></a><h3>g_ascii_isxdigit ()</h3>
1433 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_ascii_isxdigit                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1434 <p>
1435 Determines whether a character is a hexadecimal-digit character.
1436 </p>
1437 <p>
1438 Unlike the standard C library <code class="function">isxdigit()</code> function, this takes
1439 a <span class="type">char</span>, not an <span class="type">int</span>, so don't call it
1440 on <code class="literal">EOF</code>, but no need to cast to <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a> before passing a
1441 possibly non-ASCII character in.
1442 </p>
1443 <div class="variablelist"><table border="0">
1444 <col align="left" valign="top">
1445 <tbody>
1446 <tr>
1447 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1448 <td>any character</td>
1449 </tr>
1450 <tr>
1451 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1452 <td>
1453 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>c</code></em> is an ASCII hexadecimal-digit character.</td>
1454 </tr>
1455 </tbody>
1456 </table></div>
1457 </div>
1458 <hr>
1459 <div class="refsect2">
1460 <a name="g-ascii-digit-value"></a><h3>g_ascii_digit_value ()</h3>
1461 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_ascii_digit_value                 (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1462 <p>
1463 Determines the numeric value of a character as a decimal
1464 digit. Differs from <a class="link" href="glib-Unicode-Manipulation.html#g-unichar-digit-value" title="g_unichar_digit_value ()"><code class="function">g_unichar_digit_value()</code></a> because it takes
1465 a char, so there's no worry about sign extension if characters
1466 are signed.
1467 </p>
1468 <div class="variablelist"><table border="0">
1469 <col align="left" valign="top">
1470 <tbody>
1471 <tr>
1472 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1473 <td>an ASCII character.</td>
1474 </tr>
1475 <tr>
1476 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1477 <td>If <em class="parameter"><code>c</code></em> is a decimal digit (according to
1478 <a class="link" href="glib-String-Utility-Functions.html#g-ascii-isdigit" title="g_ascii_isdigit ()"><code class="function">g_ascii_isdigit()</code></a>), its numeric value. Otherwise, -1.</td>
1479 </tr>
1480 </tbody>
1481 </table></div>
1482 </div>
1483 <hr>
1484 <div class="refsect2">
1485 <a name="g-ascii-xdigit-value"></a><h3>g_ascii_xdigit_value ()</h3>
1486 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_ascii_xdigit_value                (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1487 <p>
1488 Determines the numeric value of a character as a hexidecimal
1489 digit. Differs from <a class="link" href="glib-Unicode-Manipulation.html#g-unichar-xdigit-value" title="g_unichar_xdigit_value ()"><code class="function">g_unichar_xdigit_value()</code></a> because it takes
1490 a char, so there's no worry about sign extension if characters
1491 are signed.
1492 </p>
1493 <div class="variablelist"><table border="0">
1494 <col align="left" valign="top">
1495 <tbody>
1496 <tr>
1497 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1498 <td>an ASCII character.</td>
1499 </tr>
1500 <tr>
1501 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1502 <td>If <em class="parameter"><code>c</code></em> is a hex digit (according to
1503 <a class="link" href="glib-String-Utility-Functions.html#g-ascii-isxdigit" title="g_ascii_isxdigit ()"><code class="function">g_ascii_isxdigit()</code></a>), its numeric value. Otherwise, -1.</td>
1504 </tr>
1505 </tbody>
1506 </table></div>
1507 </div>
1508 <hr>
1509 <div class="refsect2">
1510 <a name="g-ascii-strcasecmp"></a><h3>g_ascii_strcasecmp ()</h3>
1511 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_ascii_strcasecmp                  (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s1</code></em>,
1512                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s2</code></em>);</pre>
1513 <p>
1514 Compare two strings, ignoring the case of ASCII characters.
1515 </p>
1516 <p>
1517 Unlike the BSD <code class="function">strcasecmp()</code> function, this only recognizes standard
1518 ASCII letters and ignores the locale, treating all non-ASCII
1519 bytes as if they are not letters.
1520 </p>
1521 <p>
1522 This function should be used only on strings that are known to be
1523 in encodings where the bytes corresponding to ASCII letters always
1524 represent themselves. This includes UTF-8 and the ISO-8859-*
1525 charsets, but not for instance double-byte encodings like the
1526 Windows Codepage 932, where the trailing bytes of double-byte
1527 characters include all ASCII letters. If you compare two CP932
1528 strings using this function, you will get false matches.
1529 </p>
1530 <div class="variablelist"><table border="0">
1531 <col align="left" valign="top">
1532 <tbody>
1533 <tr>
1534 <td><p><span class="term"><em class="parameter"><code>s1</code></em> :</span></p></td>
1535 <td>string to compare with <em class="parameter"><code>s2</code></em>.</td>
1536 </tr>
1537 <tr>
1538 <td><p><span class="term"><em class="parameter"><code>s2</code></em> :</span></p></td>
1539 <td>string to compare with <em class="parameter"><code>s1</code></em>.</td>
1540 </tr>
1541 <tr>
1542 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1543 <td>0 if the strings match, a negative value if <em class="parameter"><code>s1</code></em> &lt; <em class="parameter"><code>s2</code></em>,
1544 or a positive value if <em class="parameter"><code>s1</code></em> &gt; <em class="parameter"><code>s2</code></em>.</td>
1545 </tr>
1546 </tbody>
1547 </table></div>
1548 </div>
1549 <hr>
1550 <div class="refsect2">
1551 <a name="g-ascii-strncasecmp"></a><h3>g_ascii_strncasecmp ()</h3>
1552 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_ascii_strncasecmp                 (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s1</code></em>,
1553                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s2</code></em>,
1554                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> n</code></em>);</pre>
1555 <p>
1556 Compare <em class="parameter"><code>s1</code></em> and <em class="parameter"><code>s2</code></em>, ignoring the case of ASCII characters and any
1557 characters after the first <em class="parameter"><code>n</code></em> in each string.
1558 </p>
1559 <p>
1560 Unlike the BSD <code class="function">strcasecmp()</code> function, this only recognizes standard
1561 ASCII letters and ignores the locale, treating all non-ASCII
1562 characters as if they are not letters.
1563 </p>
1564 <p>
1565 The same warning as in <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strcasecmp" title="g_ascii_strcasecmp ()"><code class="function">g_ascii_strcasecmp()</code></a> applies: Use this
1566 function only on strings known to be in encodings where bytes
1567 corresponding to ASCII letters always represent themselves.
1568 </p>
1569 <div class="variablelist"><table border="0">
1570 <col align="left" valign="top">
1571 <tbody>
1572 <tr>
1573 <td><p><span class="term"><em class="parameter"><code>s1</code></em> :</span></p></td>
1574 <td>string to compare with <em class="parameter"><code>s2</code></em>.</td>
1575 </tr>
1576 <tr>
1577 <td><p><span class="term"><em class="parameter"><code>s2</code></em> :</span></p></td>
1578 <td>string to compare with <em class="parameter"><code>s1</code></em>.</td>
1579 </tr>
1580 <tr>
1581 <td><p><span class="term"><em class="parameter"><code>n</code></em> :</span></p></td>
1582 <td>number of characters to compare.</td>
1583 </tr>
1584 <tr>
1585 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1586 <td>0 if the strings match, a negative value if <em class="parameter"><code>s1</code></em> &lt; <em class="parameter"><code>s2</code></em>,
1587 or a positive value if <em class="parameter"><code>s1</code></em> &gt; <em class="parameter"><code>s2</code></em>.</td>
1588 </tr>
1589 </tbody>
1590 </table></div>
1591 </div>
1592 <hr>
1593 <div class="refsect2">
1594 <a name="g-ascii-strup"></a><h3>g_ascii_strup ()</h3>
1595 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_ascii_strup                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
1596                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>);</pre>
1597 <p>
1598 Converts all lower case ASCII letters to upper case ASCII letters.
1599 </p>
1600 <div class="variablelist"><table border="0">
1601 <col align="left" valign="top">
1602 <tbody>
1603 <tr>
1604 <td><p><span class="term"><em class="parameter"><code>str</code></em> :</span></p></td>
1605 <td>a string.</td>
1606 </tr>
1607 <tr>
1608 <td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
1609 <td>length of <em class="parameter"><code>str</code></em> in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</td>
1610 </tr>
1611 <tr>
1612 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1613 <td>a newly allocated string, with all the lower case
1614 characters in <em class="parameter"><code>str</code></em> converted to upper case, with
1615 semantics that exactly match <a class="link" href="glib-String-Utility-Functions.html#g-ascii-toupper" title="g_ascii_toupper ()"><code class="function">g_ascii_toupper()</code></a>. (Note
1616 that this is unlike the old <a class="link" href="glib-String-Utility-Functions.html#g-strup" title="g_strup ()"><code class="function">g_strup()</code></a>, which modified
1617 the string in place.)</td>
1618 </tr>
1619 </tbody>
1620 </table></div>
1621 </div>
1622 <hr>
1623 <div class="refsect2">
1624 <a name="g-ascii-strdown"></a><h3>g_ascii_strdown ()</h3>
1625 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_ascii_strdown                     (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
1626                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>);</pre>
1627 <p>
1628 Converts all upper case ASCII letters to lower case ASCII letters.
1629 </p>
1630 <div class="variablelist"><table border="0">
1631 <col align="left" valign="top">
1632 <tbody>
1633 <tr>
1634 <td><p><span class="term"><em class="parameter"><code>str</code></em> :</span></p></td>
1635 <td>a string.</td>
1636 </tr>
1637 <tr>
1638 <td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
1639 <td>length of <em class="parameter"><code>str</code></em> in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</td>
1640 </tr>
1641 <tr>
1642 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1643 <td>a newly-allocated string, with all the upper case
1644 characters in <em class="parameter"><code>str</code></em> converted to lower case, with
1645 semantics that exactly match <a class="link" href="glib-String-Utility-Functions.html#g-ascii-tolower" title="g_ascii_tolower ()"><code class="function">g_ascii_tolower()</code></a>. (Note
1646 that this is unlike the old <a class="link" href="glib-String-Utility-Functions.html#g-strdown" title="g_strdown ()"><code class="function">g_strdown()</code></a>, which modified
1647 the string in place.)</td>
1648 </tr>
1649 </tbody>
1650 </table></div>
1651 </div>
1652 <hr>
1653 <div class="refsect2">
1654 <a name="g-ascii-tolower"></a><h3>g_ascii_tolower ()</h3>
1655 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a>               g_ascii_tolower                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1656 <p>
1657 Convert a character to ASCII lower case.
1658 </p>
1659 <p>
1660 Unlike the standard C library <code class="function">tolower()</code> function, this only
1661 recognizes standard ASCII letters and ignores the locale, returning
1662 all non-ASCII characters unchanged, even if they are lower case
1663 letters in a particular character set. Also unlike the standard
1664 library function, this takes and returns a char, not an int, so
1665 don't call it on <code class="literal">EOF</code> but no need to worry about casting to <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a>
1666 before passing a possibly non-ASCII character in.
1667 </p>
1668 <div class="variablelist"><table border="0">
1669 <col align="left" valign="top">
1670 <tbody>
1671 <tr>
1672 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1673 <td>any character.</td>
1674 </tr>
1675 <tr>
1676 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1677 <td>the result of converting <em class="parameter"><code>c</code></em> to lower case.
1678 If <em class="parameter"><code>c</code></em> is not an ASCII upper case letter,
1679 <em class="parameter"><code>c</code></em> is returned unchanged.</td>
1680 </tr>
1681 </tbody>
1682 </table></div>
1683 </div>
1684 <hr>
1685 <div class="refsect2">
1686 <a name="g-ascii-toupper"></a><h3>g_ascii_toupper ()</h3>
1687 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a>               g_ascii_toupper                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> c</code></em>);</pre>
1688 <p>
1689 Convert a character to ASCII upper case.
1690 </p>
1691 <p>
1692 Unlike the standard C library <code class="function">toupper()</code> function, this only
1693 recognizes standard ASCII letters and ignores the locale, returning
1694 all non-ASCII characters unchanged, even if they are upper case
1695 letters in a particular character set. Also unlike the standard
1696 library function, this takes and returns a char, not an int, so
1697 don't call it on <code class="literal">EOF</code> but no need to worry about casting to <a class="link" href="glib-Basic-Types.html#guchar" title="guchar"><span class="type">guchar</span></a>
1698 before passing a possibly non-ASCII character in.
1699 </p>
1700 <div class="variablelist"><table border="0">
1701 <col align="left" valign="top">
1702 <tbody>
1703 <tr>
1704 <td><p><span class="term"><em class="parameter"><code>c</code></em> :</span></p></td>
1705 <td>any character.</td>
1706 </tr>
1707 <tr>
1708 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1709 <td>the result of converting <em class="parameter"><code>c</code></em> to upper case.
1710 If <em class="parameter"><code>c</code></em> is not an ASCII lower case letter,
1711 <em class="parameter"><code>c</code></em> is returned unchanged.</td>
1712 </tr>
1713 </tbody>
1714 </table></div>
1715 </div>
1716 <hr>
1717 <div class="refsect2">
1718 <a name="g-string-ascii-up"></a><h3>g_string_ascii_up ()</h3>
1719 <pre class="programlisting"><a class="link" href="glib-Strings.html#GString" title="struct GString"><span class="returnvalue">GString</span></a> *           g_string_ascii_up                   (<em class="parameter"><code><a class="link" href="glib-Strings.html#GString" title="struct GString"><span class="type">GString</span></a> *string</code></em>);</pre>
1720 <p>
1721 Converts all lowercase ASCII letters to uppercase ASCII letters.
1722 </p>
1723 <div class="variablelist"><table border="0">
1724 <col align="left" valign="top">
1725 <tbody>
1726 <tr>
1727 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
1728 <td>a GString</td>
1729 </tr>
1730 <tr>
1731 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1732 <td>passed-in <em class="parameter"><code>string</code></em> pointer, with all the
1733 lowercase characters converted to uppercase in place,
1734 with semantics that exactly match <a class="link" href="glib-String-Utility-Functions.html#g-ascii-toupper" title="g_ascii_toupper ()"><code class="function">g_ascii_toupper()</code></a>.</td>
1735 </tr>
1736 </tbody>
1737 </table></div>
1738 </div>
1739 <hr>
1740 <div class="refsect2">
1741 <a name="g-string-ascii-down"></a><h3>g_string_ascii_down ()</h3>
1742 <pre class="programlisting"><a class="link" href="glib-Strings.html#GString" title="struct GString"><span class="returnvalue">GString</span></a> *           g_string_ascii_down                 (<em class="parameter"><code><a class="link" href="glib-Strings.html#GString" title="struct GString"><span class="type">GString</span></a> *string</code></em>);</pre>
1743 <p>
1744 Converts all uppercase ASCII letters to lowercase ASCII letters.
1745 </p>
1746 <div class="variablelist"><table border="0">
1747 <col align="left" valign="top">
1748 <tbody>
1749 <tr>
1750 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
1751 <td>a GString</td>
1752 </tr>
1753 <tr>
1754 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1755 <td>passed-in <em class="parameter"><code>string</code></em> pointer, with all the
1756 uppercase characters converted to lowercase in place,
1757 with semantics that exactly match <a class="link" href="glib-String-Utility-Functions.html#g-ascii-tolower" title="g_ascii_tolower ()"><code class="function">g_ascii_tolower()</code></a>.</td>
1758 </tr>
1759 </tbody>
1760 </table></div>
1761 </div>
1762 <hr>
1763 <div class="refsect2">
1764 <a name="g-strup"></a><h3>g_strup ()</h3>
1765 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strup                             (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>);</pre>
1766 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
1767 <h3 class="title">Warning</h3>
1768 <p><code class="literal">g_strup</code> 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
1769 in the <a class="link" href="glib-String-Utility-Functions.html#g-strncasecmp" title="g_strncasecmp ()"><code class="function">g_strncasecmp()</code></a> docs - use <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strup" title="g_ascii_strup ()"><code class="function">g_ascii_strup()</code></a> or <a class="link" href="glib-Unicode-Manipulation.html#g-utf8-strup" title="g_utf8_strup ()"><code class="function">g_utf8_strup()</code></a> instead.</p>
1770 </div>
1771 <p>
1772 Converts a string to upper case.
1773 </p>
1774 <div class="variablelist"><table border="0">
1775 <col align="left" valign="top">
1776 <tbody>
1777 <tr>
1778 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
1779 <td>the string to convert.</td>
1780 </tr>
1781 <tr>
1782 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1783 <td>the string</td>
1784 </tr>
1785 </tbody>
1786 </table></div>
1787 </div>
1788 <hr>
1789 <div class="refsect2">
1790 <a name="g-strdown"></a><h3>g_strdown ()</h3>
1791 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strdown                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>);</pre>
1792 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
1793 <h3 class="title">Warning</h3>
1794 <p><code class="literal">g_strdown</code> 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
1795 in the <a class="link" href="glib-String-Utility-Functions.html#g-strncasecmp" title="g_strncasecmp ()"><code class="function">g_strncasecmp()</code></a> docs - use <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strdown" title="g_ascii_strdown ()"><code class="function">g_ascii_strdown()</code></a> or <a class="link" href="glib-Unicode-Manipulation.html#g-utf8-strdown" title="g_utf8_strdown ()"><code class="function">g_utf8_strdown()</code></a>
1796 instead.</p>
1797 </div>
1798 <p>
1799 Converts a string to lower case.
1800 </p>
1801 <div class="variablelist"><table border="0">
1802 <col align="left" valign="top">
1803 <tbody>
1804 <tr>
1805 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
1806 <td>the string to convert.</td>
1807 </tr>
1808 <tr>
1809 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1810 <td>the string</td>
1811 </tr>
1812 </tbody>
1813 </table></div>
1814 </div>
1815 <hr>
1816 <div class="refsect2">
1817 <a name="g-strcasecmp"></a><h3>g_strcasecmp ()</h3>
1818 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_strcasecmp                        (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s1</code></em>,
1819                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s2</code></em>);</pre>
1820 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
1821 <h3 class="title">Warning</h3>
1822 <p><code class="literal">g_strcasecmp</code> has been deprecated since version 2.2 and should not be used in newly-written code. See <a class="link" href="glib-String-Utility-Functions.html#g-strncasecmp" title="g_strncasecmp ()"><code class="function">g_strncasecmp()</code></a> for a discussion of why this function
1823   is deprecated and how to replace it.</p>
1824 </div>
1825 <p>
1826 A case-insensitive string comparison, corresponding to the standard
1827 <code class="function">strcasecmp()</code> function on platforms which support it.
1828 </p>
1829 <div class="variablelist"><table border="0">
1830 <col align="left" valign="top">
1831 <tbody>
1832 <tr>
1833 <td><p><span class="term"><em class="parameter"><code>s1</code></em> :</span></p></td>
1834 <td>a string.</td>
1835 </tr>
1836 <tr>
1837 <td><p><span class="term"><em class="parameter"><code>s2</code></em> :</span></p></td>
1838 <td>a string to compare with <em class="parameter"><code>s1</code></em>.</td>
1839 </tr>
1840 <tr>
1841 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1842 <td>0 if the strings match, a negative value if <em class="parameter"><code>s1</code></em> &lt; <em class="parameter"><code>s2</code></em>,
1843 or a positive value if <em class="parameter"><code>s1</code></em> &gt; <em class="parameter"><code>s2</code></em>.</td>
1844 </tr>
1845 </tbody>
1846 </table></div>
1847 </div>
1848 <hr>
1849 <div class="refsect2">
1850 <a name="g-strncasecmp"></a><h3>g_strncasecmp ()</h3>
1851 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_strncasecmp                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s1</code></em>,
1852                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *s2</code></em>,
1853                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> n</code></em>);</pre>
1854 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
1855 <h3 class="title">Warning</h3>
1856 <p><code class="literal">g_strncasecmp</code> has been deprecated since version 2.2 and should not be used in newly-written code. The problem with <a class="link" href="glib-String-Utility-Functions.html#g-strncasecmp" title="g_strncasecmp ()"><code class="function">g_strncasecmp()</code></a> is that it does the
1857 comparison by calling <code class="function">toupper()</code>/<code class="function">tolower()</code>. These functions are
1858 locale-specific and operate on single bytes. However, it is impossible
1859 to handle things correctly from an I18N standpoint by operating on
1860 bytes, since characters may be multibyte. Thus <a class="link" href="glib-String-Utility-Functions.html#g-strncasecmp" title="g_strncasecmp ()"><code class="function">g_strncasecmp()</code></a> is
1861 broken if your string is guaranteed to be ASCII, since it's
1862 locale-sensitive, and it's broken if your string is localized, since
1863 it doesn't work on many encodings at all, including UTF-8, EUC-JP,
1864 etc.
1865 </p>
1866 <p>
1867 There are therefore two replacement functions: <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strncasecmp" title="g_ascii_strncasecmp ()"><code class="function">g_ascii_strncasecmp()</code></a>,
1868 which only works on ASCII and is not locale-sensitive, and
1869 <a class="link" href="glib-Unicode-Manipulation.html#g-utf8-casefold" title="g_utf8_casefold ()"><code class="function">g_utf8_casefold()</code></a>, which is good for case-insensitive sorting of UTF-8.</p>
1870 </div>
1871 <p>
1872 A case-insensitive string comparison, corresponding to the standard
1873 <code class="function">strncasecmp()</code> function on platforms which support it.
1874 It is similar to <a class="link" href="glib-String-Utility-Functions.html#g-strcasecmp" title="g_strcasecmp ()"><code class="function">g_strcasecmp()</code></a> except it only compares the first <em class="parameter"><code>n</code></em>
1875 characters of the strings.
1876 </p>
1877 <div class="variablelist"><table border="0">
1878 <col align="left" valign="top">
1879 <tbody>
1880 <tr>
1881 <td><p><span class="term"><em class="parameter"><code>s1</code></em> :</span></p></td>
1882 <td>a string.</td>
1883 </tr>
1884 <tr>
1885 <td><p><span class="term"><em class="parameter"><code>s2</code></em> :</span></p></td>
1886 <td>a string to compare with <em class="parameter"><code>s1</code></em>.</td>
1887 </tr>
1888 <tr>
1889 <td><p><span class="term"><em class="parameter"><code>n</code></em> :</span></p></td>
1890 <td>the maximum number of characters to compare.</td>
1891 </tr>
1892 <tr>
1893 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1894 <td>0 if the strings match, a negative value if <em class="parameter"><code>s1</code></em> &lt; <em class="parameter"><code>s2</code></em>,
1895 or a positive value if <em class="parameter"><code>s1</code></em> &gt; <em class="parameter"><code>s2</code></em>.</td>
1896 </tr>
1897 </tbody>
1898 </table></div>
1899 </div>
1900 <hr>
1901 <div class="refsect2">
1902 <a name="g-strreverse"></a><h3>g_strreverse ()</h3>
1903 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strreverse                        (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>);</pre>
1904 <p>
1905 Reverses all of the bytes in a string. For example,
1906 <code class="literal">g_strreverse ("abcdef")</code> will result
1907 in "fedcba".
1908 </p>
1909 <p>
1910 Note that <a class="link" href="glib-String-Utility-Functions.html#g-strreverse" title="g_strreverse ()"><code class="function">g_strreverse()</code></a> doesn't work on UTF-8 strings
1911 containing multibyte characters. For that purpose, use
1912 <a class="link" href="glib-Unicode-Manipulation.html#g-utf8-strreverse" title="g_utf8_strreverse ()"><code class="function">g_utf8_strreverse()</code></a>.
1913 </p>
1914 <div class="variablelist"><table border="0">
1915 <col align="left" valign="top">
1916 <tbody>
1917 <tr>
1918 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
1919 <td>the string to reverse</td>
1920 </tr>
1921 <tr>
1922 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1923 <td>the same pointer passed in as <em class="parameter"><code>string</code></em>
1924 </td>
1925 </tr>
1926 </tbody>
1927 </table></div>
1928 </div>
1929 <hr>
1930 <div class="refsect2">
1931 <a name="g-ascii-strtoll"></a><h3>g_ascii_strtoll ()</h3>
1932 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint64" title="gint64"><span class="returnvalue">gint64</span></a>              g_ascii_strtoll                     (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *nptr</code></em>,
1933                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **endptr</code></em>,
1934                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> base</code></em>);</pre>
1935 <p>
1936 Converts a string to a <a class="link" href="glib-Basic-Types.html#gint64" title="gint64"><span class="type">gint64</span></a> value.
1937 This function behaves like the standard <code class="function">strtoll()</code> function
1938 does in the C locale. It does this without actually
1939 changing the current locale, since that would not be
1940 thread-safe.
1941 </p>
1942 <p>
1943 This function is typically used when reading configuration
1944 files or other non-user input that should be locale independent.
1945 To handle input from the user you should normally use the
1946 locale-sensitive system <code class="function">strtoll()</code> function.
1947 </p>
1948 <p>
1949 If the correct value would cause overflow, <a class="link" href="glib-Basic-Types.html#G-MAXINT64:CAPS" title="G_MAXINT64"><code class="literal">G_MAXINT64</code></a> or <a class="link" href="glib-Basic-Types.html#G-MININT64:CAPS" title="G_MININT64"><code class="literal">G_MININT64</code></a>
1950 is returned, and <code class="literal">ERANGE</code> is stored in <code class="literal">errno</code>.
1951 If the base is outside the valid range, zero is returned, and
1952 <code class="literal">EINVAL</code> is stored in <code class="literal">errno</code>. If the
1953 string conversion fails, zero is returned, and <em class="parameter"><code>endptr</code></em> returns <em class="parameter"><code>nptr</code></em>
1954 (if <em class="parameter"><code>endptr</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>).
1955 </p>
1956 <div class="variablelist"><table border="0">
1957 <col align="left" valign="top">
1958 <tbody>
1959 <tr>
1960 <td><p><span class="term"><em class="parameter"><code>nptr</code></em> :</span></p></td>
1961 <td>the string to convert to a numeric value.</td>
1962 </tr>
1963 <tr>
1964 <td><p><span class="term"><em class="parameter"><code>endptr</code></em> :</span></p></td>
1965 <td>if non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, it returns the character after
1966 the last character used in the conversion.</td>
1967 </tr>
1968 <tr>
1969 <td><p><span class="term"><em class="parameter"><code>base</code></em> :</span></p></td>
1970 <td>to be used for the conversion, 2..36 or 0</td>
1971 </tr>
1972 <tr>
1973 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1974 <td>the <a class="link" href="glib-Basic-Types.html#gint64" title="gint64"><span class="type">gint64</span></a> value or zero on error.</td>
1975 </tr>
1976 </tbody>
1977 </table></div>
1978 <p class="since">Since 2.12</p>
1979 </div>
1980 <hr>
1981 <div class="refsect2">
1982 <a name="g-ascii-strtoull"></a><h3>g_ascii_strtoull ()</h3>
1983 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="returnvalue">guint64</span></a>             g_ascii_strtoull                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *nptr</code></em>,
1984                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **endptr</code></em>,
1985                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> base</code></em>);</pre>
1986 <p>
1987 Converts a string to a <a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a> value.
1988 This function behaves like the standard <code class="function">strtoull()</code> function
1989 does in the C locale. It does this without actually
1990 changing the current locale, since that would not be
1991 thread-safe.
1992 </p>
1993 <p>
1994 This function is typically used when reading configuration
1995 files or other non-user input that should be locale independent.
1996 To handle input from the user you should normally use the
1997 locale-sensitive system <code class="function">strtoull()</code> function.
1998 </p>
1999 <p>
2000 If the correct value would cause overflow, <a class="link" href="glib-Basic-Types.html#G-MAXUINT64:CAPS" title="G_MAXUINT64"><code class="literal">G_MAXUINT64</code></a>
2001 is returned, and <code class="literal">ERANGE</code> is stored in <code class="literal">errno</code>.
2002 If the base is outside the valid range, zero is returned, and
2003 <code class="literal">EINVAL</code> is stored in <code class="literal">errno</code>.
2004 If the string conversion fails, zero is returned, and <em class="parameter"><code>endptr</code></em> returns
2005 <em class="parameter"><code>nptr</code></em> (if <em class="parameter"><code>endptr</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>).
2006 </p>
2007 <div class="variablelist"><table border="0">
2008 <col align="left" valign="top">
2009 <tbody>
2010 <tr>
2011 <td><p><span class="term"><em class="parameter"><code>nptr</code></em> :</span></p></td>
2012 <td>the string to convert to a numeric value.</td>
2013 </tr>
2014 <tr>
2015 <td><p><span class="term"><em class="parameter"><code>endptr</code></em> :</span></p></td>
2016 <td>if non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, it returns the character after
2017 the last character used in the conversion.</td>
2018 </tr>
2019 <tr>
2020 <td><p><span class="term"><em class="parameter"><code>base</code></em> :</span></p></td>
2021 <td>to be used for the conversion, 2..36 or 0</td>
2022 </tr>
2023 <tr>
2024 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2025 <td>the <a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a> value or zero on error.</td>
2026 </tr>
2027 </tbody>
2028 </table></div>
2029 <p class="since">Since 2.2</p>
2030 </div>
2031 <hr>
2032 <div class="refsect2">
2033 <a name="G-ASCII-DTOSTR-BUF-SIZE:CAPS"></a><h3>G_ASCII_DTOSTR_BUF_SIZE</h3>
2034 <pre class="programlisting">#define G_ASCII_DTOSTR_BUF_SIZE (29 + 10)
2035 </pre>
2036 <p>
2037 A good size for a buffer to be passed into <a class="link" href="glib-String-Utility-Functions.html#g-ascii-dtostr" title="g_ascii_dtostr ()"><code class="function">g_ascii_dtostr()</code></a>.
2038 It is guaranteed to be enough for all output of that function
2039 on systems with 64bit IEEE-compatible doubles.
2040 </p>
2041 <p>
2042 The typical usage would be something like:
2043 </p>
2044 <div class="informalexample">
2045   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
2046     <tbody>
2047       <tr>
2048         <td class="listing_lines" align="right"><pre>1
2049 2
2050 3</pre></td>
2051         <td class="listing_code"><pre class="programlisting"><span class="type">char</span><span class="normal"> buf</span><span class="symbol">[</span><span class="normal"><a href="glib-String-Utility-Functions.html#G-ASCII-DTOSTR-BUF-SIZE:CAPS">G_ASCII_DTOSTR_BUF_SIZE</a></span><span class="symbol">];</span>
2052
2053 <span class="function">fprintf</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">out</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"value=%s</span><span class="specialchar">\n</span><span class="string">"</span><span class="symbol">,</span><span class="normal"> </span><span class="function"><a href="glib-String-Utility-Functions.html#g-ascii-dtostr">g_ascii_dtostr</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">buf</span><span class="symbol">,</span><span class="normal"> </span><span class="keyword">sizeof</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">buf</span><span class="symbol">),</span><span class="normal"> value</span><span class="symbol">));</span></pre></td>
2054       </tr>
2055     </tbody>
2056   </table>
2057 </div>
2058
2059 <p>
2060 </p>
2061 </div>
2062 <hr>
2063 <div class="refsect2">
2064 <a name="g-ascii-strtod"></a><h3>g_ascii_strtod ()</h3>
2065 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="returnvalue">gdouble</span></a>             g_ascii_strtod                      (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *nptr</code></em>,
2066                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **endptr</code></em>);</pre>
2067 <p>
2068 Converts a string to a <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> value.
2069 </p>
2070 <p>
2071 This function behaves like the standard <code class="function">strtod()</code> function
2072 does in the C locale. It does this without actually changing
2073 the current locale, since that would not be thread-safe.
2074 A limitation of the implementation is that this function
2075 will still accept localized versions of infinities and NANs.
2076 </p>
2077 <p>
2078 This function is typically used when reading configuration
2079 files or other non-user input that should be locale independent.
2080 To handle input from the user you should normally use the
2081 locale-sensitive system <code class="function">strtod()</code> function.
2082 </p>
2083 <p>
2084 To convert from a <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> to a string in a locale-insensitive
2085 way, use <a class="link" href="glib-String-Utility-Functions.html#g-ascii-dtostr" title="g_ascii_dtostr ()"><code class="function">g_ascii_dtostr()</code></a>.
2086 </p>
2087 <p>
2088 If the correct value would cause overflow, plus or minus <code class="literal">HUGE_VAL</code>
2089 is returned (according to the sign of the value), and <code class="literal">ERANGE</code> is
2090 stored in <code class="literal">errno</code>. If the correct value would cause underflow,
2091 zero is returned and <code class="literal">ERANGE</code> is stored in <code class="literal">errno</code>.
2092 </p>
2093 <p>
2094 This function resets <code class="literal">errno</code> before calling <code class="function">strtod()</code> so that
2095 you can reliably detect overflow and underflow.
2096 </p>
2097 <div class="variablelist"><table border="0">
2098 <col align="left" valign="top">
2099 <tbody>
2100 <tr>
2101 <td><p><span class="term"><em class="parameter"><code>nptr</code></em> :</span></p></td>
2102 <td>the string to convert to a numeric value.</td>
2103 </tr>
2104 <tr>
2105 <td><p><span class="term"><em class="parameter"><code>endptr</code></em> :</span></p></td>
2106 <td>if non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, it returns the character after
2107 the last character used in the conversion.</td>
2108 </tr>
2109 <tr>
2110 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2111 <td>the <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> value.</td>
2112 </tr>
2113 </tbody>
2114 </table></div>
2115 </div>
2116 <hr>
2117 <div class="refsect2">
2118 <a name="g-ascii-dtostr"></a><h3>g_ascii_dtostr ()</h3>
2119 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_ascii_dtostr                      (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *buffer</code></em>,
2120                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> buf_len</code></em>,
2121                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> d</code></em>);</pre>
2122 <p>
2123 Converts a <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> to a string, using the '.' as
2124 decimal point.
2125 </p>
2126 <p>
2127 This functions generates enough precision that converting
2128 the string back using <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strtod" title="g_ascii_strtod ()"><code class="function">g_ascii_strtod()</code></a> gives the same machine-number
2129 (on machines with IEEE compatible 64bit doubles). It is
2130 guaranteed that the size of the resulting string will never
2131 be larger than <em class="parameter"><code>G_ASCII_DTOSTR_BUF_SIZE</code></em> bytes.
2132 </p>
2133 <div class="variablelist"><table border="0">
2134 <col align="left" valign="top">
2135 <tbody>
2136 <tr>
2137 <td><p><span class="term"><em class="parameter"><code>buffer</code></em> :</span></p></td>
2138 <td>A buffer to place the resulting string in</td>
2139 </tr>
2140 <tr>
2141 <td><p><span class="term"><em class="parameter"><code>buf_len</code></em> :</span></p></td>
2142 <td>The length of the buffer.</td>
2143 </tr>
2144 <tr>
2145 <td><p><span class="term"><em class="parameter"><code>d</code></em> :</span></p></td>
2146 <td>The <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> to convert</td>
2147 </tr>
2148 <tr>
2149 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2150 <td>The pointer to the buffer with the converted string.</td>
2151 </tr>
2152 </tbody>
2153 </table></div>
2154 </div>
2155 <hr>
2156 <div class="refsect2">
2157 <a name="g-ascii-formatd"></a><h3>g_ascii_formatd ()</h3>
2158 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_ascii_formatd                     (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *buffer</code></em>,
2159                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> buf_len</code></em>,
2160                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
2161                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> d</code></em>);</pre>
2162 <p>
2163 Converts a <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> to a string, using the '.' as
2164 decimal point. To format the number you pass in
2165 a <code class="function">printf()</code>-style format string. Allowed conversion
2166 specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
2167 </p>
2168 <p>
2169 If you just want to want to serialize the value into a
2170 string, use <a class="link" href="glib-String-Utility-Functions.html#g-ascii-dtostr" title="g_ascii_dtostr ()"><code class="function">g_ascii_dtostr()</code></a>.
2171 </p>
2172 <div class="variablelist"><table border="0">
2173 <col align="left" valign="top">
2174 <tbody>
2175 <tr>
2176 <td><p><span class="term"><em class="parameter"><code>buffer</code></em> :</span></p></td>
2177 <td>A buffer to place the resulting string in</td>
2178 </tr>
2179 <tr>
2180 <td><p><span class="term"><em class="parameter"><code>buf_len</code></em> :</span></p></td>
2181 <td>The length of the buffer.</td>
2182 </tr>
2183 <tr>
2184 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
2185 <td>The <code class="function">printf()</code>-style format to use for the
2186 code to use for converting.</td>
2187 </tr>
2188 <tr>
2189 <td><p><span class="term"><em class="parameter"><code>d</code></em> :</span></p></td>
2190 <td>The <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> to convert</td>
2191 </tr>
2192 <tr>
2193 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2194 <td>The pointer to the buffer with the converted string.</td>
2195 </tr>
2196 </tbody>
2197 </table></div>
2198 </div>
2199 <hr>
2200 <div class="refsect2">
2201 <a name="g-strtod"></a><h3>g_strtod ()</h3>
2202 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="returnvalue">gdouble</span></a>             g_strtod                            (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *nptr</code></em>,
2203                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **endptr</code></em>);</pre>
2204 <p>
2205 Converts a string to a <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> value.
2206 It calls the standard <code class="function">strtod()</code> function to handle the conversion, but
2207 if the string is not completely converted it attempts the conversion
2208 again with <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strtod" title="g_ascii_strtod ()"><code class="function">g_ascii_strtod()</code></a>, and returns the best match.
2209 </p>
2210 <p>
2211 This function should seldom be used. The normal situation when reading
2212 numbers not for human consumption is to use <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strtod" title="g_ascii_strtod ()"><code class="function">g_ascii_strtod()</code></a>. Only when
2213 you know that you must expect both locale formatted and C formatted numbers
2214 should you use this. Make sure that you don't pass strings such as comma
2215 separated lists of values, since the commas may be interpreted as a decimal
2216 point in some locales, causing unexpected results.
2217 </p>
2218 <div class="variablelist"><table border="0">
2219 <col align="left" valign="top">
2220 <tbody>
2221 <tr>
2222 <td><p><span class="term"><em class="parameter"><code>nptr</code></em> :</span></p></td>
2223 <td>the string to convert to a numeric value.</td>
2224 </tr>
2225 <tr>
2226 <td><p><span class="term"><em class="parameter"><code>endptr</code></em> :</span></p></td>
2227 <td>if non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, it returns the character after
2228 the last character used in the conversion.</td>
2229 </tr>
2230 <tr>
2231 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2232 <td>the <a class="link" href="glib-Basic-Types.html#gdouble" title="gdouble"><span class="type">gdouble</span></a> value.</td>
2233 </tr>
2234 </tbody>
2235 </table></div>
2236 </div>
2237 <hr>
2238 <div class="refsect2">
2239 <a name="g-strchug"></a><h3>g_strchug ()</h3>
2240 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strchug                           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>);</pre>
2241 <p>
2242 Removes leading whitespace from a string, by moving the rest
2243 of the characters forward.
2244 </p>
2245 <p>
2246 This function doesn't allocate or reallocate any memory;
2247 it modifies <em class="parameter"><code>string</code></em> in place. The pointer to <em class="parameter"><code>string</code></em> is
2248 returned to allow the nesting of functions.
2249 </p>
2250 <p>
2251 Also see <a class="link" href="glib-String-Utility-Functions.html#g-strchomp" title="g_strchomp ()"><code class="function">g_strchomp()</code></a> and <a class="link" href="glib-String-Utility-Functions.html#g-strstrip" title="g_strstrip()"><code class="function">g_strstrip()</code></a>.
2252 </p>
2253 <div class="variablelist"><table border="0">
2254 <col align="left" valign="top">
2255 <tbody>
2256 <tr>
2257 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
2258 <td>a string to remove the leading whitespace from</td>
2259 </tr>
2260 <tr>
2261 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2262 <td><em class="parameter"><code>string</code></em></td>
2263 </tr>
2264 </tbody>
2265 </table></div>
2266 </div>
2267 <hr>
2268 <div class="refsect2">
2269 <a name="g-strchomp"></a><h3>g_strchomp ()</h3>
2270 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strchomp                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>);</pre>
2271 <p>
2272 Removes trailing whitespace from a string.
2273 </p>
2274 <p>
2275 This function doesn't allocate or reallocate any memory;
2276 it modifies <em class="parameter"><code>string</code></em> in place. The pointer to <em class="parameter"><code>string</code></em> is
2277 returned to allow the nesting of functions.
2278 </p>
2279 <p>
2280 Also see <a class="link" href="glib-String-Utility-Functions.html#g-strchug" title="g_strchug ()"><code class="function">g_strchug()</code></a> and <a class="link" href="glib-String-Utility-Functions.html#g-strstrip" title="g_strstrip()"><code class="function">g_strstrip()</code></a>.
2281 </p>
2282 <div class="variablelist"><table border="0">
2283 <col align="left" valign="top">
2284 <tbody>
2285 <tr>
2286 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
2287 <td>a string to remove the trailing whitespace from</td>
2288 </tr>
2289 <tr>
2290 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2291 <td>
2292 <em class="parameter"><code>string</code></em>.</td>
2293 </tr>
2294 </tbody>
2295 </table></div>
2296 </div>
2297 <hr>
2298 <div class="refsect2">
2299 <a name="g-strstrip"></a><h3>g_strstrip()</h3>
2300 <pre class="programlisting">#define             g_strstrip( string )</pre>
2301 <p>
2302 Removes leading and trailing whitespace from a string.
2303 See <a class="link" href="glib-String-Utility-Functions.html#g-strchomp" title="g_strchomp ()"><code class="function">g_strchomp()</code></a> and <a class="link" href="glib-String-Utility-Functions.html#g-strchug" title="g_strchug ()"><code class="function">g_strchug()</code></a>.
2304 </p>
2305 <div class="variablelist"><table border="0">
2306 <col align="left" valign="top">
2307 <tbody>
2308 <tr>
2309 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
2310 <td>a string to remove the leading and trailing whitespace from</td>
2311 </tr>
2312 <tr>
2313 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2314 <td><em class="parameter"><code>string</code></em></td>
2315 </tr>
2316 </tbody>
2317 </table></div>
2318 </div>
2319 <hr>
2320 <div class="refsect2">
2321 <a name="g-strdelimit"></a><h3>g_strdelimit ()</h3>
2322 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strdelimit                        (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
2323                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *delimiters</code></em>,
2324                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> new_delimiter</code></em>);</pre>
2325 <p>
2326 Converts any delimiter characters in <em class="parameter"><code>string</code></em> to <em class="parameter"><code>new_delimiter</code></em>.
2327 Any characters in <em class="parameter"><code>string</code></em> which are found in <em class="parameter"><code>delimiters</code></em> are
2328 changed to the <em class="parameter"><code>new_delimiter</code></em> character. Modifies <em class="parameter"><code>string</code></em> in place,
2329 and returns <em class="parameter"><code>string</code></em> itself, not a copy. The return value is to
2330 allow nesting such as
2331 </p>
2332 <div class="informalexample">
2333   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
2334     <tbody>
2335       <tr>
2336         <td class="listing_lines" align="right"><pre>1</pre></td>
2337         <td class="listing_code"><pre class="programlisting"><span class="function"><a href="glib-String-Utility-Functions.html#g-ascii-strup">g_ascii_strup</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="glib-String-Utility-Functions.html#g-strdelimit">g_strdelimit</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">str</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"abc"</span><span class="symbol">,</span><span class="normal"> </span><span class="string">'?'</span><span class="symbol">))</span></pre></td>
2338       </tr>
2339     </tbody>
2340   </table>
2341 </div>
2342
2343 <p>
2344 </p>
2345 <div class="variablelist"><table border="0">
2346 <col align="left" valign="top">
2347 <tbody>
2348 <tr>
2349 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
2350 <td>the string to convert</td>
2351 </tr>
2352 <tr>
2353 <td><p><span class="term"><em class="parameter"><code>delimiters</code></em> :</span></p></td>
2354 <td>a string containing the current delimiters, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
2355 to use the standard delimiters defined in <a class="link" href="glib-String-Utility-Functions.html#G-STR-DELIMITERS:CAPS" title="G_STR_DELIMITERS"><span class="type">G_STR_DELIMITERS</span></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
2356 </td>
2357 </tr>
2358 <tr>
2359 <td><p><span class="term"><em class="parameter"><code>new_delimiter</code></em> :</span></p></td>
2360 <td>the new delimiter character</td>
2361 </tr>
2362 <tr>
2363 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2364 <td><em class="parameter"><code>string</code></em></td>
2365 </tr>
2366 </tbody>
2367 </table></div>
2368 </div>
2369 <hr>
2370 <div class="refsect2">
2371 <a name="G-STR-DELIMITERS:CAPS"></a><h3>G_STR_DELIMITERS</h3>
2372 <pre class="programlisting">#define      G_STR_DELIMITERS "_-|&gt; &lt;."
2373 </pre>
2374 <p>
2375 The standard delimiters, used in <a class="link" href="glib-String-Utility-Functions.html#g-strdelimit" title="g_strdelimit ()"><code class="function">g_strdelimit()</code></a>.
2376 </p>
2377 </div>
2378 <hr>
2379 <div class="refsect2">
2380 <a name="g-strescape"></a><h3>g_strescape ()</h3>
2381 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strescape                         (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *source</code></em>,
2382                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *exceptions</code></em>);</pre>
2383 <p>
2384 Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
2385 and '"' in the string <em class="parameter"><code>source</code></em> by inserting a '\' before
2386 them. Additionally all characters in the range 0x01-0x1F (everything
2387 below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
2388 replaced with a '\' followed by their octal representation.
2389 Characters supplied in <em class="parameter"><code>exceptions</code></em> are not escaped.
2390 </p>
2391 <p>
2392 <a class="link" href="glib-String-Utility-Functions.html#g-strcompress" title="g_strcompress ()"><code class="function">g_strcompress()</code></a> does the reverse conversion.
2393 </p>
2394 <div class="variablelist"><table border="0">
2395 <col align="left" valign="top">
2396 <tbody>
2397 <tr>
2398 <td><p><span class="term"><em class="parameter"><code>source</code></em> :</span></p></td>
2399 <td>a string to escape</td>
2400 </tr>
2401 <tr>
2402 <td><p><span class="term"><em class="parameter"><code>exceptions</code></em> :</span></p></td>
2403 <td>a string of characters not to escape in <em class="parameter"><code>source</code></em>
2404 </td>
2405 </tr>
2406 <tr>
2407 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2408 <td>a newly-allocated copy of <em class="parameter"><code>source</code></em> with certain
2409 characters escaped. See above.</td>
2410 </tr>
2411 </tbody>
2412 </table></div>
2413 </div>
2414 <hr>
2415 <div class="refsect2">
2416 <a name="g-strcompress"></a><h3>g_strcompress ()</h3>
2417 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strcompress                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *source</code></em>);</pre>
2418 <p>
2419 Replaces all escaped characters with their one byte equivalent.
2420 </p>
2421 <p>
2422 This function does the reverse conversion of <a class="link" href="glib-String-Utility-Functions.html#g-strescape" title="g_strescape ()"><code class="function">g_strescape()</code></a>.
2423 </p>
2424 <div class="variablelist"><table border="0">
2425 <col align="left" valign="top">
2426 <tbody>
2427 <tr>
2428 <td><p><span class="term"><em class="parameter"><code>source</code></em> :</span></p></td>
2429 <td>a string to compress</td>
2430 </tr>
2431 <tr>
2432 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2433 <td>a newly-allocated copy of <em class="parameter"><code>source</code></em> with all escaped
2434 character compressed</td>
2435 </tr>
2436 </tbody>
2437 </table></div>
2438 </div>
2439 <hr>
2440 <div class="refsect2">
2441 <a name="g-strcanon"></a><h3>g_strcanon ()</h3>
2442 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strcanon                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
2443                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *valid_chars</code></em>,
2444                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> substitutor</code></em>);</pre>
2445 <p>
2446 For each character in <em class="parameter"><code>string</code></em>, if the character is not in
2447 <em class="parameter"><code>valid_chars</code></em>, replaces the character with <em class="parameter"><code>substitutor</code></em>.
2448 Modifies <em class="parameter"><code>string</code></em> in place, and return <em class="parameter"><code>string</code></em> itself, not
2449 a copy. The return value is to allow nesting such as
2450 </p>
2451 <div class="informalexample">
2452   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
2453     <tbody>
2454       <tr>
2455         <td class="listing_lines" align="right"><pre>1</pre></td>
2456         <td class="listing_code"><pre class="programlisting"><span class="function"><a href="glib-String-Utility-Functions.html#g-ascii-strup">g_ascii_strup</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="glib-String-Utility-Functions.html#g-strcanon">g_strcanon</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">str</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"abc"</span><span class="symbol">,</span><span class="normal"> </span><span class="string">'?'</span><span class="symbol">))</span></pre></td>
2457       </tr>
2458     </tbody>
2459   </table>
2460 </div>
2461
2462 <p>
2463 </p>
2464 <div class="variablelist"><table border="0">
2465 <col align="left" valign="top">
2466 <tbody>
2467 <tr>
2468 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
2469 <td>a nul-terminated array of bytes</td>
2470 </tr>
2471 <tr>
2472 <td><p><span class="term"><em class="parameter"><code>valid_chars</code></em> :</span></p></td>
2473 <td>bytes permitted in <em class="parameter"><code>string</code></em>
2474 </td>
2475 </tr>
2476 <tr>
2477 <td><p><span class="term"><em class="parameter"><code>substitutor</code></em> :</span></p></td>
2478 <td>replacement character for disallowed bytes</td>
2479 </tr>
2480 <tr>
2481 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2482 <td><em class="parameter"><code>string</code></em></td>
2483 </tr>
2484 </tbody>
2485 </table></div>
2486 </div>
2487 <hr>
2488 <div class="refsect2">
2489 <a name="g-strsplit"></a><h3>g_strsplit ()</h3>
2490 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            g_strsplit                          (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
2491                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *delimiter</code></em>,
2492                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> max_tokens</code></em>);</pre>
2493 <p>
2494 Splits a string into a maximum of <em class="parameter"><code>max_tokens</code></em> pieces, using the given
2495 <em class="parameter"><code>delimiter</code></em>. If <em class="parameter"><code>max_tokens</code></em> is reached, the remainder of <em class="parameter"><code>string</code></em> is
2496 appended to the last token.
2497 </p>
2498 <p>
2499 As a special case, the result of splitting the empty string "" is an empty
2500 vector, not a vector containing a single string. The reason for this
2501 special case is that being able to represent a empty vector is typically
2502 more useful than consistent handling of empty elements. If you do need
2503 to represent empty elements, you'll need to check for the empty string
2504 before calling <a class="link" href="glib-String-Utility-Functions.html#g-strsplit" title="g_strsplit ()"><code class="function">g_strsplit()</code></a>.
2505 </p>
2506 <div class="variablelist"><table border="0">
2507 <col align="left" valign="top">
2508 <tbody>
2509 <tr>
2510 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
2511 <td>a string to split</td>
2512 </tr>
2513 <tr>
2514 <td><p><span class="term"><em class="parameter"><code>delimiter</code></em> :</span></p></td>
2515 <td>a string which specifies the places at which to split
2516 the string. The delimiter is not included in any of the resulting
2517 strings, unless <em class="parameter"><code>max_tokens</code></em> is reached.</td>
2518 </tr>
2519 <tr>
2520 <td><p><span class="term"><em class="parameter"><code>max_tokens</code></em> :</span></p></td>
2521 <td>the maximum number of pieces to split <em class="parameter"><code>string</code></em> into.
2522 If this is less than 1, the string is split completely.</td>
2523 </tr>
2524 <tr>
2525 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2526 <td>a newly-allocated <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings. Use
2527 <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a> to free it.</td>
2528 </tr>
2529 </tbody>
2530 </table></div>
2531 </div>
2532 <hr>
2533 <div class="refsect2">
2534 <a name="g-strsplit-set"></a><h3>g_strsplit_set ()</h3>
2535 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            g_strsplit_set                      (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
2536                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *delimiters</code></em>,
2537                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> max_tokens</code></em>);</pre>
2538 <p>
2539 Splits <em class="parameter"><code>string</code></em> into a number of tokens not containing any of the characters
2540 in <em class="parameter"><code>delimiter</code></em>. A token is the (possibly empty) longest string that does not
2541 contain any of the characters in <em class="parameter"><code>delimiters</code></em>. If <em class="parameter"><code>max_tokens</code></em> is reached, the
2542 remainder is appended to the last token.
2543 </p>
2544 <p>
2545 For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
2546 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated vector containing the three strings "abc", "def",
2547 and "ghi".
2548 </p>
2549 <p>
2550 The result if g_strsplit_set (":def/ghi:", ":/", -1) is a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated
2551 vector containing the four strings "", "def", "ghi", and "".
2552 </p>
2553 <p>
2554 As a special case, the result of splitting the empty string "" is an empty
2555 vector, not a vector containing a single string. The reason for this
2556 special case is that being able to represent a empty vector is typically
2557 more useful than consistent handling of empty elements. If you do need
2558 to represent empty elements, you'll need to check for the empty string
2559 before calling <a class="link" href="glib-String-Utility-Functions.html#g-strsplit-set" title="g_strsplit_set ()"><code class="function">g_strsplit_set()</code></a>.
2560 </p>
2561 <p>
2562 Note that this function works on bytes not characters, so it can't be used
2563 to delimit UTF-8 strings for anything but ASCII characters.
2564 </p>
2565 <div class="variablelist"><table border="0">
2566 <col align="left" valign="top">
2567 <tbody>
2568 <tr>
2569 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
2570 <td>The string to be tokenized</td>
2571 </tr>
2572 <tr>
2573 <td><p><span class="term"><em class="parameter"><code>delimiters</code></em> :</span></p></td>
2574 <td>A nul-terminated string containing bytes that are used
2575 to split the string.</td>
2576 </tr>
2577 <tr>
2578 <td><p><span class="term"><em class="parameter"><code>max_tokens</code></em> :</span></p></td>
2579 <td>The maximum number of tokens to split <em class="parameter"><code>string</code></em> into.
2580 If this is less than 1, the string is split completely</td>
2581 </tr>
2582 <tr>
2583 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2584 <td>a newly-allocated <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings. Use
2585 <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a> to free it.</td>
2586 </tr>
2587 </tbody>
2588 </table></div>
2589 <p class="since">Since 2.4</p>
2590 </div>
2591 <hr>
2592 <div class="refsect2">
2593 <a name="g-strfreev"></a><h3>g_strfreev ()</h3>
2594 <pre class="programlisting"><span class="returnvalue">void</span>                g_strfreev                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **str_array</code></em>);</pre>
2595 <p>
2596 Frees a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings, and the array itself.
2597 If called on a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> value, <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a> simply returns.
2598 </p>
2599 <div class="variablelist"><table border="0">
2600 <col align="left" valign="top">
2601 <tbody><tr>
2602 <td><p><span class="term"><em class="parameter"><code>str_array</code></em> :</span></p></td>
2603 <td>a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings to free</td>
2604 </tr></tbody>
2605 </table></div>
2606 </div>
2607 <hr>
2608 <div class="refsect2">
2609 <a name="g-strconcat"></a><h3>g_strconcat ()</h3>
2610 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strconcat                         (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string1</code></em>,
2611                                                          <em class="parameter"><code>...</code></em>);</pre>
2612 <p>
2613 Concatenates all of the given strings into one long string.
2614 The returned string should be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a> when no longer needed.
2615 </p>
2616 <p>
2617 Note that this function is usually not the right function to use to
2618 assemble a translated message from pieces, since proper translation
2619 often requires the pieces to be reordered.
2620 </p>
2621 <p>
2622 </p>
2623 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
2624 <h3 class="title">Warning</h3>
2625 <p>The variable argument list <span class="emphasis"><em>must</em></span> end
2626 with <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. If you forget the <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, <a class="link" href="glib-String-Utility-Functions.html#g-strconcat" title="g_strconcat ()"><code class="function">g_strconcat()</code></a> will start appending
2627 random memory junk to your string.</p>
2628 </div>
2629 <p>
2630 </p>
2631 <div class="variablelist"><table border="0">
2632 <col align="left" valign="top">
2633 <tbody>
2634 <tr>
2635 <td><p><span class="term"><em class="parameter"><code>string1</code></em> :</span></p></td>
2636 <td>the first string to add, which must not be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
2637 </td>
2638 </tr>
2639 <tr>
2640 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
2641 <td>a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated list of strings to append to the string</td>
2642 </tr>
2643 <tr>
2644 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2645 <td>a newly-allocated string containing all the string arguments</td>
2646 </tr>
2647 </tbody>
2648 </table></div>
2649 </div>
2650 <hr>
2651 <div class="refsect2">
2652 <a name="g-strjoin"></a><h3>g_strjoin ()</h3>
2653 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strjoin                           (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *separator</code></em>,
2654                                                          <em class="parameter"><code>...</code></em>);</pre>
2655 <p>
2656 Joins a number of strings together to form one long string, with the
2657 optional <em class="parameter"><code>separator</code></em> inserted between each of them. The returned string
2658 should be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>.
2659 </p>
2660 <div class="variablelist"><table border="0">
2661 <col align="left" valign="top">
2662 <tbody>
2663 <tr>
2664 <td><p><span class="term"><em class="parameter"><code>separator</code></em> :</span></p></td>
2665 <td>a string to insert between each of the strings, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
2666 </td>
2667 </tr>
2668 <tr>
2669 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
2670 <td>a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated list of strings to join</td>
2671 </tr>
2672 <tr>
2673 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2674 <td>a newly-allocated string containing all of the strings joined
2675 together, with <em class="parameter"><code>separator</code></em> between them</td>
2676 </tr>
2677 </tbody>
2678 </table></div>
2679 </div>
2680 <hr>
2681 <div class="refsect2">
2682 <a name="g-strjoinv"></a><h3>g_strjoinv ()</h3>
2683 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_strjoinv                          (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *separator</code></em>,
2684                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **str_array</code></em>);</pre>
2685 <p>
2686 Joins a number of strings together to form one long string, with the
2687 optional <em class="parameter"><code>separator</code></em> inserted between each of them. The returned string
2688 should be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>.
2689 </p>
2690 <div class="variablelist"><table border="0">
2691 <col align="left" valign="top">
2692 <tbody>
2693 <tr>
2694 <td><p><span class="term"><em class="parameter"><code>separator</code></em> :</span></p></td>
2695 <td>a string to insert between each of the strings, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
2696 </td>
2697 </tr>
2698 <tr>
2699 <td><p><span class="term"><em class="parameter"><code>str_array</code></em> :</span></p></td>
2700 <td>a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings to join</td>
2701 </tr>
2702 <tr>
2703 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2704 <td>a newly-allocated string containing all of the strings joined
2705 together, with <em class="parameter"><code>separator</code></em> between them</td>
2706 </tr>
2707 </tbody>
2708 </table></div>
2709 </div>
2710 <hr>
2711 <div class="refsect2">
2712 <a name="g-strv-length"></a><h3>g_strv_length ()</h3>
2713 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               g_strv_length                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **str_array</code></em>);</pre>
2714 <p>
2715 Returns the length of the given <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated
2716 string array <em class="parameter"><code>str_array</code></em>.
2717 </p>
2718 <div class="variablelist"><table border="0">
2719 <col align="left" valign="top">
2720 <tbody>
2721 <tr>
2722 <td><p><span class="term"><em class="parameter"><code>str_array</code></em> :</span></p></td>
2723 <td>a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings</td>
2724 </tr>
2725 <tr>
2726 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2727 <td>length of <em class="parameter"><code>str_array</code></em>.</td>
2728 </tr>
2729 </tbody>
2730 </table></div>
2731 <p class="since">Since 2.6</p>
2732 </div>
2733 <hr>
2734 <div class="refsect2">
2735 <a name="g-strerror"></a><h3>g_strerror ()</h3>
2736 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_strerror                          (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> errnum</code></em>);</pre>
2737 <p>
2738 Returns a string corresponding to the given error code, e.g.
2739 "no such process". You should use this function in preference to
2740 <code class="function">strerror()</code>, because it returns a string in UTF-8 encoding, and since
2741 not all platforms support the <code class="function">strerror()</code> function.
2742 </p>
2743 <div class="variablelist"><table border="0">
2744 <col align="left" valign="top">
2745 <tbody>
2746 <tr>
2747 <td><p><span class="term"><em class="parameter"><code>errnum</code></em> :</span></p></td>
2748 <td>the system error number. See the standard C <code class="literal">errno</code>
2749 documentation</td>
2750 </tr>
2751 <tr>
2752 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2753 <td>a UTF-8 string describing the error code. If the error code
2754 is unknown, it returns "unknown error (&lt;code&gt;)".</td>
2755 </tr>
2756 </tbody>
2757 </table></div>
2758 </div>
2759 <hr>
2760 <div class="refsect2">
2761 <a name="g-strsignal"></a><h3>g_strsignal ()</h3>
2762 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_strsignal                         (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> signum</code></em>);</pre>
2763 <p>
2764 Returns a string describing the given signal, e.g. "Segmentation fault".
2765 You should use this function in preference to <code class="function">strsignal()</code>, because it
2766 returns a string in UTF-8 encoding, and since not all platforms support
2767 the <code class="function">strsignal()</code> function.
2768 </p>
2769 <div class="variablelist"><table border="0">
2770 <col align="left" valign="top">
2771 <tbody>
2772 <tr>
2773 <td><p><span class="term"><em class="parameter"><code>signum</code></em> :</span></p></td>
2774 <td>the signal number. See the <code class="literal">signal</code>
2775 documentation</td>
2776 </tr>
2777 <tr>
2778 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
2779 <td>a UTF-8 string describing the signal. If the signal is unknown,
2780 it returns "unknown signal (&lt;signum&gt;)".</td>
2781 </tr>
2782 </tbody>
2783 </table></div>
2784 </div>
2785 </div>
2786 </div>
2787 <div class="footer">
2788 <hr>
2789           Generated by GTK-Doc V1.18</div>
2790 </body>
2791 </html>