<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="libedataserver-e-memory">
<refmeta>
<refentrytitle role="top_of_page">e-memory</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBEDATASERVER Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>e-memory</refname>
<refpurpose></refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>



            <link linkend="EMemChunk">EMemChunk</link>;
<link linkend="EMemChunk">EMemChunk</link>*  <link linkend="e-memchunk-new">e_memchunk_new</link>                  (<link linkend="int">int</link> atomcount,
                                             <link linkend="int">int</link> atomsize);
<link linkend="void">void</link>*       <link linkend="e-memchunk-alloc">e_memchunk_alloc</link>                (<link linkend="EMemChunk">EMemChunk</link> *m);
<link linkend="void">void</link>*       <link linkend="e-memchunk-alloc0">e_memchunk_alloc0</link>               (<link linkend="EMemChunk">EMemChunk</link> *m);
<link linkend="void">void</link>        <link linkend="e-memchunk-free">e_memchunk_free</link>                 (<link linkend="EMemChunk">EMemChunk</link> *m,
                                             <link linkend="void">void</link> *mem);
<link linkend="void">void</link>        <link linkend="e-memchunk-empty">e_memchunk_empty</link>                (<link linkend="EMemChunk">EMemChunk</link> *m);
<link linkend="void">void</link>        <link linkend="e-memchunk-clean">e_memchunk_clean</link>                (<link linkend="EMemChunk">EMemChunk</link> *m);
<link linkend="void">void</link>        <link linkend="e-memchunk-destroy">e_memchunk_destroy</link>              (<link linkend="EMemChunk">EMemChunk</link> *m);
            <link linkend="EMemPool">EMemPool</link>;
enum        <link linkend="EMemPoolFlags">EMemPoolFlags</link>;
<link linkend="EMemPool">EMemPool</link>*   <link linkend="e-mempool-new">e_mempool_new</link>                   (<link linkend="int">int</link> blocksize,
                                             <link linkend="int">int</link> threshold,
                                             <link linkend="EMemPoolFlags">EMemPoolFlags</link> flags);
<link linkend="void">void</link>*       <link linkend="e-mempool-alloc">e_mempool_alloc</link>                 (<link linkend="EMemPool">EMemPool</link> *pool,
                                             <link linkend="int">int</link> size);
<link linkend="char">char</link>*       <link linkend="e-mempool-strdup">e_mempool_strdup</link>                (<link linkend="EMemPool">EMemPool</link> *pool,
                                             const <link linkend="char">char</link> *str);
<link linkend="void">void</link>        <link linkend="e-mempool-flush">e_mempool_flush</link>                 (<link linkend="EMemPool">EMemPool</link> *pool,
                                             <link linkend="int">int</link> freeall);
<link linkend="void">void</link>        <link linkend="e-mempool-destroy">e_mempool_destroy</link>               (<link linkend="EMemPool">EMemPool</link> *pool);
            <link linkend="EStrv">EStrv</link>;
<link linkend="EStrv">EStrv</link>*      <link linkend="e-strv-new">e_strv_new</link>                      (<link linkend="int">int</link> size);
<link linkend="EStrv">EStrv</link>*      <link linkend="e-strv-set-ref">e_strv_set_ref</link>                  (<link linkend="EStrv">EStrv</link> *strv,
                                             <link linkend="int">int</link> index,
                                             <link linkend="char">char</link> *str);
<link linkend="EStrv">EStrv</link>*      <link linkend="e-strv-set-ref-free">e_strv_set_ref_free</link>             (<link linkend="EStrv">EStrv</link> *strv,
                                             <link linkend="int">int</link> index,
                                             <link linkend="char">char</link> *str);
<link linkend="EStrv">EStrv</link>*      <link linkend="e-strv-set">e_strv_set</link>                      (<link linkend="EStrv">EStrv</link> *strv,
                                             <link linkend="int">int</link> index,
                                             const <link linkend="char">char</link> *str);
<link linkend="EStrv">EStrv</link>*      <link linkend="e-strv-pack">e_strv_pack</link>                     (<link linkend="EStrv">EStrv</link> *strv);
<link linkend="char">char</link>*       <link linkend="e-strv-get">e_strv_get</link>                      (<link linkend="EStrv">EStrv</link> *strv,
                                             <link linkend="int">int</link> index);
