← Back to branch summary

~ubuntu-branches/ubuntu/breezy/evolution-data-server/breezy

« back to all changes in this revision

Viewing changes to docs/reference/libedataserver/xml/e-util.xml

  • Committer: Bazaar Package Importer
  • Author(s): Daniel Holbach
  • Date: 2005-10-10 11:30:56 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20051010113056-rb4vj4kbs8yxft85
Tags: 1.4.1-0ubuntu3
* debian/patches/camel-imap-store.c.patch:
  - Ubuntu 17465: apply patch from
  http://bugzilla.gnome.org/attachment.cgi?id=53234&action=view
  (additional NULL pointer check)

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/libedataserver/xml/e-util.xml
 
1
<?xml version="1.0"?>
 
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
 
3
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
 
4
<refentry id="libedataserver-e-util">
 
5
<refmeta>
 
6
<refentrytitle id="top_of_page">Utility Functions</refentrytitle>
 
7
<manvolnum>3</manvolnum>
 
8
<refmiscinfo>LIBEDATASERVER Library</refmiscinfo>
 
9
</refmeta>
 
10
 
 
11
<refnamediv>
 
12
<refname>Utility Functions</refname>
 
13
<refpurpose>Miscellaneous utility functions for evolution-data-server.</refpurpose>
 
14
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
 
15
</refnamediv>
 
16
 
 
17
<refsynopsisdiv id="synopsis">
 
18
<title id="synopsis.title">Synopsis</title>
 
19
 
 
20
<synopsis>
 
21
 
 
22
 
 
23
 
 
24
struct      <link linkend="tm">tm</link>;
 
25
<link linkend="int">int</link>         <link linkend="e-util-mkdir-hier">e_util_mkdir_hier</link>               (const <link linkend="char">char</link> *path,
 
26
                                             <link linkend="mode-t">mode_t</link> mode);
 
27
<link linkend="gchar">gchar</link>*      <link linkend="e-util-strstrcase">e_util_strstrcase</link>               (const <link linkend="gchar">gchar</link> *haystack,
 
28
                                             const <link linkend="gchar">gchar</link> *needle);
 
29
<link linkend="gchar">gchar</link>*      <link linkend="e-util-unicode-get-utf8">e_util_unicode_get_utf8</link>         (const <link linkend="gchar">gchar</link> *text,
 
30
                                             <link linkend="gunichar">gunichar</link> *out);
 
31
const <link linkend="gchar">gchar</link>* <link linkend="e-util-utf8-strstrcase">e_util_utf8_strstrcase</link>         (const <link linkend="gchar">gchar</link> *haystack,
 
32
                                             const <link linkend="gchar">gchar</link> *needle);
 
33
const <link linkend="gchar">gchar</link>* <link linkend="e-util-utf8-strstrcasedecomp">e_util_utf8_strstrcasedecomp</link>   (const <link linkend="gchar">gchar</link> *haystack,
 
34
                                             const <link linkend="gchar">gchar</link> *needle);
 
35
<link linkend="size-t">size_t</link>      <link linkend="e-utf8-strftime">e_utf8_strftime</link>                 (<link linkend="char">char</link> *s,
 
36
                                             <link linkend="size-t">size_t</link> max,
 
37
                                             const <link linkend="char">char</link> *fmt,
 
38
                                             const struct <link linkend="tm">tm</link> *tm);
 
39
<link linkend="size-t">size_t</link>      <link linkend="e-strftime">e_strftime</link>                      (<link linkend="char">char</link> *s,
 
40
                                             <link linkend="size-t">size_t</link> max,
 
41
                                             const <link linkend="char">char</link> *fmt,
 
42
                                             const struct <link linkend="tm">tm</link> *tm);
 
43
</synopsis>
 
44
</refsynopsisdiv>
 
45
 
 
46
 
 
47
 
 
48
 
 
49
 
 
50
 
 
51
 
 
52
 
 
53
 
 
54
<refsect1 id="desc">
 
55
<title id="desc.title">Description</title>
 
56
<para>
 
57
 
 
58
</para>
 
59
</refsect1>
 
60
 
 
61
<refsect1 id="details">
 
62
<title id="details.title">Details</title>
 
63
<refsect2>
 
64
<title><anchor id="tm"/>struct tm</title>
 
65
<indexterm><primary>tm</primary></indexterm><programlisting>struct tm;</programlisting>
 
66
<para>
 
67
 
 
68
</para></refsect2>
 
69
<refsect2>
 
70
<title><anchor id="e-util-mkdir-hier"/>e_util_mkdir_hier ()</title>
 
71
<indexterm><primary>e_util_mkdir_hier</primary></indexterm><programlisting><link linkend="int">int</link>         e_util_mkdir_hier               (const <link linkend="char">char</link> *path,
 
72
                                             <link linkend="mode-t">mode_t</link> mode);</programlisting>
 
73
<para>
 
