<refentry id="libstree-lst-string">
<refmeta>
<refentrytitle>lst_string</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBSTREE Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>lst_string</refname><refpurpose></refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>



#define     <link linkend="LST-STRING-END:CAPS">LST_STRING_END</link>
#define     <link linkend="LST-EMPTY-STRING:CAPS">LST_EMPTY_STRING</link>
<link linkend="void">void</link>        (<link linkend="LST-StringCB">*LST_StringCB</link>)                 (<link linkend="LST-String">LST_String</link> *string,
                                             <link linkend="void">void</link> *data);
<link linkend="int">int</link>         (<link linkend="LST-StringItemCmpFunc">*LST_StringItemCmpFunc</link>)        (<link linkend="void">void</link> *item1,
                                             <link linkend="void">void</link> *item2);
<link linkend="char">char</link>*       (<link linkend="LST-StringPrintFunc">*LST_StringPrintFunc</link>)          (<link linkend="LST-StringIndex">LST_StringIndex</link> *index);
<link linkend="void">void</link>        (<link linkend="LST-StringItemCopyFunc">*LST_StringItemCopyFunc</link>)       (<link linkend="void">void</link> *src,
                                             <link linkend="void">void</link> *dst);
<link linkend="LST-String">LST_String</link>* <link linkend="lst-string-new">lst_string_new</link>                  (<link linkend="void">void</link> *data,
                                             <link linkend="u-int">u_int</link> item_size,
                                             <link linkend="u-int">u_int</link> num_items);
<link linkend="void">void</link>        <link linkend="lst-string-init">lst_string_init</link>                 (<link linkend="LST-String">LST_String</link> *string,
                                             <link linkend="void">void</link> *data,
                                             <link linkend="u-int">u_int</link> item_size,
                                             <link linkend="u-int">u_int</link> num_items);
<link linkend="void">void</link>        <link linkend="lst-string-free">lst_string_free</link>                 (<link linkend="LST-String">LST_String</link> *string);
<link linkend="void">void</link>*       <link linkend="lst-string-free-keep-data">lst_string_free_keep_data</link>       (<link linkend="LST-String">LST_String</link> *string);
<link linkend="u-int">u_int</link>       <link linkend="lst-string-get-length">lst_string_get_length</link>           (<link linkend="LST-String">LST_String</link> *string);
<link linkend="void">void</link>*       <link linkend="lst-string-get-item">lst_string_get_item</link>             (<link linkend="LST-String">LST_String</link> *string,
                                             <link linkend="u-int">u_int</link> index);
const <link linkend="char">char</link>* <link linkend="lst-string-print">lst_string_print</link>                (<link linkend="LST-String">LST_String</link> *string);
<link linkend="void">void</link>        <link linkend="lst-string-item-copy">lst_string_item_copy</link>            (<link linkend="LST-String">LST_String</link> *src,
                                             <link linkend="u-int">u_int</link> src_index,
                                             <link linkend="LST-String">LST_String</link> *dst,
                                             <link linkend="u-int">u_int</link> dst_index);
<link linkend="int">int</link>         <link linkend="lst-string-eq">lst_string_eq</link>                   (<link linkend="LST-String">LST_String</link> *s1,
                                             <link linkend="u-int">u_int</link> item1,
                                             <link linkend="LST-String">LST_String</link> *s2,
                                             <link linkend="u-int">u_int</link> item2);
<link linkend="u-int">u_int</link>       <link linkend="lst-string-items-common">lst_string_items_common</link>         (<link linkend="LST-String">LST_String</link> *s1,
                                             <link linkend="u-int">u_int</link> off1,
                                             <link linkend="LST-String">LST_String</link> *s2,
                                             <link linkend="u-int">u_int</link> off2,
                                             <link linkend="u-int">u_int</link> max_len);
