Index: ossp-pkg/act/act.pod
RCS File: /v/ossp/cvs/ossp-pkg/act/act.pod,v
co -q -kk -p'1.2' '/v/ossp/cvs/ossp-pkg/act/act.pod,v' | diff -u /dev/null - -L'ossp-pkg/act/act.pod' 2>/dev/null
--- ossp-pkg/act/act.pod
+++ -	2024-04-25 08:26:07.054298294 +0200
@@ -0,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)
+