, char *I, size_t I);
Attach the storage array starting at I with size I at the end of
the assembly list. Its content becomes 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
=item al_rc_t B(al_t *I, size_t I, size_t I, al_t *I, al_t *I);
This is the general data move operation modelled after the perl operator
B.
I and I are byte counts that define a span of bytes within the
source assembly list I. These bytes are moved to the target list
I while the content of the new list I 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 appends the data to its end.
The move from the new list I removes the data from its origin.
The target list I may be B, the data bytes that would
be moved to the target are then discarded. This avoids creation
and destruction of a dummy target.
The new list I may be B, 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(const al_t *I);
Returns the number of bytes stored in the assembly list.
Example: C
=back
=head2 Traversal Operations
=over 4
=item al_rc_t B(al_t *I, al_tx_t **txp);
Allocate a traversal context.
Example: C
=item al_rc_t B(al_t *I, al_tx_t *tx);
Free a traversal context.
Example: C
=item al_rc_t B(al_t *I, size_t I, size_t I, al_td_t I, al_tx_t *I);
Start traversing the assembly list I beginning at byte offset I
for up to I bytes in direction I. The state of the traversal is
stored in the supplied context I.
This function fails when the offset is outside the assembly list bounds.
=item al_rc_t B(al_t *I, al_tx_t *I, al_chunk_t **I);
Complete a traversal step on the assembly list I using the initialized
context I. In each step a chunk descriptor is filled and stored in
I. 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_t *I, size_t I, size_t I, al_td_t I, al_rc_t (*I)(al_chunk_t *, void *), void *u);
B 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 together with a user supplied pointer I. When the
callback function returns AL_OK the traversal continues, when it returns
AL_ERR_EOF the traversal is aborted and AL_OK is returned to the original
caller. Any other return code returned by the callback is passed to the
original caller verbatim.
=back
=head2 Convenience Operations
=over 4
=item al_rc_t B(al_t *I, size_t I, size_t I, char *I, size_t *I);
I and I are byte counts that define a span of bytes with the
assembly list I. These bytes are copied to the storage array I
which must be sized appropriately.
I must be a valid offset, I 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.
Example:
al_t *al;
char buffer[42];
size_t actual;
al_flatten(al, 500, 42, buffer, &actual);
=item al_rc_t B(al_t *I, size_t I, size_t I, al_t *I and I are byte counts that define a span of bytes within the
assembly list I. These bytes are appended to the target list I,
memory is allocated as necessary.
I must be a valid offset, I 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_t *I);
Returns the number of bytes in a chunk.
=item size_t B(al_chunk_t *I, size_t I, size_t I);
I and I are byte counts that define a span of bytes.
B returns the number of bytes that are stored in the chunk.
I must be a valid offset, I must be positive but may exceed
the size of the chunk.
=item char *B(al_chunk_t *I, size_t I);
Returns the pointer to the byte at offset I within the chunk I.
I 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_rc_t I);
=back
=head1 SEE ALSO
=head1 HISTORY
B was invented in October 2002 by Michael van Elst
Emlelstv@dev.de.cw.netE under contract with Cable & Wireless
Germany Ehttp://www.cw.com/deE for use inside the OSSP project
Ehttp://www.ossp.org/E.
=head1 AUTHORS
Michael van Elst
mlelstv@dev.de.cw.net
=cut