<link linkend="void">void</link>        <link linkend="e-strv-destroy">e_strv_destroy</link>                  (<link linkend="EStrv">EStrv</link> *strv);
            <link linkend="EPoolv">EPoolv</link>;
<link linkend="EPoolv">EPoolv</link>*     <link linkend="e-poolv-new">e_poolv_new</link>                     (unsigned <link linkend="int">int</link> size);
<link linkend="EPoolv">EPoolv</link>*     <link linkend="e-poolv-cpy">e_poolv_cpy</link>                     (<link linkend="EPoolv">EPoolv</link> *dest,
                                             const <link linkend="EPoolv">EPoolv</link> *src);
<link linkend="EPoolv">EPoolv</link>*     <link linkend="e-poolv-set">e_poolv_set</link>                     (<link linkend="EPoolv">EPoolv</link> *poolv,
                                             <link linkend="int">int</link> index,
                                             <link linkend="char">char</link> *str,
                                             <link linkend="int">int</link> freeit);
const <link linkend="char">char</link>* <link linkend="e-poolv-get">e_poolv_get</link>                     (<link linkend="EPoolv">EPoolv</link> *poolv,
                                             <link linkend="int">int</link> index);
<link linkend="void">void</link>        <link linkend="e-poolv-destroy">e_poolv_destroy</link>                 (<link linkend="EPoolv">EPoolv</link> *poolv);
</synopsis>
</refsynopsisdiv>









<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>

</para>
</refsect1>

<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="EMemChunk" role="struct"/>EMemChunk</title>
<indexterm><primary>EMemChunk</primary></indexterm><programlisting>typedef struct _EMemChunk EMemChunk;</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="e-memchunk-new" role="function"/>e_memchunk_new ()</title>
<indexterm><primary>e_memchunk_new</primary></indexterm><programlisting><link linkend="EMemChunk">EMemChunk</link>*  e_memchunk_new                  (<link linkend="int">int</link> atomcount,
                                             <link linkend="int">int</link> atomsize);</programlisting>
<para>
Create a new memchunk header.  Memchunks are an efficient way to allocate
and deallocate identical sized blocks of memory quickly, and space efficiently.
</para>
<para>
e_memchunks are effectively the same as gmemchunks, only faster (much), and
they use less memory overhead for housekeeping.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>atomcount</parameter>&nbsp;:</term>
<listitem><simpara> The number of atoms stored in a single malloc'd block of memory.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>atomsize</parameter>&nbsp;:</term>
<listitem><simpara> The size of each allocation.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> The new header.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-memchunk-alloc" role="function"/>e_memchunk_alloc ()</title>
<indexterm><primary>e_memchunk_alloc</primary></indexterm><programlisting><link linkend="void">void</link>*       e_memchunk_alloc                (<link linkend="EMemChunk">EMemChunk</link> *m);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>m</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-memchunk-alloc0" role="function"/>e_memchunk_alloc0 ()</title>
<indexterm><primary>e_memchunk_alloc0</primary></indexterm><programlisting><link linkend="void">void</link>*       e_memchunk_alloc0               (<link linkend="EMemChunk">EMemChunk</link> *m);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>m</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-memchunk-free" role="function"/>e_memchunk_free ()</title>
<indexterm><primary>e_memchunk_free</primary></indexterm><programlisting><link linkend="void">void</link>        e_memchunk_free                 (<link linkend="EMemChunk">EMemChunk</link> *m,
                                             <link linkend="void">void</link> *mem);</programlisting>
