The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
DJBECKETT / Redland-1.0.5.4 / redland / raptor / docs / xml / section-sequence.xml 
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="raptor-section-sequence">
<refmeta>
<refentrytitle role="top_of_page">Sequence</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>RAPTOR Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Sequence</refname>
<refpurpose>Ordered sequence of items.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

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

<synopsis>



typedef     <link linkend="raptor-sequence">raptor_sequence</link>;
<link linkend="raptor-sequence">raptor_sequence</link>* <link linkend="raptor-new-sequence">raptor_new_sequence</link>        (<link linkend="raptor-sequence-free-handler">raptor_sequence_free_handler</link> *free_handler,
                                             <link linkend="raptor-sequence-print-handler">raptor_sequence_print_handler</link> *print_handler);
<link linkend="void">void</link>        <link linkend="raptor-free-sequence">raptor_free_sequence</link>            (<link linkend="raptor-sequence">raptor_sequence</link> *seq);
<link linkend="int">int</link>         <link linkend="raptor-sequence-size">raptor_sequence_size</link>            (<link linkend="raptor-sequence">raptor_sequence</link> *seq);
<link linkend="int">int</link>         <link linkend="raptor-sequence-set-at">raptor_sequence_set_at</link>          (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="int">int</link> idx,
                                             <link linkend="void">void</link> *data);
<link linkend="int">int</link>         <link linkend="raptor-sequence-push">raptor_sequence_push</link>            (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="void">void</link> *data);
<link linkend="int">int</link>         <link linkend="raptor-sequence-shift">raptor_sequence_shift</link>           (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="void">void</link> *data);
<link linkend="void">void</link>*       <link linkend="raptor-sequence-get-at">raptor_sequence_get_at</link>          (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="int">int</link> idx);
<link linkend="void">void</link>*       <link linkend="raptor-sequence-pop">raptor_sequence_pop</link>             (<link linkend="raptor-sequence">raptor_sequence</link> *seq);
<link linkend="void">void</link>*       <link linkend="raptor-sequence-unshift">raptor_sequence_unshift</link>         (<link linkend="raptor-sequence">raptor_sequence</link> *seq);
<link linkend="int">int</link>         <link linkend="raptor-compare-strings">raptor_compare_strings</link>          (const <link linkend="void">void</link> *a,
                                             const <link linkend="void">void</link> *b);
<link linkend="void">void</link>        <link linkend="raptor-sequence-sort">raptor_sequence_sort</link>            (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="int">int</link> (*compare) (const void *, const void *));
<link linkend="void">void</link>        <link linkend="raptor-sequence-print-string">raptor_sequence_print_string</link>    (<link linkend="char">char</link> *data,
                                             <link linkend="FILE:CAPS">FILE</link> *fh);
<link linkend="void">void</link>        <link linkend="raptor-sequence-print-uri">raptor_sequence_print_uri</link>       (<link linkend="char">char</link> *data,
                                             <link linkend="FILE:CAPS">FILE</link> *fh);
<link linkend="void">void</link>        <link linkend="raptor-sequence-set-print-handler">raptor_sequence_set_print_handler</link>
                                            (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="raptor-sequence-print-handler">raptor_sequence_print_handler</link> *print_handler);
<link linkend="void">void</link>        <link linkend="raptor-sequence-print">raptor_sequence_print</link>           (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="FILE:CAPS">FILE</link> *fh);
<link linkend="int">int</link>         <link linkend="raptor-sequence-join">raptor_sequence_join</link>            (<link linkend="raptor-sequence">raptor_sequence</link> *dest,
                                             <link linkend="raptor-sequence">raptor_sequence</link> *src);
</synopsis>
</refsynopsisdiv>









<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>
A utility class that provides access to small sequence of items
that grow at the end and require quick ordered and indexed access.
Can be used as a queue/FIFO but less efficiently than a stack
where the items are added and removed from the end.
</para>
</refsect1>

<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="raptor-sequence" role="typedef"/>raptor_sequence</title>
<indexterm><primary>raptor_sequence</primary></indexterm><programlisting>raptor_sequence* raptor_sequence;
</programlisting>
<para>
Raptor sequence class</para>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="raptor-new-sequence" role="function"/>raptor_new_sequence ()</title>
<indexterm><primary>raptor_new_sequence</primary></indexterm><programlisting><link linkend="raptor-sequence">raptor_sequence</link>* raptor_new_sequence        (<link linkend="raptor-sequence-free-handler">raptor_sequence_free_handler</link> *free_handler,
                                             <link linkend="raptor-sequence-print-handler">raptor_sequence_print_handler</link> *print_handler);</programlisting>