<link linkend="char">char</link>*       <link linkend="lst-string-print-hex">lst_string_print_hex</link>            (<link linkend="LST-StringIndex">LST_StringIndex</link> *index);
<link linkend="LST-StringClass">LST_StringClass</link>* <link linkend="lst-stringclass-new">lst_stringclass_new</link>        (<link linkend="LST-StringItemCmpFunc">LST_StringItemCmpFunc</link> cmp_func,
                                             <link linkend="LST-StringItemCopyFunc">LST_StringItemCopyFunc</link> copy_func,
                                             <link linkend="LST-StringPrintFunc">LST_StringPrintFunc</link> print_func);
<link linkend="void">void</link>        <link linkend="lst-stringclass-free">lst_stringclass_free</link>            (<link linkend="LST-StringClass">LST_StringClass</link> *sclass);
<link linkend="void">void</link>        <link linkend="lst-stringclass-set-defaults">lst_stringclass_set_defaults</link>    (<link linkend="LST-StringItemCmpFunc">LST_StringItemCmpFunc</link> cmp_func,
                                             <link linkend="LST-StringItemCopyFunc">LST_StringItemCopyFunc</link> copy_func,
                                             <link linkend="LST-StringPrintFunc">LST_StringPrintFunc</link> print_func);
<link linkend="LST-StringClass">LST_StringClass</link>* <link linkend="lst-string-set-class">lst_string_set_class</link>       (<link linkend="LST-String">LST_String</link> *string,
                                             <link linkend="LST-StringClass">LST_StringClass</link> *sclass);
<link linkend="void">void</link>        <link linkend="lst-string-index-init">lst_string_index_init</link>           (<link linkend="LST-StringIndex">LST_StringIndex</link> *index);
<link linkend="void">void</link>        <link linkend="lst-string-index-copy">lst_string_index_copy</link>           (<link linkend="LST-StringIndex">LST_StringIndex</link> *src,
                                             <link linkend="LST-StringIndex">LST_StringIndex</link> *dst);
<link linkend="LST-StringSet">LST_StringSet</link>* <link linkend="lst-stringset-new">lst_stringset_new</link>            (void);
<link linkend="void">void</link>        <link linkend="lst-stringset-add">lst_stringset_add</link>               (<link linkend="LST-StringSet">LST_StringSet</link> *set,
                                             <link linkend="LST-String">LST_String</link> *string);
<link linkend="void">void</link>        <link linkend="lst-stringset-remove">lst_stringset_remove</link>            (<link linkend="LST-StringSet">LST_StringSet</link> *set,
                                             <link linkend="LST-String">LST_String</link> *string);
<link linkend="void">void</link>        <link linkend="lst-stringset-foreach">lst_stringset_foreach</link>           (<link linkend="LST-StringSet">LST_StringSet</link> *set,
                                             <link linkend="LST-StringCB">LST_StringCB</link> callback,
                                             <link linkend="void">void</link> *user_data);
<link linkend="void">void</link>        <link linkend="lst-stringset-free">lst_stringset_free</link>              (<link linkend="LST-StringSet">LST_StringSet</link> *set);
</synopsis>
</refsynopsisdiv>









<refsect1>
<title>Description</title>
<para>

</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="LST-STRING-END:CAPS">LST_STRING_END</title>
<indexterm><primary>LST_STRING_END</primary></indexterm><programlisting>#define LST_STRING_END   UINT_MAX
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="LST-EMPTY-STRING:CAPS">LST_EMPTY_STRING</title>
<indexterm><primary>LST_EMPTY_STRING</primary></indexterm><programlisting>#define LST_EMPTY_STRING UINT_MAX
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="LST-StringCB">LST_StringCB ()</title>
<indexterm><primary>LST_StringCB</primary></indexterm><programlisting><link linkend="void">void</link>        (*LST_StringCB)                 (<link linkend="LST-String">LST_String</link> *string,
                                             <link linkend="void">void</link> *data);</programlisting>
<para>
</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string passed in.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara> arbitrary user data.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="LST-StringItemCmpFunc">LST_StringItemCmpFunc ()</title>
<indexterm><primary>LST_StringItemCmpFunc</primary></indexterm><programlisting><link linkend="int">int</link>         (*LST_StringItemCmpFunc)        (<link linkend="void">void</link> *item1,
                                             <link linkend="void">void</link> *item2);</programlisting>
