ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/src/common/lookup.h
Revision: 2.14
Committed: Tue May 25 22:04:13 2004 UTC (19 years, 10 months ago) by greg
Content type: text/plain
Branch: MAIN
CVS Tags: rad3R7P2, rad3R7P1, rad4R0, rad3R6, rad3R6P1, rad3R8, rad3R9
Changes since 2.13: +8 -10 lines
Log Message:
Added const modifier to key and other parameters in lookup.h

File Contents

# Content
1 /* RCSid $Id: lookup.h,v 2.13 2004/05/25 06:30:46 greg Exp $ */
2 /*
3 * Header file for general associative table lookup routines
4 */
5 #ifndef _RAD_LOOKUP_H_
6 #define _RAD_LOOKUP_H_
7
8 #ifdef __cplusplus
9 extern "C" {
10 #endif
11
12 typedef void lut_free_t(void *p);
13 typedef unsigned long lut_hashf_t(const void *);
14 typedef int lut_keycmpf_t(const void *, const void *);
15
16 typedef struct {
17 char *key; /* key name */
18 unsigned long hval; /* key hash value (for efficiency) */
19 char *data; /* pointer to client data */
20 } LUENT;
21
22 typedef struct {
23 lut_hashf_t *hashf; /* key hash function */
24 lut_keycmpf_t *keycmp; /* key comparison function */
25 lut_free_t *freek; /* free a key */
26 lut_free_t *freed; /* free the data */
27 int tsiz; /* current table size */
28 LUENT *tabl; /* table, if allocated */
29 int ndel; /* number of deleted entries */
30 } LUTAB;
31
32
33 /*
34 * The lu_init routine is called to initialize a table. The number of
35 * elements passed is not a limiting factor, as a table can grow to
36 * any size permitted by memory. However, access will be more efficient
37 * if this number strikes a reasonable balance between default memory use
38 * and the expected (minimum) table size. The value returned is the
39 * actual allocated table size (or zero if there was insufficient memory).
40 *
41 * The hashf, keycmp, freek and freed member functions must be assigned
42 * separately. If the hash value is sufficient to guarantee equality
43 * between keys, then the keycmp pointer may be NULL. Otherwise, it
44 * should return 0 if the two passed keys match. If it is not necessary
45 * (or possible) to free the key and/or data values, then the freek and/or
46 * freed member functions may be NULL.
47 *
48 * It isn't fully necessary to call lu_init to initialize the LUTAB structure.
49 * If tsiz is 0, then the first call to lu_find will allocate a minimal table.
50 * The LU_SINIT macro provides a convenient static declaration for character
51 * string keys.
52 *
53 * The lu_find routine returns the entry corresponding to the given
54 * key. If the entry does not exist, the corresponding key field will
55 * be NULL. If the entry has been previously deleted but not yet freed,
56 * then only the data field will be NULL. It is the caller's
57 * responsibility to (allocate and) assign the key and data fields when
58 * creating a new entry. The only case where lu_find returns NULL is when
59 * the system has run out of memory.
60 *
61 * The lu_delete routine frees an entry's data (if any) by calling
62 * the freed member function, but does not free the key field. This
63 * will be freed later during (or instead of) table reallocation.
64 * It is therefore an error to reuse or do anything with the key
65 * field after calling lu_delete.
66 *
67 * The lu_doall routine loops through every filled table entry, calling
68 * the given function once on each entry. If a NULL pointer is passed
69 * for this function, then lu_doall simply returns the total number of
70 * active entries. Otherwise, it returns the sum of all the function
71 * evaluations.
72 *
73 * The lu_done routine calls the given free function once for each
74 * assigned table entry (i.e. each entry with an assigned key value).
75 * The user must define these routines to free the key and the data
76 * in the LU_TAB structure. The final action of lu_done is to free the
77 * allocated table itself.
78 */
79
80 typedef int lut_doallf_t(const LUENT *e, void *p);
81
82 extern lut_keycmpf_t lu_strcmp;
83 extern int lu_init(LUTAB *tbl, int nel);
84 extern unsigned long lu_shash(const void *s);
85 extern LUENT *lu_find(LUTAB *tbl, const char *key);
86 extern void lu_delete(LUTAB *tbl, const char *key);
87 extern int lu_doall(const LUTAB *tbl, lut_doallf_t *f, void *p);
88 extern void lu_done(LUTAB *tbl);
89
90 #define LU_SINIT(fk,fd) {lu_shash,lu_strcmp,fk,fd,0,NULL,0}
91
92 #ifdef __cplusplus
93 }
94 #endif
95 #endif /* _RAD_LOOKUP_H_ */
96