1 /* @include ajtable ***********************************************************
2 **
3 ** AJAX table functions
4 **
5 ** Hash table functions.
6 **
7 ** @author Copyright (C) 1998 Ian Longden
8 ** @version $Revision: 1.40 $
9 ** @modified 2011 pmr Auto-resizing, destructors, table merges
10 ** @modified $Date: 2013/02/17 13:39:55 $ by $Author: mks $
11 ** @@
12 **
13 ** This library is free software; you can redistribute it and/or
14 ** modify it under the terms of the GNU Lesser General Public
15 ** License as published by the Free Software Foundation; either
16 ** version 2.1 of the License, or (at your option) any later version.
17 **
18 ** This library is distributed in the hope that it will be useful,
19 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
21 ** Lesser General Public License for more details.
22 **
23 ** You should have received a copy of the GNU Lesser General Public
24 ** License along with this library; if not, write to the Free Software
25 ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
26 ** MA  02110-1301,  USA.
27 **
28 ******************************************************************************/
29 
30 #ifndef AJTABLE_H
31 #define AJTABLE_H
32 
33 /* ========================================================================= */
34 /* ============================= include files ============================= */
35 /* ========================================================================= */
36 
37 #include "ajdefine.h"
38 #include "ajstr.h"
39 
40 AJ_BEGIN_DECLS
41 
42 
43 
44 
45 /* ========================================================================= */
46 /* =============================== constants =============================== */
47 /* ========================================================================= */
48 
49 
50 
51 
52 /* @enum AjETableType *********************************************************
53 **
54 ** AJAX Table Type enumeration
55 **
56 ** @value ajETableTypeUnknown no type set
57 ** @value ajETableTypeChar    char* type
58 ** @value ajETableTypeStr     AJAX String (AjPStr) type
59 ** @value ajETableTypeInt     AJAX integer (ajint) type
60 ** @value ajETableTypeUint    AJAX unsigned integer (ajuint) type
61 ** @value ajETableTypeLong    AJAX long integer (ajlong) type
62 ** @value ajETableTypeUlong   AJAX unsigned long integer (ajulong) type
63 ** @value ajETableTypeUser    user-defined type
64 ** @value ajETableTypeMax     beyond last defined value
65 **
66 ******************************************************************************/
67 
68 typedef enum AjOTableType
69 {
70     ajETableTypeUnknown,
71     ajETableTypeChar,
72     ajETableTypeStr,
73     ajETableTypeInt,
74     ajETableTypeUint,
75     ajETableTypeLong,
76     ajETableTypeUlong,
77     ajETableTypeUser,
78     ajETableTypeMax
79 } AjETableType;
80 
81 
82 
83 
84 /* ========================================================================= */
85 /* ============================== public data ============================== */
86 /* ========================================================================= */
87 
88 
89 
90 
91 /* @data AjPTableNode *********************************************************
92 **
93 ** AJAX Table Node object.
94 **
95 ** @attr Link [struct AjSTableNode*] Link top next AJAX Table Node
96 ** @attr Key [void*] Key data
97 ** @attr Value [void*] Value data
98 ** @@
99 ******************************************************************************/
100 
101 typedef struct AjSTableNode {
102     struct AjSTableNode* Link;
103     void* Key;
104     void* Value;
105 } AjOTableNode;
106 
107 #define AjPTableNode AjOTableNode*
108 
109 
110 
111 
112 /* @data AjPTable *************************************************************
113 **
114 ** Hash table object. Tables are key/value pairs with a simple hash function
115 ** to provide rapid searching for keys.
116 **
117 ** Tables can hold any data type. Special functions are available for
118 ** tables of AjPStr values, but these are in the ajstr library,
119 ** and start with ajStrTable...
120 **
121 ** In general, these functions are the same
122 ** but with different hash and comparison functions used. Alternative
123 ** function names are provided in all cases to save remembering which
124 ** calls need special cases.
125 **
126 ** @new ajTableNew Creates a table.
127 ** @delete ajTableFree Deallocates and clears a table.
128 ** @modify ajTablePut Adds or updates a value for a given key.
129 ** @modify ajTableMap Calls a function for each key/value in a table.
130 ** @modify ajTableRemove Removes a key/value pair from a table, and returns
131 **                    the value.
132 ** @cast ajTableToarray Creates an array to hold each key value pair
133 **                     in pairs of array elements. The last element is null.
134 ** @cast ajTableGet Returns the value for a given key.
135 ** @cast ajTableLength Returns the number of keys in a table.
136 ** @output ajTableTrace Writes debug messages to trace the contents of a table.
137 **
138 ** @attr Fcmp [ajint function] Key compare function
139 **                       (0 for match, -1 or +1 if not matched)
140 ** @attr Fhash [ajulong function] Hash function
141 ** @attr Fkeydel [void function] Key destructor, or NULL if not an object
142 ** @attr Fvaldel [void function] Value destructor, or NULL if not an object
143 ** @attr Buckets [AjPTableNode*] Buckets of AJAX Table Node objects
144 ** @attr Size [ajulong] Size - number of hash buckets
145 ** @attr Length [ajulong] Number of entries
146 ** @attr Timestamp [ajuint] Time stamp
147 ** @attr Use [ajuint] Reference count
148 ** @attr Padding [ajuint] Padding to alignment boundary
149 ** @attr Type [AjETableType] AJAX Table Type enumeration
150 ** @@
151 ******************************************************************************/
152 
153 typedef struct AjSTable
154 {
155     ajint (*Fcmp)(const void* key1, const void* key2);
156     ajulong (*Fhash)(const void* key, ajulong hashsize);
157     void (*Fkeydel)(void** Pkey);
158     void (*Fvaldel)(void** Pvalue);
159     AjPTableNode* Buckets;
160     ajulong Size;
161     ajulong Length;
162     ajuint Timestamp;
163     ajuint Use;
164     ajuint Padding;
165     AjETableType Type;
166 } AjOTable;
167 
168 #define AjPTable AjOTable*
169 
170 
171 
172 
173 /* ========================================================================= */
174 /* =========================== public functions ============================ */
175 /* ========================================================================= */
176 
177 
178 
179 
180 /*
181 ** Prototype definitions
182 */
183 
184 void           ajTableExit(void);
185 void           ajTableClear(AjPTable table);
186 void           ajTableClearDelete(AjPTable table);
187 void           ajTableDel(AjPTable* table);
188 void           ajTableDelKeydelValdel(AjPTable* table,
189                                       void (*keydel)(void** Pvalue),
190                                       void (*valdel)(void** Pvalue));
191 void           ajTableDelValdel(AjPTable* table,
192                                 void (*valdel)(void** Pvalue));
193 void           ajTableFree(AjPTable* table);
194 
195 const void*    ajTableFetchV(const AjPTable table, const void* key);
196 void*          ajTableFetchmodV(const AjPTable table, const void* key);
197 void*          ajTableFetchmodTraceV(const AjPTable table, const void* key);
198 
199 const ajint*   ajTableintFetch(const AjPTable table, const ajint* intkey);
200 ajint*         ajTableintFetchmod(AjPTable table, const ajint* key);
201 
202 const ajlong*  ajTablelongFetch(const AjPTable table, const ajlong* longkey);
203 ajlong*        ajTablelongFetchmod(AjPTable table, const ajlong* key);
204 
205 const ajuint*  ajTableuintFetch(const AjPTable table, const ajuint* uintkey);
206 ajuint*        ajTableuintFetchmod(AjPTable table, const ajuint* key);
207 
208 const ajulong* ajTableulongFetch(const AjPTable table,
209                                  const ajulong* ulongkey);
210 ajulong*       ajTableulongFetchmod(AjPTable table, const ajulong* key);
211 
212 const void*    ajTableFetchC(const AjPTable table, const char* txtkey);
213 const void*    ajTableFetchS(const AjPTable table, const AjPStr key);
214 void*          ajTableFetchmodC(const AjPTable table, const char* txtkey);
215 void*          ajTableFetchmodS(const AjPTable table, const AjPStr key);
216 
217 ajulong        ajTableGetLength(const AjPTable table);
218 ajulong        ajTableGetSize(const AjPTable table);
219 void           ajTableMap(AjPTable table,
220                           void (*apply)(const void* key,
221                                         void** Pvalue,
222                                         void* cl),
223                           void* cl);
224 void           ajTableMapDel(AjPTable table,
225                              void (*apply)(void** Pkey,
226                                            void** Pvalue,
227                                            void* cl),
228                              void* cl);
229 AjBool         ajTableMergeAnd(AjPTable thys, AjPTable table);
230 AjBool         ajTableMergeEor(AjPTable thys, AjPTable table);
231 AjBool         ajTableMergeNot(AjPTable thys, AjPTable table);
232 AjBool         ajTableMergeOr(AjPTable thys, AjPTable table);
233 void*          ajTablePut(AjPTable table, void* key, void* value);
234 AjBool         ajTablePutClean(AjPTable table, void* key, void* value,
235                                void (*keydel)(void** Pkey),
236                                void (*valdel)(void** Pvalue));
237 void*          ajTablePutTrace(AjPTable table, void* key,
238                                void* value);
239 
240 void*          ajTableRemove(AjPTable table, const void* key);
241 void*          ajTableRemoveKey(AjPTable table, const void* key,
242                                 void** truekey);
243 void           ajTableResizeCount(AjPTable table, ajulong size);
244 
245 void           ajTableResizeHashsize(AjPTable table, ajulong hashsize);
246 
247 ajulong        ajTableToarrayKeys(const AjPTable table,
248                                   void*** keyarray);
249 ajulong        ajTableToarrayKeysValues(const AjPTable table,
250                                         void*** keyarray, void*** valarray);
251 ajulong        ajTableToarrayValues(const AjPTable table,
252                                     void*** valarray);
253 
254 
255 AjPTable       ajTablecharNew(ajulong hint);
256 AjPTable       ajTablecharNewCase(ajulong hint);
257 AjPTable       ajTablecharNewConst(ajulong hint);
258 AjPTable       ajTablecharNewCaseConst(ajulong hint);
259 
260 void           ajTableTrace(const AjPTable table);
261 void           ajTablecharPrint(const AjPTable table);
262 void           ajTablestrPrint(const AjPTable table);
263 void           ajTablestrTrace(const AjPTable table);
264 void           ajTablestrTracekeys(const AjPTable table);
265 
266 ajint          ajTablecharCmp(const void* key1, const void* key2);
267 ajint          ajTablecharCmpCase(const void* key1, const void* key2);
268 ajint          ajTableintCmp(const void* key1, const void* key2);
269 ajint          ajTableuintCmp(const void* key1, const void* key2);
270 ajint          ajTablelongCmp(const void* key1, const void* key2);
271 ajint          ajTableulongCmp(const void* key1, const void* key2);
272 ajint          ajTablestrCmp(const void* key1, const void* key2);
273 ajint          ajTablestrCmpCase(const void* key1, const void* key2);
274 
275 ajulong        ajTablecharHash(const void* key, ajulong hashsize);
276 ajulong        ajTablecharHashCase(const void* key, ajulong hashsize);
277 ajulong        ajTableintHash(const void* key, ajulong hashsize);
278 ajulong        ajTablelongHash(const void* key, ajulong hashsize);
279 ajulong        ajTableuintHash(const void* key, ajulong hashsize);
280 ajulong        ajTableulongHash(const void* key, ajulong hashsize);
281 ajulong        ajTablestrHash(const void* key, ajulong hashsize);
282 ajulong        ajTablestrHashCase(const void* key, ajulong hashsize);
283 
284 AjPTable       ajTableintNew(ajulong size);
285 AjPTable       ajTableintNewConst(ajulong size);
286 AjPTable       ajTablelongNew(ajulong size);
287 AjPTable       ajTablelongNewConst(ajulong size);
288 AjPTable       ajTableuintNew(ajulong size);
289 AjPTable       ajTableuintNewConst(ajulong size);
290 AjPTable       ajTableulongNew(ajulong size);
291 AjPTable       ajTableulongNewConst(ajulong size);
292 void           ajTableintFree(AjPTable* ptable);
293 void           ajTableintFreeKey(AjPTable* ptable);
294 void           ajTablelongFree(AjPTable* ptable);
295 void           ajTablelongFreeKey(AjPTable* ptable);
296 void           ajTableuintFree(AjPTable* ptable);
297 void           ajTableuintFreeKey(AjPTable* ptable);
298 void           ajTableulongFree(AjPTable* ptable);
299 void           ajTableulongFreeKey(AjPTable* ptable);
300 AjPTable       ajTablestrNew(ajulong size);
301 AjPTable       ajTablestrNewCase(ajulong size);
302 AjPTable       ajTablestrNewConst(ajulong size);
303 AjPTable       ajTablestrNewCaseConst(ajulong size);
304 
305 void           ajTablestrFree(AjPTable* ptable);
306 void           ajTablestrFreeKey(AjPTable* ptable);
307 
308 AjPTable       ajTableNew(ajulong size);
309 AjPTable       ajTableNewFunctionLen(ajulong size,
310                                      ajint (*cmp)(const void* key1,
311                                                   const void* key2),
312                                      ajulong (*hash)(const void* key,
313                                                     ajulong hashsize),
314                                      void (*keydel)(void** Pkey),
315                                      void (*valdel)(void** Pvalue));
316 const AjPStr   ajTablestrFetchkeyC(const AjPTable table, const char* key);
317 const AjPStr   ajTablestrFetchkeyS(const AjPTable table, const AjPStr key);
318 
319 void           ajTableSetDestroy(AjPTable table,
320                                  void (*keydel)(void** Pkey),
321                                  void (*valdel)(void** Pvalue));
322 void           ajTableSetDestroyboth(AjPTable table);
323 void           ajTableSetDestroykey(AjPTable table,
324                                     void (*keydel)(void** Pkey));
325 void           ajTableSetDestroyvalue(AjPTable table,
326                                       void (*valdel)(void** Pvalue));
327 
328 void           ajTableSettypeDefault(AjPTable table);
329 void           ajTableSettypeChar(AjPTable table);
330 void           ajTableSettypeCharCase(AjPTable table);
331 void           ajTableSettypeInt(AjPTable table);
332 void           ajTableSettypeLong(AjPTable table);
333 void           ajTableSettypeUint(AjPTable table);
334 void           ajTableSettypeUlong(AjPTable table);
335 void           ajTableSettypeString(AjPTable table);
336 void           ajTableSettypeStringCase(AjPTable table);
337 void           ajTableSettypeUser(AjPTable table,
338                                   ajint (*cmp)(const void* key1,
339                                                const void* key2),
340                                   ajulong (*hash)(const void* key,
341                                                   ajulong hashsize));
342 
343 AjBool         ajTableMatchC(const AjPTable table, const char* key);
344 AjBool         ajTableMatchS(const AjPTable table, const AjPStr key);
345 AjBool         ajTableMatchV(const AjPTable table, const void* key);
346 
347 void*          ajTablestrFetchC(const AjPTable table, const char* txtkey);
348 void*          ajTablestrFetchS(const AjPTable table, const AjPStr key);
349 AjPStr*        ajTablestrFetchmod(AjPTable table, const AjPStr key);
350 
351 /*
352 ** End of prototype definitions
353 */
354 
355 
356 
357 
358 #ifdef AJ_COMPILE_DEPRECATED_BOOK
359 #endif /* AJ_COMPILE_DEPRECATED_BOOK */
360 
361 #ifdef AJ_COMPILE_DEPRECATED
362 
363 __deprecated AjPTable   ajTableNewLen(ajuint size);
364 __deprecated AjPTable   ajTablestrNewCaseLen(ajuint size);
365 __deprecated AjPTable   ajTablestrNewLen(ajuint size);
366 __deprecated void*      ajTableFetch(const AjPTable table, const void* key);
367 __deprecated const void* ajTableFetchKey(const AjPTable table,
368                                          const void* key);
369 __deprecated AjPTable   ajTablecharNewCaseLen(ajuint hint);
370 __deprecated const AjPStr ajTablestrFetch(const AjPTable table,
371                                           const AjPStr key);
372 __deprecated ajuint     ajTableToarray(const AjPTable table,
373                                        void*** keyarray, void*** valarray);
374 __deprecated ajint      ajTableLength(const AjPTable table);
375 __deprecated void*      ajTableGet(const AjPTable table, const void* key);
376 __deprecated ajint      ajStrTableCmp(const void* key1, const void* key2);
377 __deprecated ajint      ajStrTableCmpC(const void* key1, const void* key2);
378 __deprecated ajint      ajStrTableCmpCase(const void* key1, const void* key2);
379 __deprecated ajint      ajStrTableCmpCaseC(const void* key1, const void* key2);
380 __deprecated ajuint     ajStrTableHash(const void* key, ajuint hashsize);
381 __deprecated ajuint     ajStrTableHashC(const void* key, ajuint hashsize);
382 __deprecated ajuint     ajStrTableHashCase(const void* key, ajuint hashsize);
383 __deprecated ajuint     ajStrTableHashCaseC(const void* key, ajuint hashsize);
384 __deprecated AjPTable   ajStrTableNewC(ajuint hint);
385 __deprecated AjPTable   ajStrTableNewCase(ajuint hint);
386 __deprecated AjPTable   ajStrTableNewCaseC(ajuint hint);
387 __deprecated void       ajStrTablePrint(const AjPTable table);
388 __deprecated void       ajStrTablePrintC(const AjPTable table);
389 __deprecated void       ajStrTableTrace(const AjPTable table);
390 
391 __deprecated AjPTable   ajTableNewL(ajuint size,
392                                     ajint (*cmp)(const void* key1,
393                                                  const void* key2),
394                                     ajuint (*hash)(const void* key,
395                                                    ajuint hashsize));
396 __deprecated const void* ajTableKey(const AjPTable table, const void* key);
397 __deprecated void       ajStrTableFree(AjPTable* table);
398 __deprecated AjPTable   ajStrTableNew(ajuint hint);
399 __deprecated void       ajStrTableFreeKey(AjPTable* table);
400 
401 #endif /* AJ_COMPILE_DEPRECATED */
402 
403 
404 
405 
406 AJ_END_DECLS
407 
408 #endif /* !AJTABLE_H */
409