<para>
The function compares two string items.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>item1</parameter>&nbsp;:</term>
<listitem><simpara> first string item.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>item2</parameter>&nbsp;:</term>
<listitem><simpara> second string item.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> 0 when equal, -1 when the first item is
"smaller" than the second, 1 when the first is
"larger" than the second.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="LST-StringPrintFunc">LST_StringPrintFunc ()</title>
<indexterm><primary>LST_StringPrintFunc</primary></indexterm><programlisting><link linkend="char">char</link>*       (*LST_StringPrintFunc)          (<link linkend="LST-StringIndex">LST_StringIndex</link> *index);</programlisting>
<para>
The function creates a string representation of the
subrange of the string specified in <parameter>index</parameter> and returns
it. The result should be statically allocated and not need
to be freed by the caller. To make the function more robust you
should make it work even if it is called multiple times withing
the same <link linkend="printf"><function>printf()</function></link>-like function.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>index</parameter>&nbsp;:</term>
<listitem><simpara> substring specifier.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> string representation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="LST-StringItemCopyFunc">LST_StringItemCopyFunc ()</title>
<indexterm><primary>LST_StringItemCopyFunc</primary></indexterm><programlisting><link linkend="void">void</link>        (*LST_StringItemCopyFunc)       (<link linkend="void">void</link> *src,
                                             <link linkend="void">void</link> *dst);</programlisting>
<para>
Functions of this signature copy a string item at <parameter>src</parameter> over to a
string item at *dst.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>src</parameter>&nbsp;:</term>
<listitem><simpara> address of source item.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dst</parameter>&nbsp;:</term>
<listitem><simpara> address of destination item.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-new">lst_string_new ()</title>
<indexterm><primary>lst_string_new</primary></indexterm><programlisting><link linkend="LST-String">LST_String</link>* lst_string_new                  (<link linkend="void">void</link> *data,
                                             <link linkend="u-int">u_int</link> item_size,
                                             <link linkend="u-int">u_int</link> num_items);</programlisting>
<para>
The function creates <parameter>item_size</parameter> * <parameter>num_items</parameter> bytes of memory
and copies <parameter>data</parameter> into that area, then returns the new string.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara> data to store in string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>item_size</parameter>&nbsp;:</term>
<listitem><simpara> size of a single string item, in bytes.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>num_items</parameter>&nbsp;:</term>
<listitem><simpara> number of items the string stores.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> new string, or <literal>NULL</literal> when out of memory.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-init">lst_string_init ()</title>
<indexterm><primary>lst_string_init</primary></indexterm><programlisting><link linkend="void">void</link>        lst_string_init                 (<link linkend="LST-String">LST_String</link> *string,
                                             <link linkend="void">void</link> *data,
                                             <link linkend="u-int">u_int</link> item_size,
                                             <link linkend="u-int">u_int</link> num_items);</programlisting>
<para>
The function initializes an existing string object, making it
use the passed data directly without copying it. It is thus faster
than lst_string_new, and recommended for tight loops, etc.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string object to initialize.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara> string data to initialize with.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>item_size</parameter>&nbsp;:</term>
<listitem><simpara> size of a single string item, in bytes.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>num_items</parameter>&nbsp;:</term>
<listitem><simpara> length of string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-free">lst_string_free ()</title>
<indexterm><primary>lst_string_free</primary></indexterm><programlisting><link linkend="void">void</link>        lst_string_free                 (<link linkend="LST-String">LST_String</link> *string);</programlisting>
<para>
The function cleans up all of the memory occupied by <parameter>string</parameter>.
It is safe to call this on strings initialized using <link linkend="lst-string-init"><function>lst_string_init()</function></link>
which are using external data, as in that case the string data
itself is not touched.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string to clean up.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-free-keep-data">lst_string_free_keep_data ()</title>
<indexterm><primary>lst_string_free_keep_data</primary></indexterm><programlisting><link linkend="void">void</link>*       lst_string_free_keep_data       (<link linkend="LST-String">LST_String</link> *string);</programlisting>
<para>
The function cleans up the memory occupied by <parameter>string</parameter> without
releasing the actual string data, which it returns to the caller.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string to clean up.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> actual string data.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-get-length">lst_string_get_length ()</title>
<indexterm><primary>lst_string_get_length</primary></indexterm><programlisting><link linkend="u-int">u_int</link>       lst_string_get_length           (<link linkend="LST-String">LST_String</link> *string);</programlisting>
<para>
The function returns the number of items in the string. Always
use this function and never access any of the string members directly
to obtain that value.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string to return length of.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> length of <parameter>string</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-get-item">lst_string_get_item ()</title>
<indexterm><primary>lst_string_get_item</primary></indexterm><programlisting><link linkend="void">void</link>*       lst_string_get_item             (<link linkend="LST-String">LST_String</link> *string,
                                             <link linkend="u-int">u_int</link> index);</programlisting>
