--- al.pod 2002/10/18 12:23:35 1.10
+++ al.pod 2002/10/22 15:33:16 1.11
@@ -79,6 +79,8 @@
al_chunk_len,
al_chunk_span,
+al_chunk_label,
+al_same_label,
al_chunk_ptr.
=item B<Error Handling>:
@@ -100,7 +102,7 @@
=head1 DATA TYPES
-B<OSSP al> uses five data types in its API:
+B<OSSP al> uses six data types in its API:
=over 4
@@ -141,6 +143,14 @@
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.
+=item B<al_label_t> (Label Type)
+
+This is a pointer type representing a specific data flavour. You
+can restrict traversal operations to data that was marked with
+the specific flavour. Usually you would cast a pointer to the
+object that maintains the data to B<al_label_t>. You may use
+NULL as a label but on traversal NULL matches any label.
+
=back
=head1 FUNCTIONS
@@ -172,21 +182,22 @@
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>);
+=item al_rc_t B<al_append_bytes>(al_t *I<al>, const char *I<src>, size_t I<n>, al_label_t I<label>);
Append I<n> bytes from a storage array at I<src> to the assembly line. The
-bytes are copied, memory is allocated as necessary.
+bytes are copied, memory is allocated as necessary. The data is tagged
+with I<label>.
-Example: C<al_append_bytes(al, "Goodbye cruel world\n", 20);>
+Example: C<al_append_bytes(al, "Goodbye cruel world\n", 20, NULL);>
-=item al_rc_t B<al_prepend_bytes>(al_t *I<al>, const char *I<src>, size_t I<n>);
+=item al_rc_t B<al_prepend_bytes>(al_t *I<al>, const char *I<src>, size_t I<n>, al_label_t I<label>);
Prepend I<n> bytes from a storage array at I<src> to the assembly line. The
bytes are copied, memory is allocated as necessary.
-Example: C<al_prepend_bytes(al, "Hello world\n", 12);>
+Example: C<al_prepend_bytes(al, "Hello world\n", 12, NULL);>
-=item al_rc_t B<al_attach_buffer>(al_t *I<al>, char *I<p>, size_t I<n>, void (*I<freemem>)(char *, size_t, void *), void *I<u>);
+=item al_rc_t B<al_attach_buffer>(al_t *I<al>, char *I<p>, size_t I<n>, al_label_t I<label>, void (*I<freemem>)(char *, size_t, void *), void *I<u>);
Attach the storage array starting at I<p> with size I<n> at the end of
the assembly line. Its content becomes part of the assembly line
@@ -197,7 +208,7 @@
for I<freemem> is valid, then no callback takes place, which might be
appropriate for static buffers.
-Example: C<char store[] = "foo\n"; al_attach_buffer(al, store, sizeof(store), NULL, NULL);>
+Example: C<char store[] = "foo\n"; al_attach_buffer(al, store, sizeof(store), NULL, NULL, NULL);>
=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>);
@@ -231,8 +242,8 @@
al_create(&insertion);
al_create(&buffer);
- al_append_bytes(source, "Hello world\n", 12);
- al_append_bytes(insertion, "Goodbye cruel", 13);
+ al_append_bytes(source, "Hello world\n", 12, NULL);
+ al_append_bytes(insertion, "Goodbye cruel", 13, NULL);
al_splice(source, 0, 5, insertion, buffer);
@@ -240,16 +251,16 @@
The source now holds the string "Goodbye cruel world\n".
The insertion is now empty.
- al_append_bytes(insertion, "brave", 5);
+ al_append_bytes(insertion, "brave", 5, NULL);
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_append_bytes(insertion, "B", 1, NULL);
al_splice(source, 0, 8, NULL, buffer);
al_splice(source, 0, 1, insertion, NULL);
- al_append_bytes(insertion, "\n", 1);
+ al_append_bytes(insertion, "\n", 1, NULL);
al_splice(buffer, al_bytes(buffer)-1, 1, insertion, NULL),
The source now holds the string "Brave world\n".
@@ -280,11 +291,12 @@
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>);
+=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_label_t I<label>, al_tx_t *I<tx>);
Start traversing the assembly line 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>.
+for up to I<n> bytes in direction I<dir>. If I<label> is not NULL then
+you will see only data that was tagged with I<label>. The state of the
+traversal is stored in the supplied context I<tx>.
This function fails when the offset is outside the assembly line bounds.
@@ -307,7 +319,7 @@
mandatory that every traversal that was started is finished by
a call to B<al_traverse_end> with I<final> set to a non-zero value.
-=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);
+=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_label_t I<label>, al_rc_t (*I<cb>)(al_chunk_t *, void *), void *u);
B<al_traverse_cb> is a wrapper function that does a full assembly line traversal in
a single call. In every step a chunk descriptor is passed to the callback
@@ -332,6 +344,10 @@
the size of the assembly line.
The actual number of bytes that is copied to the destination is stored
in I<lenp>.
+If I<dst> is NULL then no data is copied but the number of bytes is
+still counted in I<lenp>. This can be used to precalculate the size
+of the needed storage array by passing an arbitrary high maximum size
+as I<n>.
Example:
@@ -341,7 +357,7 @@
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);
+=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 line I<al>. These bytes are appended to the target assembly line I<tal>,
@@ -374,6 +390,16 @@
I<off> must be a valid offset, I<n> must be positive but may exceed
the size of the chunk.
+=item al_label_t B<al_chunk_label>(al_chunk_t *I<alc>);
+
+Return the label that was used to tag the data in I<alc>. This can
+be NULL.
+
+=item int B<al_same_label>(al_chunk_t *I<alc>, al_label_t *I<label>);
+
+Return true if I<label> matches the label that was used to tag the data
+in I<alc>. A NULL I<label> matches everything.
+
=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>.
|