<para>
Constructor - create a new sequence with the given handlers.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>free_handler</parameter>&nbsp;:</term>
<listitem><simpara> handler to free a sequence item
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>print_handler</parameter>&nbsp;:</term>
<listitem><simpara> handler to print a sequence item to a FILE*
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="raptor-sequence"><type>raptor_sequence</type></link> or NULL on failure 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-free-sequence" role="function"/>raptor_free_sequence ()</title>
<indexterm><primary>raptor_free_sequence</primary></indexterm><programlisting><link linkend="void">void</link>        raptor_free_sequence            (<link linkend="raptor-sequence">raptor_sequence</link> *seq);</programlisting>
<para>
Destructor - free a <link linkend="raptor-sequence"><type>raptor_sequence</type></link></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>seq</parameter>&nbsp;:</term>
<listitem><simpara> sequence to destroy
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-sequence-size" role="function"/>raptor_sequence_size ()</title>
<indexterm><primary>raptor_sequence_size</primary></indexterm><programlisting><link linkend="int">int</link>         raptor_sequence_size            (<link linkend="raptor-sequence">raptor_sequence</link> *seq);</programlisting>
<para>
Get the size of a sequence.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>seq</parameter>&nbsp;:</term>
<listitem><simpara> sequence object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the sequence size (&gt;=0)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-sequence-set-at" role="function"/>raptor_sequence_set_at ()</title>
<indexterm><primary>raptor_sequence_set_at</primary></indexterm><programlisting><link linkend="int">int</link>         raptor_sequence_set_at          (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="int">int</link> idx,
                                             <link linkend="void">void</link> *data);</programlisting>
<para>
Replace/set an item in a sequence.
</para>
<para>
The item at the offset <parameter>idx</parameter> in the sequence is replaced with the
new item <parameter>data</parameter> (which may be NULL).  Any existing item is freed
with the sequence's free_handler.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>seq</parameter>&nbsp;:</term>
<listitem><simpara> sequence object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>idx</parameter>&nbsp;:</term>
<listitem><simpara> index into sequence to operate at
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara> new data item.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-sequence-push" role="function"/>raptor_sequence_push ()</title>
<indexterm><primary>raptor_sequence_push</primary></indexterm><programlisting><link linkend="int">int</link>         raptor_sequence_push            (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="void">void</link> *data);</programlisting>
<para>
Add an item to the end of the sequence.
</para>
<para>
This is efficient to perform. <link linkend="raptor-sequence"><type>raptor_sequence</type></link> is optimised
to append/remove from the end of the sequence.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>seq</parameter>&nbsp;:</term>
<listitem><simpara> sequence to add to
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara> item to add
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-sequence-shift" role="function"/>raptor_sequence_shift ()</title>
<indexterm><primary>raptor_sequence_shift</primary></indexterm><programlisting><link linkend="int">int</link>         raptor_sequence_shift           (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="void">void</link> *data);</programlisting>
<para>
Add an item to the start of the sequence.
</para>
<para>
This is in-efficient to perform.  <link linkend="raptor-sequence"><type>raptor_sequence</type></link> is optimised
to append to the end of the sequence.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>seq</parameter>&nbsp;:</term>
<listitem><simpara> sequence to add to
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara> item to add
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-sequence-get-at" role="function"/>raptor_sequence_get_at ()</title>
<indexterm><primary>raptor_sequence_get_at</primary></indexterm><programlisting><link linkend="void">void</link>*       raptor_sequence_get_at          (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="int">int</link> idx);</programlisting>
<para>
Retrieve an item at offset <parameter>index</parameter> in the sequence.
</para>
<para>
This is efficient to perform. <link linkend="raptor-sequence"><type>raptor_sequence</type></link> is optimised
to append/remove from the end of the sequence.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>seq</parameter>&nbsp;:</term>
<listitem><simpara> sequence to use
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>idx</parameter>&nbsp;:</term>
<listitem><simpara> index of item to get
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the object or NULL if <parameter>index</parameter> is out of range (0... sequence size-1)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-sequence-pop" role="function"/>raptor_sequence_pop ()</title>
<indexterm><primary>raptor_sequence_pop</primary></indexterm><programlisting><link linkend="void">void</link>*       raptor_sequence_pop             (<link linkend="raptor-sequence">raptor_sequence</link> *seq);</programlisting>
<para>
Retrieve the item at the end of the sequence.
</para>
<para>
This is efficient to perform.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>seq</parameter>&nbsp;:</term>
<listitem><simpara> sequence to use
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the object or NULL if the sequence is empty
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-sequence-unshift" role="function"/>raptor_sequence_unshift ()</title>
<indexterm><primary>raptor_sequence_unshift</primary></indexterm><programlisting><link linkend="void">void</link>*       raptor_sequence_unshift         (<link linkend="raptor-sequence">raptor_sequence</link> *seq);</programlisting>
<para>
Retrieve the item at the start of the sequence.
</para>
<para>
This is in-efficient to perform. <link linkend="raptor-sequence"><type>raptor_sequence</type></link> is optimised
to append/remove from the end of the sequence.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>seq</parameter>&nbsp;:</term>
<listitem><simpara> sequence to use
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the object or NULL if the sequence is empty
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-compare-strings" role="function"/>raptor_compare_strings ()</title>
<indexterm><primary>raptor_compare_strings</primary></indexterm><programlisting><link linkend="int">int</link>         raptor_compare_strings          (const <link linkend="void">void</link> *a,
                                             const <link linkend="void">void</link> *b);</programlisting>