<para>
Free a single atom back to the free pool of atoms in the given
memchunk.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>m</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mem</parameter>&nbsp;:</term>
<listitem><simpara> Address of atom to free.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-memchunk-empty" role="function"/>e_memchunk_empty ()</title>
<indexterm><primary>e_memchunk_empty</primary></indexterm><programlisting><link linkend="void">void</link>        e_memchunk_empty                (<link linkend="EMemChunk">EMemChunk</link> *m);</programlisting>
<para>
Clean out the memchunk buffers.  Marks all allocated memory as free blocks,
but does not give it back to the system.  Can be used if the memchunk
is to be used repeatedly.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>m</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-memchunk-clean" role="function"/>e_memchunk_clean ()</title>
<indexterm><primary>e_memchunk_clean</primary></indexterm><programlisting><link linkend="void">void</link>        e_memchunk_clean                (<link linkend="EMemChunk">EMemChunk</link> *m);</programlisting>
<para>
Scan all empty blocks and check for blocks which can be free'd 
back to the system.
</para>
<para>
This routine may take a while to run if there are many allocated
memory blocks (if the total number of allocations is many times
greater than atomcount).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>m</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-memchunk-destroy" role="function"/>e_memchunk_destroy ()</title>
<indexterm><primary>e_memchunk_destroy</primary></indexterm><programlisting><link linkend="void">void</link>        e_memchunk_destroy              (<link linkend="EMemChunk">EMemChunk</link> *m);</programlisting>
<para>
Free the memchunk header, and all associated memory.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>m</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="EMemPool" role="struct"/>EMemPool</title>
<indexterm><primary>EMemPool</primary></indexterm><programlisting>typedef struct _EMemPool EMemPool;</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="EMemPoolFlags" role="enum"/>enum EMemPoolFlags</title>
<indexterm><primary>EMemPoolFlags</primary></indexterm><programlisting>typedef enum {
	E_MEMPOOL_ALIGN_STRUCT = 0,	/* allocate to native structure alignment */
	E_MEMPOOL_ALIGN_WORD = 1,	/* allocate to words - 16 bit alignment */
	E_MEMPOOL_ALIGN_BYTE = 2,	/* allocate to bytes - 8 bit alignment */
	E_MEMPOOL_ALIGN_MASK = 3, /* which bits determine the alignment information */
} EMemPoolFlags;
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="e-mempool-new" role="function"/>e_mempool_new ()</title>
<indexterm><primary>e_mempool_new</primary></indexterm><programlisting><link linkend="EMemPool">EMemPool</link>*   e_mempool_new                   (<link linkend="int">int</link> blocksize,
                                             <link linkend="int">int</link> threshold,
                                             <link linkend="EMemPoolFlags">EMemPoolFlags</link> flags);</programlisting>
<para>
Create a new mempool header.  Mempools can be used to efficiently
allocate data which can then be freed as a whole.
</para>
<para>
Mempools can also be used to efficiently allocate arbitrarily
aligned data (such as strings) without incurring the space overhead
of aligning each allocation (which is not required for strings).
</para>
<para>
However, each allocation cannot be freed individually, only all
or nothing.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>blocksize</parameter>&nbsp;:</term>
<listitem><simpara> The base blocksize to use for all system alocations.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>threshold</parameter>&nbsp;:</term>
<listitem><simpara> If the allocation exceeds the threshold, then it is
allocated separately and stored in a separate list.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&nbsp;:</term>
<listitem><simpara> Alignment options: E_MEMPOOL_ALIGN_STRUCT uses native
struct alignment, E_MEMPOOL_ALIGN_WORD aligns to 16 bits (2 bytes),
and E_MEMPOOL_ALIGN_BYTE aligns to the nearest byte.  The default
is to align to native structures.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-mempool-alloc" role="function"/>e_mempool_alloc ()</title>
<indexterm><primary>e_mempool_alloc</primary></indexterm><programlisting><link linkend="void">void</link>*       e_mempool_alloc                 (<link linkend="EMemPool">EMemPool</link> *pool,
                                             <link linkend="int">int</link> size);</programlisting>
<para>
Allocate a new data block in the mempool.  Size will
be rounded up to the mempool's alignment restrictions
before being used.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>pool</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-mempool-strdup" role="function"/>e_mempool_strdup ()</title>
<indexterm><primary>e_mempool_strdup</primary></indexterm><programlisting><link linkend="char">char</link>*       e_mempool_strdup                (<link linkend="EMemPool">EMemPool</link> *pool,
                                             const <link linkend="char">char</link> *str);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>pool</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-mempool-flush" role="function"/>e_mempool_flush ()</title>
<indexterm><primary>e_mempool_flush</primary></indexterm><programlisting><link linkend="void">void</link>        e_mempool_flush                 (<link linkend="EMemPool">EMemPool</link> *pool,
                                             <link linkend="int">int</link> freeall);</programlisting>
