1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>String Utility Functions</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="exo Reference Manual">
<link rel="up" href="exo-miscelleanous.html" title="Part VI. Miscelleanous">
<link rel="prev" href="exo-Mount-Points.html" title="Mount Points">
<link rel="next" href="exo-Opening-URLs.html" title="Opening URLs">
<meta name="generator" content="GTK-Doc V1.14 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="exo-Mount-Points.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="exo-miscelleanous.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">exo Reference Manual</th>
<td><a accesskey="n" href="exo-Opening-URLs.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#exo-String-Utility-Functions.synopsis" class="shortcut">Top</a>
|
<a href="#exo-String-Utility-Functions.description" class="shortcut">Description</a>
</td></tr>
</table>
<div class="refentry" title="String Utility Functions">
<a name="exo-String-Utility-Functions"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="exo-String-Utility-Functions.top_of_page"></a>String Utility Functions</span></h2>
<p>String Utility Functions — Various string-related functions</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1" title="Stability Level">
<a name="exo-String-Utility-Functions.stability-level"></a><h2>Stability Level</h2>
Stable, unless otherwise indicated
</div>
<div class="refsynopsisdiv" title="Synopsis">
<a name="exo-String-Utility-Functions.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis">
#include <exo/exo.h>
<span class="returnvalue">gchar</span> * <a class="link" href="exo-String-Utility-Functions.html#exo-str-elide-underscores" title="exo_str_elide_underscores ()">exo_str_elide_underscores</a> (<em class="parameter"><code>const <span class="type">gchar</span> *text</code></em>);
<span class="returnvalue">gboolean</span> <a class="link" href="exo-String-Utility-Functions.html#exo-str-is-equal" title="exo_str_is_equal ()">exo_str_is_equal</a> (<em class="parameter"><code>const <span class="type">gchar</span> *a</code></em>,
<em class="parameter"><code>const <span class="type">gchar</span> *b</code></em>);
<span class="returnvalue">gchar</span> * <a class="link" href="exo-String-Utility-Functions.html#exo-str-replace" title="exo_str_replace ()">exo_str_replace</a> (<em class="parameter"><code>const <span class="type">gchar</span> *str</code></em>,
<em class="parameter"><code>const <span class="type">gchar</span> *pattern</code></em>,
<em class="parameter"><code>const <span class="type">gchar</span> *replacement</code></em>);
<span class="returnvalue">gchar</span> * <a class="link" href="exo-String-Utility-Functions.html#exo-strdup-strftime" title="exo_strdup_strftime ()">exo_strdup_strftime</a> (<em class="parameter"><code>const <span class="type">gchar</span> *format</code></em>,
<em class="parameter"><code>const <span class="type">struct tm</span> *tm</code></em>);
<span class="returnvalue">gchar</span> ** <a class="link" href="exo-String-Utility-Functions.html#exo-strndupv" title="exo_strndupv ()">exo_strndupv</a> (<em class="parameter"><code><span class="type">gchar</span> **strv</code></em>,
<em class="parameter"><code><span class="type">gint</span> num</code></em>);
const <span class="returnvalue">gchar</span> * <a class="link" href="exo-String-Utility-Functions.html#exo-intern-string" title="exo_intern_string ()">exo_intern_string</a> (<em class="parameter"><code>const <span class="type">gchar</span> *string</code></em>);
const <span class="returnvalue">gchar</span> * <a class="link" href="exo-String-Utility-Functions.html#exo-intern-static-string" title="exo_intern_static_string ()">exo_intern_static_string</a> (<em class="parameter"><code>const <span class="type">gchar</span> *string</code></em>);
#define <a class="link" href="exo-String-Utility-Functions.html#I-:CAPS" title="I_()">I_</a> (string)
</pre>
</div>
<div class="refsect1" title="Description">
<a name="exo-String-Utility-Functions.description"></a><h2>Description</h2>
<p>
This section describes a number of utility functions for manipulating
strings.
</p>
</div>
<div class="refsect1" title="Details">
<a name="exo-String-Utility-Functions.details"></a><h2>Details</h2>
<div class="refsect2" title="exo_str_elide_underscores ()">
<a name="exo-str-elide-underscores"></a><h3>exo_str_elide_underscores ()</h3>
<pre class="programlisting"><span class="returnvalue">gchar</span> * exo_str_elide_underscores (<em class="parameter"><code>const <span class="type">gchar</span> *text</code></em>);</pre>
<p>
Returns a copy of <em class="parameter"><code>text</code></em> with all mnemonic underscores
stripped off.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>text</code></em> :</span></p></td>
<td>A zero terminated string.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> A copy of <em class="parameter"><code>text</code></em> without underscores. The
returned string must be freed when no
longer required.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="exo_str_is_equal ()">
<a name="exo-str-is-equal"></a><h3>exo_str_is_equal ()</h3>
<pre class="programlisting"><span class="returnvalue">gboolean</span> exo_str_is_equal (<em class="parameter"><code>const <span class="type">gchar</span> *a</code></em>,
<em class="parameter"><code>const <span class="type">gchar</span> *b</code></em>);</pre>
<p>
<a href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL--CAPS"><code class="literal">NULL</code></a>-safe string comparison. Returns <code class="literal">TRUE</code> if both <em class="parameter"><code>a</code></em> and <em class="parameter"><code>b</code></em> are
<a href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL--CAPS"><code class="literal">NULL</code></a> or if <em class="parameter"><code>a</code></em> and <em class="parameter"><code>b</code></em> refer to valid strings which are equal.
</p>
<p>
You should always prefer this function over <code class="function">strcmp()</code>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>a</code></em> :</span></p></td>
<td>A pointer to first string or <a href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL--CAPS"><code class="literal">NULL</code></a>.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>b</code></em> :</span></p></td>
<td>A pointer to second string or <a href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL--CAPS"><code class="literal">NULL</code></a>.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> <code class="literal">TRUE</code> if <em class="parameter"><code>a</code></em> equals <em class="parameter"><code>b</code></em>, else <code class="literal">FALSE</code>.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="exo_str_replace ()">
<a name="exo-str-replace"></a><h3>exo_str_replace ()</h3>
<pre class="programlisting"><span class="returnvalue">gchar</span> * exo_str_replace (<em class="parameter"><code>const <span class="type">gchar</span> *str</code></em>,
<em class="parameter"><code>const <span class="type">gchar</span> *pattern</code></em>,
<em class="parameter"><code>const <span class="type">gchar</span> *replacement</code></em>);</pre>
<p>
Searches <em class="parameter"><code>str</code></em> for occurances of <em class="parameter"><code>pattern</code></em> and replaces each
such occurance with <em class="parameter"><code>replacement</code></em>. Returns a newly allocated
copy of <em class="parameter"><code>str</code></em> on which the given replacement were performed.
The caller is responsible to free the returned string using
<code class="function">g_free()</code> when no longer needed.
</p>
<p>
Note that <em class="parameter"><code>pattern</code></em> and <em class="parameter"><code>replacement</code></em> don't need to be of the
same size.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>str</code></em> :</span></p></td>
<td>the input string.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>pattern</code></em> :</span></p></td>
<td>a search pattern in <em class="parameter"><code>str</code></em>.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>replacement</code></em> :</span></p></td>
<td>replacement string for <em class="parameter"><code>pattern</code></em>.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> a newly allocated copy of <em class="parameter"><code>str</code></em> where all
occurances of <em class="parameter"><code>pattern</code></em> are replaced with
<em class="parameter"><code>replacement</code></em>.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 0.3.1.1</p>
</div>
<hr>
<div class="refsect2" title="exo_strdup_strftime ()">
<a name="exo-strdup-strftime"></a><h3>exo_strdup_strftime ()</h3>
<pre class="programlisting"><span class="returnvalue">gchar</span> * exo_strdup_strftime (<em class="parameter"><code>const <span class="type">gchar</span> *format</code></em>,
<em class="parameter"><code>const <span class="type">struct tm</span> *tm</code></em>);</pre>
<p>
Cover for standard date-and-time-formatting routine strftime that returns
a newly-allocated string of the correct size. The caller is responsible
to free the returned string using <code class="function">g_free()</code> when no longer needed.
</p>
<p>
Besides the buffer management, there are two differences between this
and the library strftime:
</p>
<p>
The modifiers "-" and "_" between a "%" and a numeric directive
are defined as for the GNU version of strftime. "-" means "do not
pad the field" and "_" means "pad with spaces instead of zeroes".
</p>
<p>
Non-ANSI extensions to strftime are flagged at runtime with a
warning, so it's easy to notice use of the extensions without
testing with multiple versions of the library.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
<td>format string to pass to strftime(3). See the strftime(3) documentation
for details.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>tm</code></em> :</span></p></td>
<td>date/time, in struct tm format.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> a newly allocated string containing the formatted date/time.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 0.3.3</p>
</div>
<hr>
<div class="refsect2" title="exo_strndupv ()">
<a name="exo-strndupv"></a><h3>exo_strndupv ()</h3>
<pre class="programlisting"><span class="returnvalue">gchar</span> ** exo_strndupv (<em class="parameter"><code><span class="type">gchar</span> **strv</code></em>,
<em class="parameter"><code><span class="type">gint</span> num</code></em>);</pre>
<p>
Creates a new string vector containing the
first <em class="parameter"><code>n</code></em> elements of <em class="parameter"><code>strv</code></em>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>strv</code></em> :</span></p></td>
<td>String vector to duplicate.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>num</code></em> :</span></p></td>
<td>Number of strings in <em class="parameter"><code>strv</code></em> to
duplicate.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> The new string vector. Should be
freed using <code class="function">g_strfreev()</code> when no
longer needed.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="exo_intern_string ()">
<a name="exo-intern-string"></a><h3>exo_intern_string ()</h3>
<pre class="programlisting">const <span class="returnvalue">gchar</span> * exo_intern_string (<em class="parameter"><code>const <span class="type">gchar</span> *string</code></em>);</pre>
<p>
Returns a canonical representation for <em class="parameter"><code>string</code></em>. Interned strings can
be compared for equality by comparing the pointers, instead of using <code class="function">strcmp()</code>
or <a class="link" href="exo-String-Utility-Functions.html#exo-str-is-equal" title="exo_str_is_equal ()"><code class="function">exo_str_is_equal()</code></a>. <a class="link" href="exo-String-Utility-Functions.html#exo-intern-string" title="exo_intern_string ()"><code class="function">exo_intern_string()</code></a> takes a copy of the <em class="parameter"><code>string</code></em> for its
internal usage, so <em class="parameter"><code>string</code></em> does not need to be static.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
<td>a string
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> a canonical representation for the string
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 0.3.1.1</p>
</div>
<hr>
<div class="refsect2" title="exo_intern_static_string ()">
<a name="exo-intern-static-string"></a><h3>exo_intern_static_string ()</h3>
<pre class="programlisting">const <span class="returnvalue">gchar</span> * exo_intern_static_string (<em class="parameter"><code>const <span class="type">gchar</span> *string</code></em>);</pre>
<p>
Returns a canonical representation for <em class="parameter"><code>string</code></em>. Interned strings can
be compared for equality by comparing the pointers, instead of using <code class="function">strcmp()</code>
or <a class="link" href="exo-String-Utility-Functions.html#exo-str-is-equal" title="exo_str_is_equal ()"><code class="function">exo_str_is_equal()</code></a>. <a class="link" href="exo-String-Utility-Functions.html#exo-intern-static-string" title="exo_intern_static_string ()"><code class="function">exo_intern_static_string()</code></a> does not copy the string,
therefore <em class="parameter"><code>string</code></em> must not be freed or modified.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
<td>a static string
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> a canonical representation for the string
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 0.3.1.1</p>
</div>
<hr>
<div class="refsect2" title="I_()">
<a name="I-:CAPS"></a><h3>I_()</h3>
<pre class="programlisting">#define I_(string)</pre>
<p>
Shortcut for <a class="link" href="exo-String-Utility-Functions.html#exo-intern-static-string" title="exo_intern_static_string ()"><code class="function">exo_intern_static_string()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
<td>a static string.
</td>
</tr></tbody>
</table></div>
<p class="since">Since 0.3.1.1</p>
</div>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.14</div>
</body>
</html>
|
