14 .TH assoc 3 "23 January 2001" "Straylight/Edgeware" "mLib utilities library"
16 assoc \- tables indexed by atoms
28 .B "#include <mLib/assoc.h>"
30 .B "typedef struct { ...\& } assoc_table;"
31 .B "typedef struct { ...\& } assoc_base;"
33 .BI "void assoc_create(assoc_table *" t );
34 .BI "void assoc_destroy(assoc_table *" t );
36 .BI "void *assoc_find(assoc_table *" t ", atom *" a ", size_t " sz ", unsigned *" f );
37 .BI "void assoc_remove(assoc_table *" t ", void *" b );
39 .BI "atom *ASSOC_ATOM(const void *" p );
41 .BI "void assoc_mkiter(assoc_iter *" i ", assoc_table *" t );
42 .BI "void *assoc_next(assoc_iter *" i );
46 .I "association table"
47 is a data structure which maps atoms (see
49 to arbitrary values. It works in a similar way to the symbol tables
52 except that it uses atoms rather than blocks of data as keys.
58 table: the value structures must include an
62 There are three main data structures:
65 Keeps track of the information associated with a particular table.
68 The header which must be attached to the front of all the value objects.
71 An iterator object, used for enumerating all of the associations stored
74 All of the above structures should be considered
76 don't try looking inside.
77 .SS "Creation and destruction"
80 object itself needs to be allocated by the caller. It is initialized by
81 passing it to the function
83 After initialization, the table contains no entries.
85 Initializing an association table involves allocating some memory. If
86 this allocation fails, an
90 When an association table is no longer needed, the memory occupied by
91 the values and other maintenance structures can be reclaimed by calling
93 Any bits of user data attached to values should previously have been
95 .SS "Adding, searching and removing"
96 Most of the actual work is done by the function
98 It does both lookup and creation, depending on its arguments. To do its
99 job, it needs to know the following bits of information:
101 .BI "assoc_table *" t
102 A pointer to an association table to manipulate.
105 The address of the atom to use as a key.
108 The size of the value block to allocate if the key could not be found.
109 If this is zero, no value is allocated, and a null pointer is returned
110 to indicate an unsuccessful lookup.
113 The address of a `found' flag to set. This is an output parameter. On
116 will set the value of
118 to zero if the key could not be found, or nonzero if it was found. This
119 can be used to tell whether the value returned has been newly allocated,
120 or whether it was already in the table.
122 A symbol can be removed from the table by calling
124 passing the association table itself, and the value block that needs
126 .SS "Enquiries about associations"
129 to an association, the expression
131 has as its value a poinetr to the atom which is that association's key.
132 .SS "Enumerating associations"
133 Enumerating the values in an association table is fairly simple.
136 object from somewhere. Attach it to an association table by calling
138 and passing in the addresses of the iterator and the symbol table.
141 will return a different value from the association table, until all of
142 them have been enumerated, at which point,
144 returns a null pointer.
146 It's safe to remove the symbol you've just been returned by
148 However, it's not safe to remove any other symbol. So don't do that.
150 When you've finished with an iterator, it's safe to just throw it away.
151 You don't need to call any functions beforehand.
158 Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blob