*** /dev/null Fri Apr 26 20:33:00 2024
--- - Fri Apr 26 20:34:22 2024
***************
*** 0 ****
--- 1,209 ----
+
+ =head1 NAME
+
+ B<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)
+
|