<para>
</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string to look up item in.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index</parameter>&nbsp;:</term>
<listitem><simpara> number of element in string to find, starting at 0.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a pointer to the element in the string at position <parameter>index</parameter>,
or <literal>NULL</literal> when the index is invalid.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-print">lst_string_print ()</title>
<indexterm><primary>lst_string_print</primary></indexterm><programlisting>const <link linkend="char">char</link>* lst_string_print                (<link linkend="LST-String">LST_String</link> *string);</programlisting>
<para>
The creates an ASCII string verions of <parameter>string</parameter> and returns it as
a pointer to static memory. The way this mapping is implemented depends
on the string class active for this string, see @<link linkend="lst-string-set-class"><function>lst_string_set_class()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string to print.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> pointer to static string buffer.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-item-copy">lst_string_item_copy ()</title>
<indexterm><primary>lst_string_item_copy</primary></indexterm><programlisting><link linkend="void">void</link>        lst_string_item_copy            (<link linkend="LST-String">LST_String</link> *src,
                                             <link linkend="u-int">u_int</link> src_index,
                                             <link linkend="LST-String">LST_String</link> *dst,
                                             <link linkend="u-int">u_int</link> dst_index);</programlisting>
<para>
The function copies the item found at <parameter>src_index</parameter> in <parameter>src</parameter> into the
item <parameter>dst_index</parameter> of string <parameter>dst</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>src</parameter>&nbsp;:</term>
<listitem><simpara> source string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>src_index</parameter>&nbsp;:</term>
<listitem><simpara> item in source string, starting at 0.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dst</parameter>&nbsp;:</term>
<listitem><simpara> destination string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dst_index</parameter>&nbsp;:</term>
<listitem><simpara> item to copy to.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-eq">lst_string_eq ()</title>
<indexterm><primary>lst_string_eq</primary></indexterm><programlisting><link linkend="int">int</link>         lst_string_eq                   (<link linkend="LST-String">LST_String</link> *s1,
                                             <link linkend="u-int">u_int</link> item1,
                                             <link linkend="LST-String">LST_String</link> *s2,
                                             <link linkend="u-int">u_int</link> item2);</programlisting>
<para>
The function compares the items specified via the input parameters.
The way this is implemented depends on the string class for the
strings involved, see <link linkend="lst-string-set-class"><function>lst_string_set_class()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>s1</parameter>&nbsp;:</term>
<listitem><simpara> first string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>item1</parameter>&nbsp;:</term>
<listitem><simpara> item in <parameter>s1</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>s2</parameter>&nbsp;:</term>
<listitem><simpara> second string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>item2</parameter>&nbsp;:</term>
<listitem><simpara> item in <parameter>s2</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> value &gt; 0 when equal, 0 otherwise.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-items-common">lst_string_items_common ()</title>
<indexterm><primary>lst_string_items_common</primary></indexterm><programlisting><link linkend="u-int">u_int</link>       lst_string_items_common         (<link linkend="LST-String">LST_String</link> *s1,
                                             <link linkend="u-int">u_int</link> off1,
                                             <link linkend="LST-String">LST_String</link> *s2,
                                             <link linkend="u-int">u_int</link> off2,
                                             <link linkend="u-int">u_int</link> max_len);</programlisting>