<para>
Flush used memory and mark allocated blocks as free.
</para>
<para>
If <parameter>freeall</parameter> is <link linkend="TRUE:CAPS"><type>TRUE</type></link>, then all allocated blocks are free'd
as well.  Otherwise only blocks above the threshold are
actually freed, and the others are simply marked as empty.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>pool</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>freeall</parameter>&nbsp;:</term>
<listitem><simpara> Free all system allocated blocks as well.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-mempool-destroy" role="function"/>e_mempool_destroy ()</title>
<indexterm><primary>e_mempool_destroy</primary></indexterm><programlisting><link linkend="void">void</link>        e_mempool_destroy               (<link linkend="EMemPool">EMemPool</link> *pool);</programlisting>
<para>
Free all memory associated with a mempool.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>pool</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="EStrv" role="struct"/>EStrv</title>
<indexterm><primary>EStrv</primary></indexterm><programlisting>typedef struct _EStrv EStrv;</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="e-strv-new" role="function"/>e_strv_new ()</title>
<indexterm><primary>e_strv_new</primary></indexterm><programlisting><link linkend="EStrv">EStrv</link>*      e_strv_new                      (<link linkend="int">int</link> size);</programlisting>
<para>
Create a new strv (string array) header.  strv's can be used to
create and work with arrays of strings that can then be compressed
into a space-efficient static structure.  This is useful
where a number of strings are to be stored for lookup, and not
generally edited afterwards.
</para>
<para>
The size limit is currently 254 elements.  This will probably not
change as arrays of this size suffer significant performance
penalties when looking up strings with high indices.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>size</parameter>&nbsp;:</term>
<listitem><simpara> The number of elements in the strv.  Currently this is limited
to 254 elements.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-strv-set-ref" role="function"/>e_strv_set_ref ()</title>
<indexterm><primary>e_strv_set_ref</primary></indexterm><programlisting><link linkend="EStrv">EStrv</link>*      e_strv_set_ref                  (<link linkend="EStrv">EStrv</link> *strv,
                                             <link linkend="int">int</link> index,
                                             <link linkend="char">char</link> *str);</programlisting>
<para>
Set a string array element by reference.  The string
is not copied until the array is packed.
</para>
<para>
If <parameter>strv</parameter> has been packed, then it is unpacked ready
for more inserts, and should be packed again once finished with.
The memory used by the original <parameter>strv</parameter> is not freed until
the new strv is packed, or freed itself.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>strv</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A new EStrv if the strv has already
been packed, otherwise <parameter>strv</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-strv-set-ref-free" role="function"/>e_strv_set_ref_free ()</title>
<indexterm><primary>e_strv_set_ref_free</primary></indexterm><programlisting><link linkend="EStrv">EStrv</link>*      e_strv_set_ref_free             (<link linkend="EStrv">EStrv</link> *strv,
                                             <link linkend="int">int</link> index,
                                             <link linkend="char">char</link> *str);</programlisting>
<para>
Set a string by reference, similar to set_ref, but also
free the string when finished with it.  The string
is not copied until the strv is packed, and not at
all if the index is overwritten.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>strv</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <parameter>strv</parameter> if already unpacked, otherwise an packed
EStrv.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-strv-set" role="function"/>e_strv_set ()</title>
<indexterm><primary>e_strv_set</primary></indexterm><programlisting><link linkend="EStrv">EStrv</link>*      e_strv_set                      (<link linkend="EStrv">EStrv</link> *strv,
                                             <link linkend="int">int</link> index,
                                             const <link linkend="char">char</link> *str);</programlisting>
<para>
Set a string array reference.  The string <parameter>str</parameter> is copied
into the string array at location <parameter>index</parameter>.
</para>
<para>
If <parameter>strv</parameter> has been packed, then it is unpacked ready
for more inserts, and should be packed again once finished with.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>strv</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A new EStrv if the strv has already
been packed, otherwise <parameter>strv</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-strv-pack" role="function"/>e_strv_pack ()</title>
<indexterm><primary>e_strv_pack</primary></indexterm><programlisting><link linkend="EStrv">EStrv</link>*      e_strv_pack                     (<link linkend="EStrv">EStrv</link> *strv);</programlisting>
<para>
Pack the <parameter>strv</parameter> into a space efficient structure for later lookup.
</para>
<para>
All strings are packed into a single allocated block, separated
by single \0 characters, together with a count byte.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>strv</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-strv-get" role="function"/>e_strv_get ()</title>
<indexterm><primary>e_strv_get</primary></indexterm><programlisting><link linkend="char">char</link>*       e_strv_get                      (<link linkend="EStrv">EStrv</link> *strv,
                                             <link linkend="int">int</link> index);</programlisting>