<para>
Utility function for <link linkend="raptor-sequence-sort"><function>raptor_sequence_sort()</function></link> to compare a sequence of strings.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>a</parameter>&nbsp;:</term>
<listitem><simpara> pointer first string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>b</parameter>&nbsp;:</term>
<listitem><simpara> pointer to second string
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> comparison of <parameter>a</parameter> to <parameter>b</parameter> as strings
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-sequence-sort" role="function"/>raptor_sequence_sort ()</title>
<indexterm><primary>raptor_sequence_sort</primary></indexterm><programlisting><link linkend="void">void</link>        raptor_sequence_sort            (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="int">int</link> (*compare) (const void *, const void *));</programlisting>
<para>
The comparison function is compatible with that used for <link linkend="qsort"><function>qsort()</function></link>
and provides the addresses of pointers to the data that
must be dereferenced to get to the stored sequence data.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>seq</parameter>&nbsp;:</term>
<listitem><simpara> sequence to sort
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>compare</parameter>&nbsp;:</term>
<listitem><simpara> comparison function
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-sequence-print-string" role="function"/>raptor_sequence_print_string ()</title>
<indexterm><primary>raptor_sequence_print_string</primary></indexterm><programlisting><link linkend="void">void</link>        raptor_sequence_print_string    (<link linkend="char">char</link> *data,
                                             <link linkend="FILE:CAPS">FILE</link> *fh);</programlisting>
<para>
Helper function for printing a sequence of strings.
</para>
<para>
Intended for use as a <link linkend="raptor-sequence-print-handler"><type>raptor_sequence_print_handler</type></link> passed into
<link linkend="raptor-new-sequence"><function>raptor_new_sequence()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara> data item (a char*)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fh</parameter>&nbsp;:</term>
<listitem><simpara> file handle to print to
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-sequence-print-uri" role="function"/>raptor_sequence_print_uri ()</title>
<indexterm><primary>raptor_sequence_print_uri</primary></indexterm><programlisting><link linkend="void">void</link>        raptor_sequence_print_uri       (<link linkend="char">char</link> *data,
                                             <link linkend="FILE:CAPS">FILE</link> *fh);</programlisting>
<para>
Helper function for printing a sequence of URIs.
</para>
<para>
Intended for use as a <link linkend="raptor-sequence-print-handler"><type>raptor_sequence_print_handler</type></link> passed into
<link linkend="raptor-new-sequence"><function>raptor_new_sequence()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara> data item (a <link linkend="raptor-uri"><type>raptor_uri</type></link>)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fh</parameter>&nbsp;:</term>
<listitem><simpara> file handle to print to
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-sequence-set-print-handler" role="function"/>raptor_sequence_set_print_handler ()</title>
<indexterm><primary>raptor_sequence_set_print_handler</primary></indexterm><programlisting><link linkend="void">void</link>        raptor_sequence_set_print_handler
                                            (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="raptor-sequence-print-handler">raptor_sequence_print_handler</link> *print_handler);</programlisting>
<para>
Set the print handler for the sequence.
</para>
<para>
This is set in the <link linkend="raptor-new-sequence"><function>raptor_new_sequence()</function></link> constructor and can be
overridden here.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>seq</parameter>&nbsp;:</term>
<listitem><simpara> sequence
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>print_handler</parameter>&nbsp;:</term>
<listitem><simpara> print handler
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-sequence-print" role="function"/>raptor_sequence_print ()</title>
<indexterm><primary>raptor_sequence_print</primary></indexterm><programlisting><link linkend="void">void</link>        raptor_sequence_print           (<link linkend="raptor-sequence">raptor_sequence</link> *seq,
                                             <link linkend="FILE:CAPS">FILE</link> *fh);</programlisting>
<para>
Print the sequence contents using the print_handler to print the data items.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>seq</parameter>&nbsp;:</term>
<listitem><simpara> sequence to sort
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fh</parameter>&nbsp;:</term>
<listitem><simpara> file handle
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="raptor-sequence-join" role="function"/>raptor_sequence_join ()</title>
<indexterm><primary>raptor_sequence_join</primary></indexterm><programlisting><link linkend="int">int</link>         raptor_sequence_join            (<link linkend="raptor-sequence">raptor_sequence</link> *dest,
                                             <link linkend="raptor-sequence">raptor_sequence</link> *src);</programlisting>
<para>
Join two sequences moving all items from one sequence to the end of another.
</para>
<para>
After this operation, sequence src will be empty (zero size) but
will have the same item capacity as before.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>dest</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="raptor-sequence"><type>raptor_sequence</type></link> destination sequence
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>src</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="raptor-sequence"><type>raptor_sequence</type></link> source sequence
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>