<para>
The function compares items in <parameter>s1</parameter> and <parameter>s2</parameter> from the given offsets,
counting how many are equal. The way the comparison works depends on
the string class active for the strings involved, see <link linkend="lst-string-set-class"><function>lst_string_set_class()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>s1</parameter>&nbsp;:</term>
<listitem><simpara> first string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>off1</parameter>&nbsp;:</term>
<listitem><simpara> item in <parameter>s1</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>s2</parameter>&nbsp;:</term>
<listitem><simpara> second string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>off2</parameter>&nbsp;:</term>
<listitem><simpara> item in <parameter>s2</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max_len</parameter>&nbsp;:</term>
<listitem><simpara> maximum number of items to compare.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> number of identical items.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-print-hex">lst_string_print_hex ()</title>
<indexterm><primary>lst_string_print_hex</primary></indexterm><programlisting><link linkend="char">char</link>*       lst_string_print_hex            (<link linkend="LST-StringIndex">LST_StringIndex</link> *index);</programlisting>
<para>
For convenience, this is a printer implementation that returns a hex
representation of the data contained in the string. You can call
this function up to three times from within the same <link linkend="printf"><function>printf()</function></link>-like
function.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>index</parameter>&nbsp;:</term>
<listitem><simpara> string region to print.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> hex representation in statically allocated string, copy
this if you need to keep it around.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-stringclass-new">lst_stringclass_new ()</title>
<indexterm><primary>lst_stringclass_new</primary></indexterm><programlisting><link linkend="LST-StringClass">LST_StringClass</link>* lst_stringclass_new        (<link linkend="LST-StringItemCmpFunc">LST_StringItemCmpFunc</link> cmp_func,
                                             <link linkend="LST-StringItemCopyFunc">LST_StringItemCopyFunc</link> copy_func,
                                             <link linkend="LST-StringPrintFunc">LST_StringPrintFunc</link> print_func);</programlisting>
<para>
Strings are made generic in libstree through virtualization of the
essential string operations. Each string in libstree has a string class
specifying how these operations are implemented. By default, the strings
support ASCII strings of single-byte characters as normally used. Using
this function, you can create your own string classes. If you want to
keep some of the default implementations, just pass <literal>NULL</literal> for those.
Get rid of the class using <link linkend="lst-stringclass-free"><function>lst_stringclass_free()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cmp_func</parameter>&nbsp;:</term>
<listitem><simpara> string item compare function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>copy_func</parameter>&nbsp;:</term>
<listitem><simpara> string item copy function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>print_func</parameter>&nbsp;:</term>
<listitem><simpara> string print function.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> new string class.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-stringclass-free">lst_stringclass_free ()</title>
<indexterm><primary>lst_stringclass_free</primary></indexterm><programlisting><link linkend="void">void</link>        lst_stringclass_free            (<link linkend="LST-StringClass">LST_StringClass</link> *sclass);</programlisting>
<para>
The function releases the memory occupied by <parameter>sclass</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>sclass</parameter>&nbsp;:</term>
<listitem><simpara> class to clean up.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-stringclass-set-defaults">lst_stringclass_set_defaults ()</title>
<indexterm><primary>lst_stringclass_set_defaults</primary></indexterm><programlisting><link linkend="void">void</link>        lst_stringclass_set_defaults    (<link linkend="LST-StringItemCmpFunc">LST_StringItemCmpFunc</link> cmp_func,
                                             <link linkend="LST-StringItemCopyFunc">LST_StringItemCopyFunc</link> copy_func,
                                             <link linkend="LST-StringPrintFunc">LST_StringPrintFunc</link> print_func);</programlisting>
<para>
This function sets new default string manipulation functions for all
strings. Beware, this will also implicitly change the implementations
for all previously created strings with default handlers. If you want
the original handler, pass <literal>NULL</literal> for the implementation desired.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cmp_func</parameter>&nbsp;:</term>
<listitem><simpara> string item compare function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>copy_func</parameter>&nbsp;:</term>
<listitem><simpara> string item copy function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>print_func</parameter>&nbsp;:</term>
<listitem><simpara> string print function.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-set-class">lst_string_set_class ()</title>
<indexterm><primary>lst_string_set_class</primary></indexterm><programlisting><link linkend="LST-StringClass">LST_StringClass</link>* lst_string_set_class       (<link linkend="LST-String">LST_String</link> *string,
                                             <link linkend="LST-StringClass">LST_StringClass</link> *sclass);</programlisting>
