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-memory">
6
<refentrytitle role="top_of_page" id="libedataserver-e-memory.top_of_page">e-memory</refentrytitle>
7
<manvolnum>3</manvolnum>
13
<refname>e-memory</refname>
14
<refpurpose></refpurpose>
17
<refsynopsisdiv id="libedataserver-e-memory.synopsis" role="synopsis">
18
<title role="synopsis.title">Synopsis</title>
20
<synopsis> <link linkend="EMemChunk">EMemChunk</link>;
21
<link linkend="EMemChunk"><returnvalue>EMemChunk</returnvalue></link> * <link linkend="e-memchunk-new">e_memchunk_new</link> (<parameter><link linkend="gint"><type>gint</type></link> atomcount</parameter>,
22
<parameter><link linkend="gint"><type>gint</type></link> atomsize</parameter>);
23
<link linkend="gpointer"><returnvalue>gpointer</returnvalue></link> <link linkend="e-memchunk-alloc">e_memchunk_alloc</link> (<parameter><link linkend="EMemChunk"><type>EMemChunk</type></link> *m</parameter>);
24
<link linkend="gpointer"><returnvalue>gpointer</returnvalue></link> <link linkend="e-memchunk-alloc0">e_memchunk_alloc0</link> (<parameter><link linkend="EMemChunk"><type>EMemChunk</type></link> *m</parameter>);
25
<link linkend="void"><returnvalue>void</returnvalue></link> <link linkend="e-memchunk-free">e_memchunk_free</link> (<parameter><link linkend="EMemChunk"><type>EMemChunk</type></link> *m</parameter>,
26
<parameter><link linkend="gpointer"><type>gpointer</type></link> mem</parameter>);
27
<link linkend="void"><returnvalue>void</returnvalue></link> <link linkend="e-memchunk-empty">e_memchunk_empty</link> (<parameter><link linkend="EMemChunk"><type>EMemChunk</type></link> *m</parameter>);
28
<link linkend="void"><returnvalue>void</returnvalue></link> <link linkend="e-memchunk-clean">e_memchunk_clean</link> (<parameter><link linkend="EMemChunk"><type>EMemChunk</type></link> *m</parameter>);
29
<link linkend="void"><returnvalue>void</returnvalue></link> <link linkend="e-memchunk-destroy">e_memchunk_destroy</link> (<parameter><link linkend="EMemChunk"><type>EMemChunk</type></link> *m</parameter>);
30
<link linkend="EMemPool">EMemPool</link>;
31
enum <link linkend="EMemPoolFlags">EMemPoolFlags</link>;
32
<link linkend="EMemPool"><returnvalue>EMemPool</returnvalue></link> * <link linkend="e-mempool-new">e_mempool_new</link> (<parameter><link linkend="gint"><type>gint</type></link> blocksize</parameter>,
33
<parameter><link linkend="gint"><type>gint</type></link> threshold</parameter>,
34
<parameter><link linkend="EMemPoolFlags"><type>EMemPoolFlags</type></link> flags</parameter>);
35
<link linkend="gpointer"><returnvalue>gpointer</returnvalue></link> <link linkend="e-mempool-alloc">e_mempool_alloc</link> (<parameter><link linkend="EMemPool"><type>EMemPool</type></link> *pool</parameter>,
36
<parameter><link linkend="gint"><type>gint</type></link> size</parameter>);
37
<link linkend="gchar"><returnvalue>gchar</returnvalue></link> * <link linkend="e-mempool-strdup">e_mempool_strdup</link> (<parameter><link linkend="EMemPool"><type>EMemPool</type></link> *pool</parameter>,
38
<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>);
39
<link linkend="void"><returnvalue>void</returnvalue></link> <link linkend="e-mempool-flush">e_mempool_flush</link> (<parameter><link linkend="EMemPool"><type>EMemPool</type></link> *pool</parameter>,
40
<parameter><link linkend="gint"><type>gint</type></link> freeall</parameter>);
41
<link linkend="void"><returnvalue>void</returnvalue></link> <link linkend="e-mempool-destroy">e_mempool_destroy</link> (<parameter><link linkend="EMemPool"><type>EMemPool</type></link> *pool</parameter>);
42
<link linkend="EStrv">EStrv</link>;
43
<link linkend="EStrv"><returnvalue>EStrv</returnvalue></link> * <link linkend="e-strv-new">e_strv_new</link> (<parameter><link linkend="gint"><type>gint</type></link> size</parameter>);
44
<link linkend="EStrv"><returnvalue>EStrv</returnvalue></link> * <link linkend="e-strv-set-ref">e_strv_set_ref</link> (<parameter><link linkend="EStrv"><type>EStrv</type></link> *strv</parameter>,
45
<parameter><link linkend="gint"><type>gint</type></link> index</parameter>,
46
<parameter><link linkend="gchar"><type>gchar</type></link> *str</parameter>);
47
<link linkend="EStrv"><returnvalue>EStrv</returnvalue></link> * <link linkend="e-strv-set-ref-free">e_strv_set_ref_free</link> (<parameter><link linkend="EStrv"><type>EStrv</type></link> *strv</parameter>,
48
<parameter><link linkend="gint"><type>gint</type></link> index</parameter>,
49
<parameter><link linkend="gchar"><type>gchar</type></link> *str</parameter>);
50
<link linkend="EStrv"><returnvalue>EStrv</returnvalue></link> * <link linkend="e-strv-set">e_strv_set</link> (<parameter><link linkend="EStrv"><type>EStrv</type></link> *strv</parameter>,
51
<parameter><link linkend="gint"><type>gint</type></link> index</parameter>,
52
<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>);
53
<link linkend="EStrv"><returnvalue>EStrv</returnvalue></link> * <link linkend="e-strv-pack">e_strv_pack</link> (<parameter><link linkend="EStrv"><type>EStrv</type></link> *strv</parameter>);
54
const <link linkend="gchar"><returnvalue>gchar</returnvalue></link> * <link linkend="e-strv-get">e_strv_get</link> (<parameter><link linkend="EStrv"><type>EStrv</type></link> *strv</parameter>,
55
<parameter><link linkend="gint"><type>gint</type></link> index</parameter>);
56
<link linkend="void"><returnvalue>void</returnvalue></link> <link linkend="e-strv-destroy">e_strv_destroy</link> (<parameter><link linkend="EStrv"><type>EStrv</type></link> *strv</parameter>);
57
<link linkend="EPoolv">EPoolv</link>;
58
<link linkend="EPoolv"><returnvalue>EPoolv</returnvalue></link> * <link linkend="e-poolv-new">e_poolv_new</link> (<parameter><link linkend="guint"><type>guint</type></link> size</parameter>);
59
<link linkend="EPoolv"><returnvalue>EPoolv</returnvalue></link> * <link linkend="e-poolv-cpy">e_poolv_cpy</link> (<parameter><link linkend="EPoolv"><type>EPoolv</type></link> *dest</parameter>,
60
<parameter>const <link linkend="EPoolv"><type>EPoolv</type></link> *src</parameter>);
61
<link linkend="EPoolv"><returnvalue>EPoolv</returnvalue></link> * <link linkend="e-poolv-set">e_poolv_set</link> (<parameter><link linkend="EPoolv"><type>EPoolv</type></link> *poolv</parameter>,
62
<parameter><link linkend="gint"><type>gint</type></link> index</parameter>,
63
<parameter><link linkend="gchar"><type>gchar</type></link> *str</parameter>,
64
<parameter><link linkend="gint"><type>gint</type></link> freeit</parameter>);
65
const <link linkend="gchar"><returnvalue>gchar</returnvalue></link> * <link linkend="e-poolv-get">e_poolv_get</link> (<parameter><link linkend="EPoolv"><type>EPoolv</type></link> *poolv</parameter>,
66
<parameter><link linkend="gint"><type>gint</type></link> index</parameter>);
67
<link linkend="void"><returnvalue>void</returnvalue></link> <link linkend="e-poolv-destroy">e_poolv_destroy</link> (<parameter><link linkend="EPoolv"><type>EPoolv</type></link> *poolv</parameter>);
71
<refsect1 id="libedataserver-e-memory.description" role="desc">
72
<title role="desc.title">Description</title>
76
<refsect1 id="libedataserver-e-memory.details" role="details">
77
<title role="details.title">Details</title>
78
<refsect2 id="EMemChunk" role="struct">
79
<title>EMemChunk</title>
80
<indexterm zone="EMemChunk"><primary>EMemChunk</primary></indexterm>
81
<programlisting>typedef struct _EMemChunk EMemChunk;</programlisting>
84
<refsect2 id="e-memchunk-new" role="function">
85
<title>e_memchunk_new ()</title>
86
<indexterm zone="e-memchunk-new"><primary>e_memchunk_new</primary></indexterm>
87
<programlisting><link linkend="EMemChunk"><returnvalue>EMemChunk</returnvalue></link> * e_memchunk_new (<parameter><link linkend="gint"><type>gint</type></link> atomcount</parameter>,
88
<parameter><link linkend="gint"><type>gint</type></link> atomsize</parameter>);</programlisting>
90
Create a new memchunk header. Memchunks are an efficient way to allocate
91
and deallocate identical sized blocks of memory quickly, and space efficiently.
94
e_memchunks are effectively the same as gmemchunks, only faster (much), and
95
they use less memory overhead for housekeeping.</para>
96
<variablelist role="params">
97
<varlistentry><term><parameter>atomcount</parameter> :</term>
98
<listitem><simpara>The number of atoms stored in a single malloc'd block of memory.
99
</simpara></listitem></varlistentry>
100
<varlistentry><term><parameter>atomsize</parameter> :</term>
101
<listitem><simpara>The size of each allocation.
102
</simpara></listitem></varlistentry>
103
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The new header.
104
</simpara></listitem></varlistentry>
105
</variablelist></refsect2>
106
<refsect2 id="e-memchunk-alloc" role="function">
107
<title>e_memchunk_alloc ()</title>
108
<indexterm zone="e-memchunk-alloc"><primary>e_memchunk_alloc</primary></indexterm>
109
<programlisting><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link> e_memchunk_alloc (<parameter><link linkend="EMemChunk"><type>EMemChunk</type></link> *m</parameter>);</programlisting>
111
</para><variablelist role="params">
112
<varlistentry><term><parameter>m</parameter> :</term>
114
</simpara></listitem></varlistentry>
115
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
116
</simpara></listitem></varlistentry>
117
</variablelist></refsect2>
118
<refsect2 id="e-memchunk-alloc0" role="function">
119
<title>e_memchunk_alloc0 ()</title>
120
<indexterm zone="e-memchunk-alloc0"><primary>e_memchunk_alloc0</primary></indexterm>
121
<programlisting><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link> e_memchunk_alloc0 (<parameter><link linkend="EMemChunk"><type>EMemChunk</type></link> *m</parameter>);</programlisting>
123
</para><variablelist role="params">
124
<varlistentry><term><parameter>m</parameter> :</term>
126
</simpara></listitem></varlistentry>
127
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
128
</simpara></listitem></varlistentry>
129
</variablelist></refsect2>
130
<refsect2 id="e-memchunk-free" role="function">
131
<title>e_memchunk_free ()</title>
132
<indexterm zone="e-memchunk-free"><primary>e_memchunk_free</primary></indexterm>
133
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link> e_memchunk_free (<parameter><link linkend="EMemChunk"><type>EMemChunk</type></link> *m</parameter>,
134
<parameter><link linkend="gpointer"><type>gpointer</type></link> mem</parameter>);</programlisting>
136
Free a single atom back to the free pool of atoms in the given
138
<variablelist role="params">
139
<varlistentry><term><parameter>mem</parameter> :</term>
140
<listitem><simpara>Address of atom to free.
141
</simpara></listitem></varlistentry>
142
</variablelist></refsect2>
143
<refsect2 id="e-memchunk-empty" role="function">
144
<title>e_memchunk_empty ()</title>
145
<indexterm zone="e-memchunk-empty"><primary>e_memchunk_empty</primary></indexterm>
146
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link> e_memchunk_empty (<parameter><link linkend="EMemChunk"><type>EMemChunk</type></link> *m</parameter>);</programlisting>
148
Clean out the memchunk buffers. Marks all allocated memory as free blocks,
149
but does not give it back to the system. Can be used if the memchunk
150
is to be used repeatedly.</para>
152
<refsect2 id="e-memchunk-clean" role="function">
153
<title>e_memchunk_clean ()</title>
154
<indexterm zone="e-memchunk-clean"><primary>e_memchunk_clean</primary></indexterm>
155
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link> e_memchunk_clean (<parameter><link linkend="EMemChunk"><type>EMemChunk</type></link> *m</parameter>);</programlisting>
157
Scan all empty blocks and check for blocks which can be free'd
161
This routine may take a while to run if there are many allocated
162
memory blocks (if the total number of allocations is many times
163
greater than atomcount).</para>
165
<refsect2 id="e-memchunk-destroy" role="function">
166
<title>e_memchunk_destroy ()</title>
167
<indexterm zone="e-memchunk-destroy"><primary>e_memchunk_destroy</primary></indexterm>
168
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link> e_memchunk_destroy (<parameter><link linkend="EMemChunk"><type>EMemChunk</type></link> *m</parameter>);</programlisting>
170
Free the memchunk header, and all associated memory.</para>
172
<refsect2 id="EMemPool" role="struct">
173
<title>EMemPool</title>
174
<indexterm zone="EMemPool"><primary>EMemPool</primary></indexterm>
175
<programlisting>typedef struct _EMemPool EMemPool;</programlisting>
178
<refsect2 id="EMemPoolFlags" role="enum">
179
<title>enum EMemPoolFlags</title>
180
<indexterm zone="EMemPoolFlags"><primary>EMemPoolFlags</primary></indexterm>
181
<programlisting>typedef enum {
182
E_MEMPOOL_ALIGN_STRUCT = 0, /* allocate to native structure alignment */
183
E_MEMPOOL_ALIGN_WORD = 1, /* allocate to words - 16 bit alignment */
184
E_MEMPOOL_ALIGN_BYTE = 2, /* allocate to bytes - 8 bit alignment */
185
E_MEMPOOL_ALIGN_MASK = 3 /* which bits determine the alignment information */
190
<refsect2 id="e-mempool-new" role="function">
191
<title>e_mempool_new ()</title>
192
<indexterm zone="e-mempool-new"><primary>e_mempool_new</primary></indexterm>
193
<programlisting><link linkend="EMemPool"><returnvalue>EMemPool</returnvalue></link> * e_mempool_new (<parameter><link linkend="gint"><type>gint</type></link> blocksize</parameter>,
194
<parameter><link linkend="gint"><type>gint</type></link> threshold</parameter>,
195
<parameter><link linkend="EMemPoolFlags"><type>EMemPoolFlags</type></link> flags</parameter>);</programlisting>
197
Create a new mempool header. Mempools can be used to efficiently
198
allocate data which can then be freed as a whole.
201
Mempools can also be used to efficiently allocate arbitrarily
202
aligned data (such as strings) without incurring the space overhead
203
of aligning each allocation (which is not required for strings).
206
However, each allocation cannot be freed individually, only all
208
<variablelist role="params">
209
<varlistentry><term><parameter>blocksize</parameter> :</term>
210
<listitem><simpara>The base blocksize to use for all system alocations.
211
</simpara></listitem></varlistentry>
212
<varlistentry><term><parameter>threshold</parameter> :</term>
213
<listitem><simpara>If the allocation exceeds the threshold, then it is
214
allocated separately and stored in a separate list.
215
</simpara></listitem></varlistentry>
216
<varlistentry><term><parameter>flags</parameter> :</term>
217
<listitem><simpara>Alignment options: E_MEMPOOL_ALIGN_STRUCT uses native
218
struct alignment, E_MEMPOOL_ALIGN_WORD aligns to 16 bits (2 bytes),
219
and E_MEMPOOL_ALIGN_BYTE aligns to the nearest byte. The default
220
is to align to native structures.
221
</simpara></listitem></varlistentry>
222
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
223
</simpara></listitem></varlistentry>
224
</variablelist></refsect2>
225
<refsect2 id="e-mempool-alloc" role="function">
226
<title>e_mempool_alloc ()</title>
227
<indexterm zone="e-mempool-alloc"><primary>e_mempool_alloc</primary></indexterm>
228
<programlisting><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link> e_mempool_alloc (<parameter><link linkend="EMemPool"><type>EMemPool</type></link> *pool</parameter>,
229
<parameter><link linkend="gint"><type>gint</type></link> size</parameter>);</programlisting>
231
Allocate a new data block in the mempool. Size will
232
be rounded up to the mempool's alignment restrictions
233
before being used.</para>
234
<variablelist role="params">
235
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
236
</simpara></listitem></varlistentry>
237
</variablelist></refsect2>
238
<refsect2 id="e-mempool-strdup" role="function">
239
<title>e_mempool_strdup ()</title>
240
<indexterm zone="e-mempool-strdup"><primary>e_mempool_strdup</primary></indexterm>
241
<programlisting><link linkend="gchar"><returnvalue>gchar</returnvalue></link> * e_mempool_strdup (<parameter><link linkend="EMemPool"><type>EMemPool</type></link> *pool</parameter>,
242
<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>);</programlisting>
244
</para><variablelist role="params">
245
<varlistentry><term><parameter>pool</parameter> :</term>
247
</simpara></listitem></varlistentry>
248
<varlistentry><term><parameter>str</parameter> :</term>
250
</simpara></listitem></varlistentry>
251
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
252
</simpara></listitem></varlistentry>
253
</variablelist></refsect2>
254
<refsect2 id="e-mempool-flush" role="function">
255
<title>e_mempool_flush ()</title>
256
<indexterm zone="e-mempool-flush"><primary>e_mempool_flush</primary></indexterm>
257
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link> e_mempool_flush (<parameter><link linkend="EMemPool"><type>EMemPool</type></link> *pool</parameter>,
258
<parameter><link linkend="gint"><type>gint</type></link> freeall</parameter>);</programlisting>
260
Flush used memory and mark allocated blocks as free.
263
If <parameter>freeall</parameter> is <link linkend="TRUE:CAPS"><type>TRUE</type></link>, then all allocated blocks are free'd
264
as well. Otherwise only blocks above the threshold are
265
actually freed, and the others are simply marked as empty.</para>
266
<variablelist role="params">
267
<varlistentry><term><parameter>freeall</parameter> :</term>
268
<listitem><simpara>Free all system allocated blocks as well.
269
</simpara></listitem></varlistentry>
270
</variablelist></refsect2>
271
<refsect2 id="e-mempool-destroy" role="function">
272
<title>e_mempool_destroy ()</title>
273
<indexterm zone="e-mempool-destroy"><primary>e_mempool_destroy</primary></indexterm>
274
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link> e_mempool_destroy (<parameter><link linkend="EMemPool"><type>EMemPool</type></link> *pool</parameter>);</programlisting>
276
Free all memory associated with a mempool.</para>
278
<refsect2 id="EStrv" role="struct">
280
<indexterm zone="EStrv"><primary>EStrv</primary></indexterm>
281
<programlisting>typedef struct _EStrv EStrv;</programlisting>
284
<refsect2 id="e-strv-new" role="function">
285
<title>e_strv_new ()</title>
286
<indexterm zone="e-strv-new"><primary>e_strv_new</primary></indexterm>
287
<programlisting><link linkend="EStrv"><returnvalue>EStrv</returnvalue></link> * e_strv_new (<parameter><link linkend="gint"><type>gint</type></link> size</parameter>);</programlisting>
289
Create a new strv (string array) header. strv's can be used to
290
create and work with arrays of strings that can then be compressed
291
into a space-efficient static structure. This is useful
292
where a number of strings are to be stored for lookup, and not
293
generally edited afterwards.
296
The size limit is currently 254 elements. This will probably not
297
change as arrays of this size suffer significant performance
298
penalties when looking up strings with high indices.</para>
299
<variablelist role="params">
300
<varlistentry><term><parameter>size</parameter> :</term>
301
<listitem><simpara>The number of elements in the strv. Currently this is limited
303
</simpara></listitem></varlistentry>
304
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
305
</simpara></listitem></varlistentry>
306
</variablelist></refsect2>
307
<refsect2 id="e-strv-set-ref" role="function">
308
<title>e_strv_set_ref ()</title>
309
<indexterm zone="e-strv-set-ref"><primary>e_strv_set_ref</primary></indexterm>
310
<programlisting><link linkend="EStrv"><returnvalue>EStrv</returnvalue></link> * e_strv_set_ref (<parameter><link linkend="EStrv"><type>EStrv</type></link> *strv</parameter>,
311
<parameter><link linkend="gint"><type>gint</type></link> index</parameter>,
312
<parameter><link linkend="gchar"><type>gchar</type></link> *str</parameter>);</programlisting>
314
Set a string array element by reference. The string
315
is not copied until the array is packed.
318
If <parameter>strv</parameter> has been packed, then it is unpacked ready
319
for more inserts, and should be packed again once finished with.
320
The memory used by the original <parameter>strv</parameter> is not freed until
321
the new strv is packed, or freed itself.</para>
322
<variablelist role="params">
323
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A new EStrv if the strv has already
324
been packed, otherwise <parameter>strv</parameter>.
325
</simpara></listitem></varlistentry>
326
</variablelist></refsect2>
327
<refsect2 id="e-strv-set-ref-free" role="function">
328
<title>e_strv_set_ref_free ()</title>
329
<indexterm zone="e-strv-set-ref-free"><primary>e_strv_set_ref_free</primary></indexterm>
330
<programlisting><link linkend="EStrv"><returnvalue>EStrv</returnvalue></link> * e_strv_set_ref_free (<parameter><link linkend="EStrv"><type>EStrv</type></link> *strv</parameter>,
331
<parameter><link linkend="gint"><type>gint</type></link> index</parameter>,
332
<parameter><link linkend="gchar"><type>gchar</type></link> *str</parameter>);</programlisting>
334
Set a string by reference, similar to set_ref, but also
335
free the string when finished with it. The string
336
is not copied until the strv is packed, and not at
337
all if the index is overwritten.</para>
338
<variablelist role="params">
339
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>strv</parameter> if already unpacked, otherwise an packed
341
</simpara></listitem></varlistentry>
342
</variablelist></refsect2>
343
<refsect2 id="e-strv-set" role="function">
344
<title>e_strv_set ()</title>
345
<indexterm zone="e-strv-set"><primary>e_strv_set</primary></indexterm>
346
<programlisting><link linkend="EStrv"><returnvalue>EStrv</returnvalue></link> * e_strv_set (<parameter><link linkend="EStrv"><type>EStrv</type></link> *strv</parameter>,
347
<parameter><link linkend="gint"><type>gint</type></link> index</parameter>,
348
<parameter>const <link linkend="gchar"><type>gchar</type></link> *str</parameter>);</programlisting>
350
Set a string array reference. The string <parameter>str</parameter> is copied
351
into the string array at location <parameter>index</parameter>.
354
If <parameter>strv</parameter> has been packed, then it is unpacked ready
355
for more inserts, and should be packed again once finished with.</para>
356
<variablelist role="params">
357
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A new EStrv if the strv has already
358
been packed, otherwise <parameter>strv</parameter>.
359
</simpara></listitem></varlistentry>
360
</variablelist></refsect2>
361
<refsect2 id="e-strv-pack" role="function">
362
<title>e_strv_pack ()</title>
363
<indexterm zone="e-strv-pack"><primary>e_strv_pack</primary></indexterm>
364
<programlisting><link linkend="EStrv"><returnvalue>EStrv</returnvalue></link> * e_strv_pack (<parameter><link linkend="EStrv"><type>EStrv</type></link> *strv</parameter>);</programlisting>
366
Pack the <parameter>strv</parameter> into a space efficient structure for later lookup.
369
All strings are packed into a single allocated block, separated
370
by single \0 characters, together with a count byte.</para>
371
<variablelist role="params">
372
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
373
</simpara></listitem></varlistentry>
374
</variablelist></refsect2>
375
<refsect2 id="e-strv-get" role="function">
376
<title>e_strv_get ()</title>
377
<indexterm zone="e-strv-get"><primary>e_strv_get</primary></indexterm>
378
<programlisting>const <link linkend="gchar"><returnvalue>gchar</returnvalue></link> * e_strv_get (<parameter><link linkend="EStrv"><type>EStrv</type></link> *strv</parameter>,
379
<parameter><link linkend="gint"><type>gint</type></link> index</parameter>);</programlisting>
381
Retrieve a string by index. This function works
382
identically on both packed and unpacked strv's, although
383
may be much slower on a packed strv.</para>
384
<variablelist role="params">
385
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
386
</simpara></listitem></varlistentry>
387
</variablelist></refsect2>
388
<refsect2 id="e-strv-destroy" role="function">
389
<title>e_strv_destroy ()</title>
390
<indexterm zone="e-strv-destroy"><primary>e_strv_destroy</primary></indexterm>
391
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link> e_strv_destroy (<parameter><link linkend="EStrv"><type>EStrv</type></link> *strv</parameter>);</programlisting>
393
Free a strv and all associated memory. Works on packed
394
or unpacked strv's.</para>
396
<refsect2 id="EPoolv" role="struct">
397
<title>EPoolv</title>
398
<indexterm zone="EPoolv"><primary>EPoolv</primary></indexterm>
399
<programlisting>typedef struct _EPoolv EPoolv;</programlisting>
402
<refsect2 id="e-poolv-new" role="function">
403
<title>e_poolv_new ()</title>
404
<indexterm zone="e-poolv-new"><primary>e_poolv_new</primary></indexterm>
405
<programlisting><link linkend="EPoolv"><returnvalue>EPoolv</returnvalue></link> * e_poolv_new (<parameter><link linkend="guint"><type>guint</type></link> size</parameter>);</programlisting>
407
</para><variablelist role="params">
408
<varlistentry><term><parameter>size</parameter> :</term>
410
</simpara></listitem></varlistentry>
411
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
412
</simpara></listitem></varlistentry>
413
</variablelist></refsect2>
414
<refsect2 id="e-poolv-cpy" role="function">
415
<title>e_poolv_cpy ()</title>
416
<indexterm zone="e-poolv-cpy"><primary>e_poolv_cpy</primary></indexterm>
417
<programlisting><link linkend="EPoolv"><returnvalue>EPoolv</returnvalue></link> * e_poolv_cpy (<parameter><link linkend="EPoolv"><type>EPoolv</type></link> *dest</parameter>,
418
<parameter>const <link linkend="EPoolv"><type>EPoolv</type></link> *src</parameter>);</programlisting>
420
Copy the contents of a pooled string vector</para>
421
<variablelist role="params">
422
<varlistentry><term><parameter>dest</parameter> :</term>
423
<listitem><simpara>destination pooled string vector
424
</simpara></listitem></varlistentry>
425
<varlistentry><term><parameter>src</parameter> :</term>
426
<listitem><simpara>source pooled string vector
427
</simpara></listitem></varlistentry>
428
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>dest</parameter>, which may be re-allocated if the strings
429
are different lengths.
430
</simpara></listitem></varlistentry>
431
</variablelist></refsect2>
432
<refsect2 id="e-poolv-set" role="function">
433
<title>e_poolv_set ()</title>
434
<indexterm zone="e-poolv-set"><primary>e_poolv_set</primary></indexterm>
435
<programlisting><link linkend="EPoolv"><returnvalue>EPoolv</returnvalue></link> * e_poolv_set (<parameter><link linkend="EPoolv"><type>EPoolv</type></link> *poolv</parameter>,
436
<parameter><link linkend="gint"><type>gint</type></link> index</parameter>,
437
<parameter><link linkend="gchar"><type>gchar</type></link> *str</parameter>,
438
<parameter><link linkend="gint"><type>gint</type></link> freeit</parameter>);</programlisting>
440
Set a string vector reference. If the caller will no longer be
441
referencing the string, freeit should be TRUE. Otherwise, this
442
will duplicate the string if it is not found in the pool.</para>
443
<variablelist role="params">
444
<varlistentry><term><parameter>poolv</parameter> :</term>
445
<listitem><simpara>pooled string vector
446
</simpara></listitem></varlistentry>
447
<varlistentry><term><parameter>index</parameter> :</term>
448
<listitem><simpara>index in vector of string
449
</simpara></listitem></varlistentry>
450
<varlistentry><term><parameter>str</parameter> :</term>
451
<listitem><simpara>string to set
452
</simpara></listitem></varlistentry>
453
<varlistentry><term><parameter>freeit</parameter> :</term>
454
<listitem><simpara>whether the caller is releasing its reference to the
456
</simpara></listitem></varlistentry>
457
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>poolv</parameter>
458
</simpara></listitem></varlistentry>
459
</variablelist></refsect2>
460
<refsect2 id="e-poolv-get" role="function">
461
<title>e_poolv_get ()</title>
462
<indexterm zone="e-poolv-get"><primary>e_poolv_get</primary></indexterm>
463
<programlisting>const <link linkend="gchar"><returnvalue>gchar</returnvalue></link> * e_poolv_get (<parameter><link linkend="EPoolv"><type>EPoolv</type></link> *poolv</parameter>,
464
<parameter><link linkend="gint"><type>gint</type></link> index</parameter>);</programlisting>
466
Retrieve a string by index. This could possibly just be a macro.
469
Since the pool is never freed, this string does not need to be
470
duplicated, but should not be modified.</para>
471
<variablelist role="params">
472
<varlistentry><term><parameter>poolv</parameter> :</term>
473
<listitem><simpara>pooled string vector
474
</simpara></listitem></varlistentry>
475
<varlistentry><term><parameter>index</parameter> :</term>
476
<listitem><simpara>index in vector of string
477
</simpara></listitem></varlistentry>
478
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> string at that index.
479
</simpara></listitem></varlistentry>
480
</variablelist></refsect2>
481
<refsect2 id="e-poolv-destroy" role="function">
482
<title>e_poolv_destroy ()</title>
483
<indexterm zone="e-poolv-destroy"><primary>e_poolv_destroy</primary></indexterm>
484
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link> e_poolv_destroy (<parameter><link linkend="EPoolv"><type>EPoolv</type></link> *poolv</parameter>);</programlisting>
486
Free a pooled string vector. This doesn't free the strings from
487
the vector, however.</para>
488
<variablelist role="params">
489
<varlistentry><term><parameter>poolv</parameter> :</term>
490
<listitem><simpara>pooled string vector to free
491
</simpara></listitem></varlistentry>
492
</variablelist></refsect2>
added
removed
docs/reference/libedataserver/xml/e-memory.xml
