chiark / gitweb /
Various manual fixes.
[mLib] / assoc.h
1 /* -*-c-*-
2  *
3  * $Id: assoc.h,v 1.3 2004/04/08 01:36:11 mdw Exp $
4  *
5  * Assocation tables
6  *
7  * (c) 2000 Straylight/Edgeware
8  */
9
10 /*----- Licensing notice --------------------------------------------------* 
11  *
12  * This file is part of the mLib utilities library.
13  *
14  * mLib is free software; you can redistribute it and/or modify
15  * it under the terms of the GNU Library General Public License as
16  * published by the Free Software Foundation; either version 2 of the
17  * License, or (at your option) any later version.
18  * 
19  * mLib is distributed in the hope that it will be useful,
20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
22  * GNU Library General Public License for more details.
23  * 
24  * You should have received a copy of the GNU Library General Public
25  * License along with mLib; if not, write to the Free
26  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
27  * MA 02111-1307, USA.
28  */
29
30 #ifndef MLIB_ASSOC_H
31 #define MLIB_ASSOC_H
32
33 #ifdef __cplusplus
34   extern "C" {
35 #endif
36
37 /*----- Header files ------------------------------------------------------*/
38
39 #ifndef MLIB_ATOM_H
40 #  include "atom.h"
41 #endif
42
43 #ifndef MLIB_HASH_H
44 #  include "hash.h"
45 #endif
46
47 /*----- Data structures ---------------------------------------------------*/
48
49 typedef struct assoc_table {
50   hash_table t;
51   size_t load;
52 } assoc_table;
53
54 typedef struct assoc_base {
55   hash_base b;
56   atom *a;
57 } assoc_base;
58
59 typedef struct { hash_iter i; } assoc_iter;
60
61 #define ASSOC_ATOM(p) (((assoc_base *)(p))->a + 0)
62
63 /*----- Functions provided ------------------------------------------------*/
64
65 /* --- @assoc_create@ --- *
66  *
67  * Arguments:   @assoc_table *t@ = pointer to an association table
68  *
69  * Returns:     ---
70  *
71  * Use:         Creates a new association table.
72  */
73
74 extern void assoc_create(assoc_table */*t*/);
75
76 /* --- @assoc_destroy@ --- *
77  *
78  * Arguments:   @assoc_table *t@ = pointer to an association table
79  *
80  * Returns:     ---
81  *
82  * Use:         Destroys an association table.
83  */
84
85 extern void assoc_destroy(assoc_table */*t*/);
86
87 /* --- @assoc_find@ --- *
88  *
89  * Arguments:   @assoc_table *t@ = pointer to an association table
90  *              @atom *a@ = an atom to label the item
91  *              @size_t sz@ = size of block to allocate
92  *              @unsigned *f@ = pointer to `found' flag
93  *
94  * Returns:     A pointer to the item located or null.
95  *
96  * Use:         Looks up an atom in an association table.  If the atom is
97  *              found, the association is returned.  If not, and @sz@ is
98  *              zero, a null pointer is returned.  Otherwise, a block of size
99  *              @sz@ is allocated, its @assoc_base@ header is filled in, and
100  *              the pointer returned.  The flag @*f@ is cleared if the item
101  *              couldn't be found, or set if it was.
102  *
103  *              All the atoms used in a particular table should 
104  */
105
106 extern void *assoc_find(assoc_table */*t*/, atom */*a*/,
107                         size_t /*sz*/, unsigned */*f*/);
108
109 /* --- @assoc_remove@ --- *
110  *
111  * Arguments:   @assoc_table *t@ = pointer to an association table
112  *              @void *p@ = pointer to a block to remove
113  *
114  * Returns:     ---
115  *
116  * Use:         Removes an association from a table.
117  */
118
119 extern void assoc_remove(assoc_table */*t*/, void */*p*/);
120
121 /* --- @assoc_mkiter@, @assoc_next@ --- *
122  *
123  * Arguments:   @assoc_iter *i@ = pointer to an iterator
124  *              @assoc_table *t@ = pointer to an association table
125  *
126  * Returns:     Next association, or null, for @assoc_next@; nothing for
127  *              @assoc_mkiter@.
128  *
129  * Use:         Iterates over the associations in a table.
130  */
131
132 #define ASSOC_MKITER(i_, t_) HASH_MKITER(&(i_)->i, &(t_)->t)
133
134 #define ASSOC_NEXT(i_, p) do {                                          \
135   hash_base *_q;                                                        \
136   HASH_NEXT(&(i_)->i, _q);                                              \
137   (p) = (void *)_q;                                                     \
138 } while (0)
139
140 extern void assoc_mkiter(assoc_iter */*i*/, assoc_table */*t*/);
141 extern void *assoc_next(assoc_iter */*i*/);
142
143 /*----- That's all, folks -------------------------------------------------*/
144
145 #ifdef __cplusplus
146   }
147 #endif
148
149 #endif