14 .TH atom 3 "21 January 2001" "Straylight/Edgeware" "mLib utilities library"
16 atom \- atom table manager
18 .\" @atom_destroytable
37 .B "#include <mLib/atom.h>"
39 .B "typedef struct { ...\& } atom_table;"
40 .B "typedef struct { ...\& } atom;"
42 .BI "void atom_createtable(atom_table *" t );
43 .BI "void atom_destroytable(atom_table *" t );
45 .BI "atom *atom_intern(atom_table *" t ", const char *" p );
46 .BI "atom *atom_nintern(atom_table *" t ", const char *" p ", size_t " n );
47 .BI "atom *atom_gensym(atom_table *" t );
48 .BI "atom *INTERN(const char *" p );
51 .BI "const char *atom_name(const atom *" a );
52 .BI "size_t atom_len(const atom *" a );
53 .BI "uint32 atom_hash(const atom *" a );
54 .BI "const char *ATOM_NAME(const atom *" a );
55 .BI "size_t ATOM_LEN(const atom *" a );
56 .BI "uint32 ATOM_HASH(const atom *" a );
58 .BI "void atom_mkiter(atom_iter *" i ", atom_table *" t );
59 .BI "atom *atom_next(atom_iter *" i );
61 .BI "extern atom_table *ATOM_GLOBAL;"
66 functions and macros implement a data type similar to immutable strings,
67 with an additional property: that the addresses of two atoms from the
68 same table are equal if and only if they contain the same text. Atom
69 strings don't have to be null-terminated, although the interface is
70 simpler if you know that all of your atoms are null-terminated. It's
72 .IR "uninterned atoms" :
75 If a necessary memory allocation fails during an atom operation, the
80 Atoms are useful for speeding up string comparisons, and for saving
81 memory when many possibly-identical strings need storing.
83 There is a global atom table, named
85 available for general use. You can initialize your own atom table if
86 either you want to ensure that the atoms are not shared with some other
87 table, or if you want to be able to free the atoms later. Private atom
90 initialize it using the function
92 and free it when you're finished using
93 .BR atom_destroytable .
94 .SS "Creating atoms from strings"
95 The process of making atoms from strings is called
99 takes an atom table, a string, and a length, and returns an atom with
100 the same text. If your string is null-terminated, you can instead use
102 which has no length argument; if, in addition, you want to use the
103 global atom table, you can use the single-argument
105 macro, which takes just a null-terminated string.
107 A terminating null byte is always appended to an atom name. This is not
108 considered to be a part of the name itself, and does not contribute to
109 the atom's length as reported by the
112 .SS "Uninterned atoms"
113 You can make an atom which is guaranteed to be distinct from every other
114 atom, and has no sensible text string, by calling
116 passing it the address of your atom table. The macro
118 (which doesn't look like a function, and has no parentheses following
119 it!) will return a unique atom from the global table. Uninterned atoms
120 have a generated name of the form
121 .RB ` *gen- \fInnn * '
124 is an atom-table-specific sequence number. This text is there as a
125 debugging convenience, and doesn't mean that the uninterned atom has the
126 same address as an interned atom with the same text.
127 .SS "Other enquiries about atoms"
128 Atoms can be interrogated to find their names and hashes. The macro
130 returns a pointer to the atom's name (its text);
132 returns the length of the atom's name, excluding the terminating null;
135 returns the atom's hash value, which is useful if you want to use the
136 atom as a key in some other structure. There are lower-case function
137 versions of these, which have the same effect. There is little point in
139 .SS "Enumerating atoms"
140 You can iterate over the atoms in an atom table. The
142 function initializes an iterator object to iterate over a particular
145 returns the next atom from the iterator. Atoms are not returned in any
152 Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blob