Index: ossp-pkg/sio/al.pod
RCS File: /v/ossp/cvs/ossp-pkg/sio/Attic/al.pod,v
co -q -kk -p'1.1' '/v/ossp/cvs/ossp-pkg/sio/Attic/al.pod,v' | diff -u /dev/null - -L'ossp-pkg/sio/al.pod' 2>/dev/null
--- ossp-pkg/sio/al.pod
+++ -	2024-05-21 19:55:05.131126276 +0200
@@ -0,0 +1,399 @@
+##
+##  OSSP al - Assembly Lists
+##  Copyright (c) 2002 Michael van Elst <mlelstv@dev.de.cw.net>
+##  Copyright (c) 2002 The OSSP Project <http://www.ossp.org/>
+##  Copyright (c) 2002 Cable & Wireless Deutschland <http://www.cw.com/de/>
+##
+##  This file is part of OSSP al, an abstract datatype of a data buffer
+##  that can assemble, move and truncate data but avoids actual copying.
+##
+##  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.
+##
+##  al.pod: assembly lists library manual page
+##
+
+=pod
+
+=head1 NAME
+
+B<OSSP al> - Assembly Lists
+
+=head1 VERSION
+
+B<OSSP al AL_VERSION_STR>
+
+=head1 SYNOPSIS
+
+=over 4
+
+=item B<Abstract Data Types>:
+
+al_rc_t,
+al_t,
+al_tx_t,
+al_td_t,
+al_chunk_t.
+
+=item B<Assembly List Operations>:
+
+al_create,
+al_destroy,
+al_append_bytes,
+al_prepend_bytes,
+al_attach_buffer,
+al_splice,
+al_bytes.
+
+=item B<Traversal Operations>:
+
+al_txalloc,
+al_txfree,
+al_traverse,
+al_traverse_next,
+al_traverse_cb.
+
+=item B<Convenience Operations>:
+
+al_flatten,
+al_copy.
+
+=item B<Chunk Operations>:
+
+al_chunk_len,
+al_chunk_span,
+al_chunk_ptr.
+
+=item B<Error Handling>:
+
+al_error.
+
+=back
+
+=head1 DESCRIPTION
+
+B<OSSP al> defines an abstract type of a data buffer that can
+assemble, move and truncate data but avoids actual copying.
+
+It provides the following key features:
+
+=over 4
+
+=back
+
+=head1 DATA TYPES
+
+B<OSSP al> uses five data types in its API:
+
+=over 4
+
+=item B<al_rc_t> (Return Code Type)
+
+This is an exported enumerated integer type with the following possible
+values:
+
+ AL_OK       Everything Ok
+ AL_ERR_ARG  Invalid Argument
+ AL_ERR_MEM  Not Enough Memory
+ AL_ERR_EOF  End Of Communication
+ AL_ERR_INT  Internal Error
+
+=item B<al_t> (Assembly List Type)
+
+This is an opaque data type representing a data buffer.
+Only pointers to this abstract data type are used in the API.
+
+=item B<al_tx_t> (Traversal Context Type)
+
+This is an opaque data type representing a the state of a buffer
+traversal operation. Only pointers to this abstract data type are
+used in the API.
+
+=item B<al_td_t> (Traversal Direction Type)
+
+This is an exported enumerated integer type with the following possible
+values:
+
+ AL_FORWARD    traverse list from beginning to end
+ AL_BACKWARD   traverse list from end to beginning
+
+=item B<al_chunk_t> (Chunk Type)
+
+This is an opaque data type representing a chunk of a buffer during
+a traversal operation. Only pointers to this abstract data type are
+used in the API. The B<al_chunk_t> type is used to generate a pointer
+and byte count to access the data in the buffer.
+
+=back
+
+=head1 FUNCTIONS
+
+B<OSSP al> provides a bunch of API functions, all modelled after the
+same prototype: "C<al_rc_t> C<al_>I<name>C<(al_>[C<chunk>]C<_t *,>
+...C<)>". This means every function returns C<al_rc_t> to indicate its
+success (C<AL_OK>) or failure (C<AL_ERR_XXX>) by returning a return code
+(the corresponding describing text can be determined by passing this
+return code to C<al_error>). Each function name starts with the common
+prefix C<al_> and receives a C<al_t> (or C<al_chunk_t>) object on which
+it operates as its first argument.
+
+=head2 Assembly List Operations
+
+=over 4
+
+=item al_rc_t B<al_create>(al_t **I<alp>);
+
+Create an assembly list abstraction object. 
+The object is stored in I<alp> on success.
+
+Example: C<al_t *al; sa_create(&al);>
+
+=item al_rc_t B<al_destroy>(al_t *I<al>);
+
+Destroy an assembly list abstraction object.
+The object I<al> is invalid after this call succeeded.
+
+Example: C<al_destroy(al);>
+
+=item al_rc_t B<al_append_bytes>(al_t *I<al>, const char *I<src>, size_t I<n>);
+
+Append I<n> bytes from a storage array at I<src> to the assembly list, the
+bytes are copied, memory is allocated as necessary.
+
+Example: C<al_append_bytes(al, "Goodbye cruel world\n", 20);>
+
+=item al_rc_t B<al_prepend_bytes>(al_t *I<al>, const char *I<src>, size_t I<n>);
+
+Prepend I<n> bytes from a storage array at I<src> to the assembly list, the
+bytes are copied, memory is allocated as necessary.
+
+Example: C<al_prepend_bytes(al, "Hello world\n", 12);>
+
+=item al_rc_t B<al_attach_buffer>(al_t *I<al>, char *I<p>, size_t I<n>);
+
+Attach the storage array starting at I<p> with size <n> at the end of
+the assembly list. Its content will become part of the assembly list
+and is subject to assembly list operations. The storage array must stay
+in scope for the whole life time of the assembly list, there is no way
+to detach it from the assembly list.
+
+Example: C<char store[] = "foo\n"; al_attach_buffer(al, store, sizeof(store));>
+
+=item al_rc_t B<al_splice>(al_t *I<al>, size_t I<off>, size_t I<n>, al_t *I<nal>, al_t *I<tal>);
+
+This is the general data move operation modelled after the perl operator
+B<splice>.
+
+I<off> and I<n> are byte counts that define a span of bytes within the
+source assembly list I<al>. These bytes are moved to the target list
+I<tal> while the content of the new list I<nal> is moved to the source
+to replace the selected span.
+
+There are two deviations from the perl operator to avoid copying:
+
+The move to the target list I<tal> appends the data to its end.
+The move from the new list I<nal> removes the data from its origin.
+
+The target list I<tal> may be B<NULL>, the data bytes that would
+be moved to the target are then discard. This avoids creation
+and destruction of a dummy target.
+
+The new list I<nal> may be B<NULL>, then nothing is inserted into
+the source. This avoids creation and destruction of an empty list.
+
+Examples:
+
+ al_t *source;
+ al_t *insertion;
+ al_t *buffer;
+
+ al_create(&source);
+ al_create(&insertion);
+ al_create(&buffer);
+
+ al_append_bytes(source, "Hello world\n", 12);
+ al_append_bytes(insertion, "Goodbye cruel", 13);
+
+ al_splice(source, 0, 5, insertion, buffer);
+
+The buffer now holds the string "Hello".
+The source now holds the string "Goodbye cruel world\n".
+The insertion is now empty.
+
+ al_append_bytes(insertion, "brave", 5);
+ al_splice(source, 8, 5, insertion, NULL);
+
+The source now holds the string "Goodbye brave world\n".
+The insertion is now empty.
+
+ al_append_bytes(insertion, "B", 1);
+ al_splice(source, 0, 8, NULL, buffer);
+ al_splice(source, 0, 1, insertion, NULL);
+ al_append_bytes(insertion, "\n", 1);
+ al_splice(buffer, al_bytes(buffer)-1, 1, insertion, NULL),
+
+The source now holds the string "Brave world\n".
+The buffer now holds the string "HelloGoodbye\n".
+The insertion is empty.
+
+=item size_t B<al_bytes>(const al_t *I<al>);
+
+Returns the number of bytes stored in the assembly list.
+
+Example: C<al_t *al; size_t count; count = al_bytes(al);>
+
+=back
+
+=head2 Traversal Operations
+
+=over 4
+
+=item al_rc_t B<al_txalloc>(al_t *I<al>, al_tx_t **txp);
+
+Allocate a traversal context.
+
+Example: C<al_tx_t *tx; al_txalloc(&tx);>
+
+=item al_rc_t B<al_free>(al_t *I<al>, al_tx_t *tx);
+
+Free a traversal context.
+
+Example: C<al_tx_t *tx; al_txfree(tx);>
+
+=item al_rc_t B<al_traverse>(al_t *I<al>, size_t I<off>, size_t I<n>, al_td_t I<dir>, al_tx_t *I<tx>);
+
+Start traversing the assembly list I<al> beginning at byte offset I<off>
+for up to I<n> bytes in direction I<dir>. The state of the traversal is
+stored in the supplied context I<tx>.
+
+This function fails when the offset is outside the assembly list bounds.
+
+=item al_rc_t B<al_traverse_next>(al_t *I<al>, al_tx_t *I<tx>, al_chunk_t **I<alcp>);
+
+Complete a traversal step on the assembly list I<al> using the initialized
+context I<tx>. In each step a chunk descriptor is filled and stored in
+I<alcp>. All bytes of the chunk are guaranteed to be stored in a flat
+array and can be accessed through the chunk operations described below.
+
+The function returns AL_ERR_EOF when it passes the end (or beginning
+in case of backward traversal) of the list.
+
+=item al_rc_t B<al_traverse_cb>(al_t *I<al>, size_t I<off>, size_t I<n>, al_td_t I<dir>, al_rc_t (*I<cb>)(al_chunk_t *, void *), void *u);
+
+B<al_traverse_cb> is a wrapper function that does a full list traversal in
+a single call. In every step a chunk descriptor is passed to the callback
+function I<cb> together with a user supplied pointer I<u>. When the
+callback function returns anything but AL_OK the traversal is aborted
+and B<al_traverse_cb> returns with that result code.
+
+=back
+
+=head2 Convenience Operations
+
+=over 4
+
+=item al_rc_t B<al_flatten>(al_t *I<al>, size_t I<off>, size_t I<n>, char *I<dst>, size_t *I<lenp>);
+
+I<off> and I<n> are byte counts that define a span of bytes with the
+assembly list I<al>. These bytes are copied to the storage array I<dst>
+which must be sized appropriately.
+I<off> must be a valid offset, I<n> must be positive but may exceed
+the size of the assembly list.
+The actual number of bytes that is copied to the destination is stored
+in I<lenp>.
+
+Example:
+
+ al_t *al;
+ char buffer[42];
+ size_t actual;
+
+ al_flatten(al, 500, 42, buffer, &actual);
+
+=item al_rc_t B<al_copy>(al_t *I<al>, size_t I<off>, size_t I<n>, al_t *I<tal);
+
+I<off> and I<n> are byte counts that define a span of bytes within the
+assembly list I<al>. These bytes are appended to the target list I<tal>,
+memory is allocated as necessary.
+I<off> must be a valid offset, I<n> must be positive but may exceed
+the size of the assembly list.
+
+Example:
+
+ al_t *al;
+ al_t *tal;
+
+ al_create(&tal);
+ al_flatten(al, 500, 42, tal);
+
+=back
+
+=head2 Chunk Operations
+
+=over 4
+
+=item size_t B<al_chunk_len>(al_chunk_t *I<alc>);
+
+Returns the number of bytes in a chunk.
+
+=item size_t B<al_chunk_span>(al_chunk_t *I<alc>, size_t I<off>, size_t I<n>);
+
+I<off> and I<n> are byte counts that define a span of bytes.
+B<al_chunk_span> returns the number of bytes that are stored in the chunk.
+I<off> must be a valid offset, I<n> must be positive but may exceed
+the size of the chunk.
+
+=item char *B<al_chunk_ptr>(al_chunk_t *I<alc>, size_t I<off>);
+
+Returns the pointer to the byte at offset I<off> within the chunk I<alc>.
+I<off> must be positive and must not exceed the size of the chunk.
+Since all bytes of the chunk are guaranteed to be stored in a flat
+array the pointer can be used to reference every byte within the chunk.
+
+Example:
+
+ al_chunk_t *alc;
+ char *start, *end;
+
+ start = al_chunk_ptr(alc, 0);
+ end   = start + al_chunk_len(alc) - 1;
+
+=back
+
+=head2 Error Handling
+
+=over 4
+
+=item const char *B<al_error>(al_rc_t I<rv>);
+
+=back
+
+=head1 SEE ALSO
+
+=head1 HISTORY
+
+B<OSSP al> was invented in October 2002 by Michael van Elst
+E<lt>mlelstv@dev.de.cw.netE<gt> for use inside the OSSP project.
+
+=head1 AUTHORS
+
+ Michael van Elst
+ mlelstv@dev.de.cw.net
+
+=cut
+