--- /dev/null
+.\" -*-nroff-*-
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.TH atom 3 "21 January 2001" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
+atom \- atom table manager
+.\" @atom_createtable
+.\" @atom_destroytable
+.\" @atom_intern
+.\" @atom_nintern
+.\" @atom_gensym
+.\" @atom_name
+.\" @atom_len
+.\" @atom_hash
+.\" @atom_mkiter
+.\" @atom_next
+.\"
+.\" @ATOM_GLOBAL
+.\" @INTERN
+.\" @GENSYM
+.\" @ATOM_NAME
+.\" @ATOM_LEN
+.\" @ATOM_HASH
+.\"
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/atom.h>"
+
+.BI "void atom_createtable(atom_table *" t );
+.BI "void atom_destroytable(atom_table *" t );
+
+.BI "atom *atom_intern(atom_table *" t ", const char *" p );
+.BI "atom *atom_nintern(atom_table *" t ", const char *" p ", size_t " n );
+.BI "atom *atom_gensym(atom_table *" t );
+.BI "atom *INTERN(const char *" p );
+.BI "atom *GENSYM;"
+
+.BI "const char *atom_name(const atom *" a );
+.BI "size_t atom_len(const atom *" a );
+.BI "uint32 atom_hash(const atom *" a );
+.BI "const char *ATOM_NAME(const atom *" a );
+.BI "size_t ATOM_LEN(const atom *" a );
+.BI "uint32 ATOM_HASH(const atom *" a );
+
+.BI "void atom_mkiter(atom_iter *" i ", atom_table *" t );
+.BI "atom *atom_next(atom_iter *" i );
+
+.BI "extern atom_table *ATOM_GLOBAL;"
+.fi
+.SH DESCRIPTION
+The
+.B atom
+functions and macros implement a data type similar to immutable strings,
+with an additional property: that the addresses of two atoms from the
+same table are equal if and only if they contain the same text. Atom
+strings don't have to be null-terminated, although the interface is
+simpler if you know that all of your atoms are null-terminated. It's
+also possible to make
+.IR "uninterned atoms" :
+see below.
+.PP
+If a necessary memory allocation fails during an atom operation, the
+exception
+.B EXC_NOMEM
+is raised.
+.PP
+Atoms are useful for speeding up string comparisons, and for saving
+memory when many possibly-identical strings need storing.
+.PP
+There is a global atom table, named
+.BR ATOM_GLOBAL ,
+available for general use. You can initialize your own atom table if
+either you want to ensure that the atoms are not shared with some other
+table, or if you want to be able to free the atoms later. Private atom
+tables have the type
+.BR atom_table ;
+initialize it using the function
+.B atom_createtable
+and free it when you're finished using
+.BR atom_destroytable .
+.SS "Creating atoms from strings"
+The process of making atoms from strings is called
+.IR interning .
+The function
+.B atom_nintern
+takes an atom table, a string, and a length, and returns an atom with
+the same text. If your string is null-terminated, you can instead use
+.B atom_intern
+which has no length argument; if, in addition, you want to use the
+global atom table, you can use the single-argument
+.B INTERN
+macro, which takes just a null-terminated string.
+.PP
+A terminating null byte is always appended to an atom name. This is not
+considered to be a part of the name itself, and does not contribute to
+the atom's length as reported by the
+.B ATOM_LEN
+macro.
+.SS "Uninterned atoms"
+You can make an atom which is guaranteed to be distinct from every other
+atom, and has no sensible text string, by calling
+.BR atom_gensym ,
+passing it the address of your atom table. The macro
+.B GENSYM
+(which doesn't look like a function, and has no parentheses following
+it!) will return a unique atom from the global table. Uninterned atoms
+have a generated name of the form
+.RB ` *gen- \fInnn * '
+where
+.I nnn
+is an atom-table-specific sequence number. This text is there as a
+debugging convenience, and doesn't mean that the uninterned atom has the
+same address as an interned atom with the same text.
+.SS "Other enquiries about atoms"
+Atoms can be interrogated to find their names and hashes. The macro
+.B ATOM_NAME
+returns a pointer to the atom's name (its text);
+.B ATOM_LEN
+returns the length of the atom's name, excluding the terminating null;
+and
+.B ATOM_HASH
+returns the atom's hash value, which is useful if you want to use the
+atom as a key in some other structure. There are lower-case function
+versions of these, which have the same effect. There is little point in
+using the functions.
+.SS "Enumerating atoms"
+You can iterate over the atoms in an atom table. The
+.B atom_mkiter
+function initializes an iterator object to iterate over a particular
+atom table;
+.B atom_next
+returns the next atom from the iterator. Atoms are not returned in any
+particular order.
+.SH SEE ALSO
+.BR assoc (3),
+.BR hash (3),
+.BR mLib (3).
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blobdiff