<?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" id="raptor-section-sequence.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 id="raptor-section-sequence.synopsis" 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> (compareconst 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 id="raptor-section-sequence.description" 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 id="raptor-section-sequence.details" role="details"> <title role="details.title">Details</title> <refsect2 id="raptor-sequence" role="typedef"> <title>raptor_sequence</title> <indexterm zone="raptor-sequence"><primary>raptor_sequence</primary></indexterm><programlisting>raptor_sequence* raptor_sequence; </programlisting> <para> Raptor sequence class</para> <para> </para></refsect2> <refsect2 id="raptor-new-sequence" role="function"> <title>raptor_new_sequence ()</title> <indexterm zone="raptor-new-sequence"><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> :</term> <listitem><simpara> handler to free a sequence item </simpara></listitem></varlistentry> <varlistentry><term><parameter>print_handler</parameter> :</term> <listitem><simpara> handler to print a sequence item to a FILE* </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new <link linkend="raptor-sequence"><type>raptor_sequence</type></link> or NULL on failure </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-free-sequence" role="function"> <title>raptor_free_sequence ()</title> <indexterm zone="raptor-free-sequence"><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> :</term> <listitem><simpara> sequence to destroy </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-sequence-size" role="function"> <title>raptor_sequence_size ()</title> <indexterm zone="raptor-sequence-size"><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 number of items in a sequence.</para> <para> </para><variablelist role="params"> <varlistentry><term><parameter>seq</parameter> :</term> <listitem><simpara> sequence object </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the sequence size (>=0) </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-sequence-set-at" role="function"> <title>raptor_sequence_set_at ()</title> <indexterm zone="raptor-sequence-set-at"><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. The sequence takes ownership of the new data item. On failure, the item is freed immediately.</para> <para> </para><variablelist role="params"> <varlistentry><term><parameter>seq</parameter> :</term> <listitem><simpara> sequence object </simpara></listitem></varlistentry> <varlistentry><term><parameter>idx</parameter> :</term> <listitem><simpara> index into sequence to operate at </simpara></listitem></varlistentry> <varlistentry><term><parameter>data</parameter> :</term> <listitem><simpara> new data item. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> non-0 on failure </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-sequence-push" role="function"> <title>raptor_sequence_push ()</title> <indexterm zone="raptor-sequence-push"><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> The sequence takes ownership of the pushed item and frees it with the free_handler. On failure, the item is freed immediately.</para> <para> </para><variablelist role="params"> <varlistentry><term><parameter>seq</parameter> :</term> <listitem><simpara> sequence to add to </simpara></listitem></varlistentry> <varlistentry><term><parameter>data</parameter> :</term> <listitem><simpara> item to add </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> non-0 on failure </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-sequence-shift" role="function"> <title>raptor_sequence_shift ()</title> <indexterm zone="raptor-sequence-shift"><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> The sequence takes ownership of the shifted item and frees it with the free_handler. On failure, the item is freed immediately.</para> <para> </para><variablelist role="params"> <varlistentry><term><parameter>seq</parameter> :</term> <listitem><simpara> sequence to add to </simpara></listitem></varlistentry> <varlistentry><term><parameter>data</parameter> :</term> <listitem><simpara> item to add </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> non-0 on failure </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-sequence-get-at" role="function"> <title>raptor_sequence_get_at ()</title> <indexterm zone="raptor-sequence-get-at"><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> After this call the item is still owned by the sequence.</para> <para> </para><variablelist role="params"> <varlistentry><term><parameter>seq</parameter> :</term> <listitem><simpara> sequence to use </simpara></listitem></varlistentry> <varlistentry><term><parameter>idx</parameter> :</term> <listitem><simpara> index of item to get </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</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 id="raptor-sequence-pop" role="function"> <title>raptor_sequence_pop ()</title> <indexterm zone="raptor-sequence-pop"><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> Ownership of the item is transferred to the caller, i.e. caller is responsible of freeing the item.</para> <para> </para><variablelist role="params"> <varlistentry><term><parameter>seq</parameter> :</term> <listitem><simpara> sequence to use </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the object or NULL if the sequence is empty </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-sequence-unshift" role="function"> <title>raptor_sequence_unshift ()</title> <indexterm zone="raptor-sequence-unshift"><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> Ownership of the item is transferred to the caller, i.e. caller is responsible of freeing the item.</para> <para> </para><variablelist role="params"> <varlistentry><term><parameter>seq</parameter> :</term> <listitem><simpara> sequence to use </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the object or NULL if the sequence is empty </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-compare-strings" role="function"> <title>raptor_compare_strings ()</title> <indexterm zone="raptor-compare-strings"><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> :</term> <listitem><simpara> pointer first string </simpara></listitem></varlistentry> <varlistentry><term><parameter>b</parameter> :</term> <listitem><simpara> pointer to second string </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> comparison of <parameter>a</parameter> to <parameter>b</parameter> as strings </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-sequence-sort" role="function"> <title>raptor_sequence_sort ()</title> <indexterm zone="raptor-sequence-sort"><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> (compareconst 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> :</term> <listitem><simpara> sequence to sort </simpara></listitem></varlistentry> <varlistentry><term><parameter>compare</parameter> :</term> <listitem><simpara> comparison function </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-sequence-print-string" role="function"> <title>raptor_sequence_print_string ()</title> <indexterm zone="raptor-sequence-print-string"><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> :</term> <listitem><simpara> data item (a char*) </simpara></listitem></varlistentry> <varlistentry><term><parameter>fh</parameter> :</term> <listitem><simpara> file handle to print to </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-sequence-print-uri" role="function"> <title>raptor_sequence_print_uri ()</title> <indexterm zone="raptor-sequence-print-uri"><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> :</term> <listitem><simpara> data item (a <link linkend="raptor-uri"><type>raptor_uri</type></link>) </simpara></listitem></varlistentry> <varlistentry><term><parameter>fh</parameter> :</term> <listitem><simpara> file handle to print to </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-sequence-set-print-handler" role="function"> <title>raptor_sequence_set_print_handler ()</title> <indexterm zone="raptor-sequence-set-print-handler"><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> :</term> <listitem><simpara> sequence </simpara></listitem></varlistentry> <varlistentry><term><parameter>print_handler</parameter> :</term> <listitem><simpara> print handler </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-sequence-print" role="function"> <title>raptor_sequence_print ()</title> <indexterm zone="raptor-sequence-print"><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> :</term> <listitem><simpara> sequence to sort </simpara></listitem></varlistentry> <varlistentry><term><parameter>fh</parameter> :</term> <listitem><simpara> file handle </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2 id="raptor-sequence-join" role="function"> <title>raptor_sequence_join ()</title> <indexterm zone="raptor-sequence-join"><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> :</term> <listitem><simpara> <link linkend="raptor-sequence"><type>raptor_sequence</type></link> destination sequence </simpara></listitem></varlistentry> <varlistentry><term><parameter>src</parameter> :</term> <listitem><simpara> <link linkend="raptor-sequence"><type>raptor_sequence</type></link> source sequence </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> non-0 on failure </simpara></listitem></varlistentry> </variablelist></refsect2> </refsect1> </refentry>