<para>
Retrieve a string by index.  This function works
identically on both packed and unpacked strv's, although
may be much slower on a packed strv.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>strv</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-strv-destroy" role="function"/>e_strv_destroy ()</title>
<indexterm><primary>e_strv_destroy</primary></indexterm><programlisting><link linkend="void">void</link>        e_strv_destroy                  (<link linkend="EStrv">EStrv</link> *strv);</programlisting>
<para>
Free a strv and all associated memory.  Works on packed
or unpacked strv's.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>strv</parameter>&nbsp;:</term>
<listitem><simpara> 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="EPoolv" role="struct"/>EPoolv</title>
<indexterm><primary>EPoolv</primary></indexterm><programlisting>typedef struct _EPoolv EPoolv;</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="e-poolv-new" role="function"/>e_poolv_new ()</title>
<indexterm><primary>e_poolv_new</primary></indexterm><programlisting><link linkend="EPoolv">EPoolv</link>*     e_poolv_new                     (unsigned <link linkend="int">int</link> size);</programlisting>
<para>
create a new poolv (string vector which shares a global string
pool).  poolv's can be used to work with arrays of strings which
save memory by eliminating duplicated allocations of the same
string.
</para>
<para>
this is useful when you have a log of read-only strings that do not
go away and are duplicated a lot (such as email headers).
</para>
<para>
we should probably in the future ref count the strings contained in
the hash table, but for now let's not.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>size</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> new pooled string vector
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-poolv-cpy" role="function"/>e_poolv_cpy ()</title>
<indexterm><primary>e_poolv_cpy</primary></indexterm><programlisting><link linkend="EPoolv">EPoolv</link>*     e_poolv_cpy                     (<link linkend="EPoolv">EPoolv</link> *dest,
                                             const <link linkend="EPoolv">EPoolv</link> *src);</programlisting>
<para>
Copy the contents of a pooled string vector</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>dest</parameter>&nbsp;:</term>
<listitem><simpara> destination pooled string vector
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>src</parameter>&nbsp;:</term>
<listitem><simpara> source pooled string vector
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <parameter>dest</parameter>, which may be re-allocated if the strings
are different lengths.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-poolv-set" role="function"/>e_poolv_set ()</title>
<indexterm><primary>e_poolv_set</primary></indexterm><programlisting><link linkend="EPoolv">EPoolv</link>*     e_poolv_set                     (<link linkend="EPoolv">EPoolv</link> *poolv,
                                             <link linkend="int">int</link> index,
                                             <link linkend="char">char</link> *str,
                                             <link linkend="int">int</link> freeit);</programlisting>
<para>
Set a string vector reference.  If the caller will no longer be
referencing the string, freeit should be TRUE.  Otherwise, this
will duplicate the string if it is not found in the pool.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>poolv</parameter>&nbsp;:</term>
<listitem><simpara> pooled string vector
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index</parameter>&nbsp;:</term>
<listitem><simpara> index in vector of string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str</parameter>&nbsp;:</term>
<listitem><simpara> string to set
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>freeit</parameter>&nbsp;:</term>
<listitem><simpara> whether the caller is releasing its reference to the
string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <parameter>poolv</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-poolv-get" role="function"/>e_poolv_get ()</title>
<indexterm><primary>e_poolv_get</primary></indexterm><programlisting>const <link linkend="char">char</link>* e_poolv_get                     (<link linkend="EPoolv">EPoolv</link> *poolv,
                                             <link linkend="int">int</link> index);</programlisting>
<para>
Retrieve a string by index.  This could possibly just be a macro.
</para>
<para>
Since the pool is never freed, this string does not need to be
duplicated, but should not be modified.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>poolv</parameter>&nbsp;:</term>
<listitem><simpara> pooled string vector
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index</parameter>&nbsp;:</term>
<listitem><simpara> index in vector of string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> string at that index.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-poolv-destroy" role="function"/>e_poolv_destroy ()</title>
<indexterm><primary>e_poolv_destroy</primary></indexterm><programlisting><link linkend="void">void</link>        e_poolv_destroy                 (<link linkend="EPoolv">EPoolv</link> *poolv);</programlisting>
<para>
Free a pooled string vector.  This doesn't free the strings from
the vector, however.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>poolv</parameter>&nbsp;:</term>
<listitem><simpara> pooled string vector to free
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>