74
Creates a directory hierarchy based on the string <parameter>path</parameter>. If <parameter>path</parameter>
 
75
is prefixed by a '/', the directories will be created relative to
 
76
the root of the file system; otherwise, the directories will be
 
77
created relative to the current directory.</para>
 
78
<para>
 
79
 
 
80
</para><variablelist role="params">
 
81
<varlistentry><term><parameter>path</parameter>&nbsp;:</term>
 
82
<listitem><simpara> The directory hierarchy to create.
 
83
</simpara></listitem></varlistentry>
 
84
<varlistentry><term><parameter>mode</parameter>&nbsp;:</term>
 
85
<listitem><simpara> The permissions to use for the directories.
 
86
</simpara></listitem></varlistentry>
 
87
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> 0 on success; -1 on failure.
 
88
</simpara></listitem></varlistentry>
 
89
</variablelist></refsect2>
 
90
<refsect2>
 
91
<title><anchor id="e-util-strstrcase"/>e_util_strstrcase ()</title>
 
92
<indexterm><primary>e_util_strstrcase</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*      e_util_strstrcase               (const <link linkend="gchar">gchar</link> *haystack,
 
93
                                             const <link linkend="gchar">gchar</link> *needle);</programlisting>
 
94
<para>
 
95
Find the first instance of <parameter>needle</parameter> in <parameter>haystack</parameter>, ignoring case.</para>
 
96
<para>
 
97
 
 
98
</para><variablelist role="params">
 
99
<varlistentry><term><parameter>haystack</parameter>&nbsp;:</term>
 
100
<listitem><simpara> The string to search in.
 
101
</simpara></listitem></varlistentry>
 
102
<varlistentry><term><parameter>needle</parameter>&nbsp;:</term>
 
103
<listitem><simpara> The string to search for.
 
104
</simpara></listitem></varlistentry>
 
105
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A pointer to the start of <parameter>needle</parameter> in <parameter>haystack</parameter>, or NULL if
 
106
         <parameter>needle</parameter> is not found.
 
107
</simpara></listitem></varlistentry>
 
108
</variablelist></refsect2>
 
109
<refsect2>
 
110
<title><anchor id="e-util-unicode-get-utf8"/>e_util_unicode_get_utf8 ()</title>
 
111
<indexterm><primary>e_util_unicode_get_utf8</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*      e_util_unicode_get_utf8         (const <link linkend="gchar">gchar</link> *text,
 
112
                                             <link linkend="gunichar">gunichar</link> *out);</programlisting>
 
113
<para>
 
114
Get a UTF-8 character from the beginning of <parameter>text</parameter>.</para>
 
115
<para>
 
116
 
 
117
</para><variablelist role="params">
 
118
<varlistentry><term><parameter>text</parameter>&nbsp;:</term>
 
119
<listitem><simpara> The string to take the UTF-8 character from.
 
120
</simpara></listitem></varlistentry>
 
121
<varlistentry><term><parameter>out</parameter>&nbsp;:</term>
 
122
<listitem><simpara> The location to store the UTF-8 character in.
 
123
</simpara></listitem></varlistentry>
 
124
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A pointer to the next character in <parameter>text</parameter> after <parameter>out</parameter>. 
 
125
</simpara></listitem></varlistentry>
 
126
</variablelist></refsect2>
 
127
<refsect2>
 
128
<title><anchor id="e-util-utf8-strstrcase"/>e_util_utf8_strstrcase ()</title>
 
129
<indexterm><primary>e_util_utf8_strstrcase</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* e_util_utf8_strstrcase         (const <link linkend="gchar">gchar</link> *haystack,
 
130
                                             const <link linkend="gchar">gchar</link> *needle);</programlisting>
 
131
<para>
 
132
Find the first instance of <parameter>needle</parameter> in <parameter>haystack</parameter>, ignoring
 
133
case. Both <parameter>needle</parameter> and <parameter>haystack</parameter> are UTF-8 strings.</para>
 
134
<para>
 
135
 
 
136
</para><variablelist role="params">
 
137
<varlistentry><term><parameter>haystack</parameter>&nbsp;:</term>
 
138
<listitem><simpara> The string to search in.
 
139
</simpara></listitem></varlistentry>
 
140
<varlistentry><term><parameter>needle</parameter>&nbsp;:</term>
 
141
<listitem><simpara> The string to search for.
 
142
</simpara></listitem></varlistentry>
 
143
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A pointer to the first instance of <parameter>needle</parameter> in <parameter>haystack</parameter>, or
 
144
         <literal>NULL</literal> if either of the strings are not legal UTF-8 strings.
 
145
</simpara></listitem></varlistentry>
 
146
</variablelist></refsect2>
 
147
<refsect2>
 
148
<title><anchor id="e-util-utf8-strstrcasedecomp"/>e_util_utf8_strstrcasedecomp ()</title>
 