<para>
Use this function to set a string's class. Pass <literal>NULL</literal> to reset to
default class.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string to change string class for.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>sclass</parameter>&nbsp;:</term>
<listitem><simpara> new string class.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the previously set string class.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-index-init">lst_string_index_init ()</title>
<indexterm><primary>lst_string_index_init</primary></indexterm><programlisting><link linkend="void">void</link>        lst_string_index_init           (<link linkend="LST-StringIndex">LST_StringIndex</link> *index);</programlisting>
<para>
The function initializes a string index. Used internally.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>index</parameter>&nbsp;:</term>
<listitem><simpara> index initialized.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-string-index-copy">lst_string_index_copy ()</title>
<indexterm><primary>lst_string_index_copy</primary></indexterm><programlisting><link linkend="void">void</link>        lst_string_index_copy           (<link linkend="LST-StringIndex">LST_StringIndex</link> *src,
                                             <link linkend="LST-StringIndex">LST_StringIndex</link> *dst);</programlisting>
<para>
Used internally.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>src</parameter>&nbsp;:</term>
<listitem><simpara> source index.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dst</parameter>&nbsp;:</term>
<listitem><simpara> destination index.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-stringset-new">lst_stringset_new ()</title>
<indexterm><primary>lst_stringset_new</primary></indexterm><programlisting><link linkend="LST-StringSet">LST_StringSet</link>* lst_stringset_new            (void);</programlisting>
<para>
The function creates a new stringset. Stringsets are the way you
pass multiple strings to an algorithm. You basically create a string
set, then add strings to the set, pass the set to an algorithm, and
clean up the set afterwards.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> new, empty set.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-stringset-add">lst_stringset_add ()</title>
<indexterm><primary>lst_stringset_add</primary></indexterm><programlisting><link linkend="void">void</link>        lst_stringset_add               (<link linkend="LST-StringSet">LST_StringSet</link> *set,
                                             <link linkend="LST-String">LST_String</link> *string);</programlisting>
<para>
The function adds a string to the set.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>set</parameter>&nbsp;:</term>
<listitem><simpara> set to add string to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string to add.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-stringset-remove">lst_stringset_remove ()</title>
<indexterm><primary>lst_stringset_remove</primary></indexterm><programlisting><link linkend="void">void</link>        lst_stringset_remove            (<link linkend="LST-StringSet">LST_StringSet</link> *set,
                                             <link linkend="LST-String">LST_String</link> *string);</programlisting>
<para>
The function removes a string from a string set.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>set</parameter>&nbsp;:</term>
<listitem><simpara> set to remove string from.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> string to remove.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-stringset-foreach">lst_stringset_foreach ()</title>
<indexterm><primary>lst_stringset_foreach</primary></indexterm><programlisting><link linkend="void">void</link>        lst_stringset_foreach           (<link linkend="LST-StringSet">LST_StringSet</link> *set,
                                             <link linkend="LST-StringCB">LST_StringCB</link> callback,
                                             <link linkend="void">void</link> *user_data);</programlisting>
<para>
The function calls <parameter>callback</parameter> for each string in <parameter>set</parameter>, passing it
that string and <parameter>user_data</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>set</parameter>&nbsp;:</term>
<listitem><simpara> set to iterate.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
<listitem><simpara> callback to call for each item.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara> arbitrary data passed through to <parameter>callback</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="lst-stringset-free">lst_stringset_free ()</title>
<indexterm><primary>lst_stringset_free</primary></indexterm><programlisting><link linkend="void">void</link>        lst_stringset_free              (<link linkend="LST-StringSet">LST_StringSet</link> *set);</programlisting>
<para>
The function releases all the memory claimed by <parameter>set</parameter>, including
all the strings it contains.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>set</parameter>&nbsp;:</term>
<listitem><simpara> set to clean up.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
