##
##  OSSP act - Abstract Container Types
##  Copyright (c) 1999-2003 Ralf S. Engelschall <rse@engelschall.com>
##  Copyright (c) 1999-2003 The OSSP Project <http://www.ossp.org/>
##
##  This file is part of OSSP act, an abstract container type library
##  which can be found at http://www.ossp.org/pkg/lib/act/.
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
##  SUCH DAMAGE.
##
##  act.pod: manual page
##

=pod

=head1 NAME

B<OSSP act> -- B<A>bstracted B<C>ontainer B<T>ypes

=head1 GLOBAL SYNOPSIS

The following synopsis applies to all container types.

B<CONTAINER TYPE CONTEXT OBJECTS>

=over 4

=item act_ctx_t I<ctx>;

Declare a context object I<ctx> for container type I<ds>.

=item act_ctx_t B<act_ctx_new>(void);

Create a new context object, initialized
with default context information.

=item act_ctx_t B<act_ctx_dup>(act_ctx_t I<ctx>);

Duplicate context object I<ctx>.

=item void B<act_ctx_reset>(act_ctx_t I<ctx>);

Reset object to default ingredients.

=item long B<act_ctx_ctrl>(act_ctx_t I<ctx>, I<cmd>, ...)

Control or query various ingredients of context object I<ctx> by sending it
the command I<cmd>. The following I<cmd>s exists for all container types: ...

=item void B<act_ctx_free>(act_ctx_t I<ctx>);

Destroy the context object I<ctx>.

=back

B<CONTAINER TYPE OBJECTS>

=over 4

=item I<ds>_t I<obj>;

Declare an object I<obj> of a container type I<ds>.

=item I<ds>_t I<ds>_B<new>(I<ds>_ctx_t I<ctx>, ...);

Create a new (empty) object of container type I<ds>. Usually one also
specifies the type or size of the to be contained data.

=item I<ds>_ctx_t I<ds>_B<dup>(I<ds>_t I<obj>);

Duplicate object I<ctx>.

=item void I<ds>_B<reset>(I<ds>_t I<obj>);

Clean out the object.

=item I<ds>_t I<ds>_B<s2i>(I<ds>_t *I<obj>, unsigned char **I<sbuf>, long I<slen>);

Create a new (initialized) object of container type I<ds> in object I<obj>
from an object stream (previously created with a I<ds>_B<i2s>) under I<sbuf>
with len I<slen>. The pointer I<sbuf> is incremented by the number of actually
read bytes.

=item long I<ds>_B<i2s>(I<ds>_t I<obj>, unsigned char **I<sbuf>);

Streamline container type object I<obj> into an object stream under I<sbuf>.
Returns the number of written number bytes and increments I<sbuf> by this
number.

=item long I<ds>_B<ctrl>(I<ds>_t I<obj>, I<cmd>, ...)

Control or query various ingredients of container object I<obj> by sending it
the command I<cmd>. The following I<cmd>s exists for all container types:
I<DS>_C<CTRL_ELEMENTS> (peeks the number of contained data elements),
I<DS>_C<CTRL_BYTES> (peeks the total number of memory bytes the object is
in size), I<DS>_C<CTRL_FUNC_MALLOC> (sets the malloc(3) function to use),
I<DS>_C<CTRL_FUNC_REALLOC> (sets the realloc(3) function to use),
I<DS>_C<CTRL_FUNC_FREE> (sets the free(3) function to use),
I<DS>_C<CTRL_FUNC_ERROR> (sets the fatal error function to use).

=item I<type> I<ds>_I<operation>(I<ds>_t I<obj>, [ I<...> ]);

Perform I<operation> on object I<obj> of container type I<ds>.
The available I<operation>s are dependent on the container type itself.
Read below for more details.

=item void I<ds>_B<free>(I<ds>_t I<obj>);

Destroy the object I<obj> of container type I<ds>.

=back

=head1 OVERVIEW

The following container type data structures exists:

=over 4

=item B<bits> - Bit Vector (Bit Mask)

A bit vector type implemented by an array of bits. The elements are of type
B<unsigned char:1>. The usual use case is a mathematical set or a feature set
mask.

Specific Operations: B<insert>(k,v), B<delete>(k), B<lookup>(k), B<iterate>.

=item B<buf> - Byte Buffer (Octet Stream)

A buffer type implemented by an array of bytes. The elements are of type
B<unsigned char>. The usual use case is an I/O buffer or the underlaying
object of a string type.

Specific Operations: B<resize>, B<seek>, B<lookup>, B<insert>, B<delete>, B<iterate>.

=item B<array> - Array

A generic array type implemented by a pointer array. The elements are
of type B<void *>. The usual use case is for stroring arbitrary data where
elements are accessed by index positions and where more read-only operations
are performed than read/write operations.
Specific Operations: B<seek>, B<insert>, B<delete>, B<lookup>, B<iterate>

=item B<list> - Linear List

This is a generic list type implemented by lineary chained nodes. The elements
are of type B<void *>. The usual use cases are sorted list, queue and stack
and where read/write operations occur often.
Specific Operations: B<seek>, B<lookup>, B<insert>, B<delete>, B<iterate>

=item B<tree> - Hierarchical Tree

This is a generic tree type implemented by hierachically chained nodes. The
elements are of type B<void *>. The usual use case is for storing hierachical
structures.
Specific Operations: B<seek>, B<lookup>, B<insert>, B<delete>, B<iterate>

=item B<hash> - Hashing Table

This is a generic table type implemented by a hash. The elements are of type
B<void *>. The usual use case is for storing elements which are accessed by a
unique key and where lookup operation occur more often than store operations.
Specific Operations: B<resize>, B<insert>, B<lookup>, B<delete>, B<iterate>

=back

=head1 DESCRIPTION

=head2 Bit Vector (bits)

B<Standard Operations>

=over 4

=item bits_t B<bits_new>(unsigned int I<num>);

Create a new bit vector with I<num> initial bits.

=item bits_t B<bits_s2i>(bits_t *I<obj>, unsigned char **I<sbuf>, long I<slen>);

Create bit vector object in I<obj> from I<sbuf>/I<slen>.

=item long B<bits_i2s>(bits_t I<obj>, unsigned char **I<sbuf>);

Streamline I<obj> into I<sbuf>.

=item long B<bits_ctrl>(bits_t I<obj>, I<cmd>, ...)

Send I<cmd> to bit vector object I<obj>.

=item void B<bits_free>(bits_t I<obj>);

Destroy the bit vector object I<obj>.

=back

B<Container Type Specific Operations>

=over 4

=item int B<bits_set>(bits_t I<obj>, I<num>);

Set the I<num> bit.

=item int B<bits_clear>(bits_t I<obj>, I<num>);

Clear the I<num> bit.

=item int B<bits_isset>(bits_t I<obj>, I<num>);

Test whether the I<num> bit is set.

=back

=head2 Byte Buffer (buf)

=head2 Array (array)

=head2 Linear List (list)

=head2 Hierarchical Tree (tree)

=head2 Hash Table (hash)

=cut