149
<indexterm><primary>e_util_utf8_strstrcasedecomp</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* e_util_utf8_strstrcasedecomp   (const <link linkend="gchar">gchar</link> *haystack,
 
150
                                             const <link linkend="gchar">gchar</link> *needle);</programlisting>
 
151
<para>
 
152
Find the first instance of <parameter>needle</parameter> in <parameter>haystack</parameter>, where both <parameter>needle</parameter>
 
153
and <parameter>haystack</parameter> are UTF-8 strings. Both strings are stripped and
 
154
decomposed for comparison, and case is ignored.</para>
 
155
<para>
 
156
 
 
157
</para><variablelist role="params">
 
158
<varlistentry><term><parameter>haystack</parameter>&nbsp;:</term>
 
159
<listitem><simpara> The string to search in.
 
160
</simpara></listitem></varlistentry>
 
161
<varlistentry><term><parameter>needle</parameter>&nbsp;:</term>
 
162
<listitem><simpara> The string to search for.
 
163
</simpara></listitem></varlistentry>
 
164
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A pointer to the first instance of <parameter>needle</parameter> in <parameter>haystack</parameter>, or
 
165
         <literal>NULL</literal> if either of the strings are not legal UTF-8 strings.
 
166
</simpara></listitem></varlistentry>
 
167
</variablelist></refsect2>
 
168
<refsect2>
 
169
<title><anchor id="e-utf8-strftime"/>e_utf8_strftime ()</title>
 
170
<indexterm><primary>e_utf8_strftime</primary></indexterm><programlisting><link linkend="size-t">size_t</link>      e_utf8_strftime                 (<link linkend="char">char</link> *s,
 
171
                                             <link linkend="size-t">size_t</link> max,
 
172
                                             const <link linkend="char">char</link> *fmt,
 
173
                                             const struct <link linkend="tm">tm</link> *tm);</programlisting>
 
174
<para>
 
175
The UTF-8 equivalent of <link linkend="e-strftime"><function>e_strftime()</function></link>.</para>
 
176
<para>
 
177
 
 
178
</para><variablelist role="params">
 
179
<varlistentry><term><parameter>s</parameter>&nbsp;:</term>
 
180
<listitem><simpara> The string array to store the result in.
 
181
</simpara></listitem></varlistentry>
 
182
<varlistentry><term><parameter>max</parameter>&nbsp;:</term>
 
183
<listitem><simpara> The size of array <parameter>s</parameter>.
 
184
</simpara></listitem></varlistentry>
 
185
<varlistentry><term><parameter>fmt</parameter>&nbsp;:</term>
 
186
<listitem><simpara> The formatting to use on <parameter>tm</parameter>.
 
187
</simpara></listitem></varlistentry>
 
188
<varlistentry><term><parameter>tm</parameter>&nbsp;:</term>
 
189
<listitem><simpara> The time value to format.
 
190
</simpara></listitem></varlistentry>
 
191
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> The number of characters placed in <parameter>s</parameter>.
 
192
</simpara></listitem></varlistentry>
 
193
</variablelist></refsect2>
 
194
<refsect2>
 
195
<title><anchor id="e-strftime"/>e_strftime ()</title>
 
196
<indexterm><primary>e_strftime</primary></indexterm><programlisting><link linkend="size-t">size_t</link>      e_strftime                      (<link linkend="char">char</link> *s,
 
197
                                             <link linkend="size-t">size_t</link> max,
 
198
                                             const <link linkend="char">char</link> *fmt,
 
199
                                             const struct <link linkend="tm">tm</link> *tm);</programlisting>
 
200
<para>
 
201
This function is a wrapper around the strftime(3) function, which
 
202
converts the &amp;percnt;l and &amp;percnt;k (12h and 24h) format variables if necessary.</para>
 
203
<para>
 
204
 
 
205
</para><variablelist role="params">
 
206
<varlistentry><term><parameter>s</parameter>&nbsp;:</term>
 
207
<listitem><simpara> The string array to store the result in.
 
208
</simpara></listitem></varlistentry>
 
209
<varlistentry><term><parameter>max</parameter>&nbsp;:</term>
 
210
<listitem><simpara> The size of array <parameter>s</parameter>.
 
211
</simpara></listitem></varlistentry>
 
212
<varlistentry><term><parameter>fmt</parameter>&nbsp;:</term>
 
213
<listitem><simpara> The formatting to use on <parameter>tm</parameter>.
 
214
</simpara></listitem></varlistentry>
 
215
<varlistentry><term><parameter>tm</parameter>&nbsp;:</term>
 
216
<listitem><simpara> The time value to format.
 
217
</simpara></listitem></varlistentry>
 
218
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> The number of characters placed in <parameter>s</parameter>.
 
219
</simpara></listitem></varlistentry>
 
220
</variablelist></refsect2>
 
221
 
 
222
</refsect1>
 
223
 
 
224
 
 
225
 
 
226
 
 
227
</refentry>