ossp-pkg/act/act.pod
##
## 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
