X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/7527ed0bc3b9987d6b468cf76cb8f55f1b4ff4db..1025598e92db95a8272dd79dcf2912684ac47c12:/man/assoc.3

diff --git a/man/assoc.3 b/man/assoc.3
new file mode 100644
index 0000000..86367fc
--- /dev/null
+++ b/man/assoc.3
@@ -0,0 +1,155 @@
+.\" -*-nroff-*-
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.TH assoc 3 "23 January 2001" mLib
+.SH NAME
+assoc \- tables indexed by atoms
+.\" @assoc_create
+.\" @assoc_destroy
+.\" @assoc_find
+.\" @assoc_remove
+.\" @assoc_mkiter
+.\" @assoc_next
+.\"
+.\" @ASSOC_ATOM
+.\"
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/assoc.h>"
+
+.BI "void assoc_create(assoc_table *" t );
+.BI "void assoc_destroy(assoc_table *" t );
+
+.BI "void *assoc_find(assoc_table *" t ", atom *" a ", size_t " sz ", unsigned *" f );
+.BI "void assoc_remove(assoc_table *" t ", void *" b );
+
+.BI "atom *ASSOC_ATOM(const void *" p );
+
+.BI "void assoc_mkiter(assoc_iter *" i ", assoc_table *" t );
+.BI "void *assoc_next(assoc_iter *" i );
+.fi
+.SH DESCRIPTION
+An
+.I "association table"
+is a data structure which maps atoms (see
+.BR atom (3))
+to arbitrary values.  It works in a similar way to the symbol tables
+implemented by
+.BR sym (3),
+except that it uses atoms rather than blocks of data as keys.
+.PP
+Like
+.BR sym (3),
+it implements an
+.I intrusive
+table: the value structures must include an
+.B assoc_base
+structure.
+.PP
+There are three main data structures:
+.TP
+.B assoc_table
+Keeps track of the information associated with a particular table.
+.TP
+.B assoc_base
+The header which must be attached to the front of all the value objects.
+.TP
+.B assoc_iter
+An iterator object, used for enumerating all of the associations stored
+in the table
+.PP
+All of the above structures should be considered
+.IR opaque :
+don't try looking inside.
+.SS "Creation and destruction"
+The
+.B assoc_table
+object itself needs to be allocated by the caller.  It is initialized by
+passing it to the function
+.BR assoc_create .
+After initialization, the table contains no entries.
+.PP
+Initializing an association table involves allocating some memory.  If
+this allocation fails, an
+.B EXC_NOMEM
+exception is raised.
+.PP
+When an association table is no longer needed, the memory occupied by
+the values and other maintenance structures can be reclaimed by calling
+.BR assoc_destroy .
+Any bits of user data attached to values should previously have been
+destroyed.
+.SS "Adding, searching and removing"
+Most of the actual work is done by the function
+.BR assoc_find .
+It does both lookup and creation, depending on its arguments.  To do its
+job, it needs to know the following bits of information:
+.TP
+.BI "assoc_table *" t
+A pointer to an association table to manipulate.
+.TP
+.BI "atom *" a
+The address of the atom to use as a key.
+.TP
+.BI "size_t " sz
+The size of the value block to allocate if the key could not be found.
+If this is zero, no value is allocated, and a null pointer is returned
+to indicate an unsuccessful lookup.
+.TP
+.BI "unsigned *" f
+The address of a `found' flag to set.  This is an output parameter.  On
+exit,
+.B assoc_find
+will set the value of
+.BI * f
+to zero if the key could not be found, or nonzero if it was found.  This
+can be used to tell whether the value returned has been newly allocated,
+or whether it was already in the table.
+.PP
+A symbol can be removed from the table by calling
+.BR assoc_remove ,
+passing the association table itself, and the value block that needs
+removing.
+.SS "Enquiries about associations"
+Given a pointer
+.I a
+to an association, the expression
+.BI ASSOC_ATOM( a )
+has as its value a poinetr to the atom which is that association's key.
+.SS "Enumerating associations"
+Enumerating the values in an association table is fairly simple.
+Allocate an
+.B assoc_iter
+object from somewhere.  Attach it to an association table by calling
+.BR assoc_mkiter ,
+and passing in the addresses of the iterator and the symbol table.
+Then, each call to
+.B assoc_next
+will return a different value from the association table, until all of
+them have been enumerated, at which point,
+.B assoc_next
+returns a null pointer.
+.PP
+It's safe to remove the symbol you've just been returned by
+.BR assoc_next .
+However, it's not safe to remove any other symbol.  So don't do that.
+.PP
+When you've finished with an iterator, it's safe to just throw it away.
+You don't need to call any functions beforehand.
+.SH SEE ALSO
+.BR atom (3),
+.BR hash (3),
+.BR sym (3),
+.BR mLib (3).
+.SH AUTHOR
+Mark Wooding, <mdw@nsict.org>