src/common/lookup.h

/* RCSid $Id: lookup.h,v 2.13 2004/05/25 06:30:46 greg Exp $ */
/*
 * Header file for general associative table lookup routines
 */
#ifndef _RAD_LOOKUP_H_
#define _RAD_LOOKUP_H_

#ifdef __cplusplus
extern "C" {
#endif

typedef void lut_free_t(void *p);
typedef unsigned long lut_hashf_t(const void *);
typedef int lut_keycmpf_t(const void *, const void *);

typedef struct {
        char    *key;                   /* key name */
        unsigned long   hval;           /* key hash value (for efficiency) */
        char    *data;                  /* pointer to client data */
} LUENT;

typedef struct {
        lut_hashf_t *hashf;     /* key hash function */
        lut_keycmpf_t *keycmp;  /* key comparison function */
        lut_free_t *freek;              /* free a key */
        lut_free_t *freed;              /* free the data */
        int     tsiz;                   /* current table size */
        LUENT   *tabl;                  /* table, if allocated */
        int     ndel;                   /* number of deleted entries */
} LUTAB;


/*
 * The lu_init routine is called to initialize a table.  The number of
 * elements passed is not a limiting factor, as a table can grow to
 * any size permitted by memory.  However, access will be more efficient
 * if this number strikes a reasonable balance between default memory use
 * and the expected (minimum) table size.  The value returned is the
 * actual allocated table size (or zero if there was insufficient memory).
 *
 * The hashf, keycmp, freek and freed member functions must be assigned
 * separately.  If the hash value is sufficient to guarantee equality
 * between keys, then the keycmp pointer may be NULL.  Otherwise, it
 * should return 0 if the two passed keys match.  If it is not necessary
 * (or possible) to free the key and/or data values, then the freek and/or
 * freed member functions may be NULL.
 *
 * It isn't fully necessary to call lu_init to initialize the LUTAB structure.
 * If tsiz is 0, then the first call to lu_find will allocate a minimal table.
 * The LU_SINIT macro provides a convenient static declaration for character
 * string keys.
 *
 * The lu_find routine returns the entry corresponding to the given
 * key.  If the entry does not exist, the corresponding key field will
 * be NULL.  If the entry has been previously deleted but not yet freed,
 * then only the data field will be NULL.  It is the caller's
 * responsibility to (allocate and) assign the key and data fields when
 * creating a new entry.  The only case where lu_find returns NULL is when
 * the system has run out of memory.
 *
 * The lu_delete routine frees an entry's data (if any) by calling
 * the freed member function, but does not free the key field.  This
 * will be freed later during (or instead of) table reallocation.
 * It is therefore an error to reuse or do anything with the key
 * field after calling lu_delete.
 *
 * The lu_doall routine loops through every filled table entry, calling
 * the given function once on each entry.  If a NULL pointer is passed
 * for this function, then lu_doall simply returns the total number of
 * active entries.  Otherwise, it returns the sum of all the function
 * evaluations.
 *
 * The lu_done routine calls the given free function once for each
 * assigned table entry (i.e. each entry with an assigned key value).
 * The user must define these routines to free the key and the data
 * in the LU_TAB structure.  The final action of lu_done is to free the
 * allocated table itself.
 */

typedef int lut_doallf_t(const LUENT *e, void *p);

extern lut_keycmpf_t lu_strcmp;
extern int      lu_init(LUTAB *tbl, int nel);
extern unsigned long    lu_shash(const void *s);
extern LUENT    *lu_find(LUTAB *tbl, const char *key);
extern void     lu_delete(LUTAB *tbl, const char *key);
extern int      lu_doall(const LUTAB *tbl, lut_doallf_t *f, void *p);
extern void     lu_done(LUTAB *tbl);

#define LU_SINIT(fk,fd) {lu_shash,lu_strcmp,fk,fd,0,NULL,0}

#ifdef __cplusplus
}
#endif
#endif /* _RAD_LOOKUP_H_ */

Revision:	2.14
Committed:	Tue May 25 22:04:13 2004 UTC (19 years, 11 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
#	User	Rev	Content
1	greg	2.14	/* RCSid $Id: lookup.h,v 2.13 2004/05/25 06:30:46 greg Exp $ */
2	greg	2.1	/*
3			* Header file for general associative table lookup routines
4			*/
5	schorsch	2.8	#ifndef _RAD_LOOKUP_H_
6			#define _RAD_LOOKUP_H_
7	schorsch	2.10
8	schorsch	2.8	#ifdef __cplusplus
9			extern "C" {
10			#endif
11	greg	2.6
12	schorsch	2.12	typedef void lut_free_t(void *p);
13	greg	2.14	typedef unsigned long lut_hashf_t(const void *);
14			typedef int lut_keycmpf_t(const void , const void );
15	schorsch	2.11
16	greg	2.1	typedef struct {
17	gwlarson	2.5	char key; / key name */
18			unsigned long hval; /* key hash value (for efficiency) */
19			char data; / pointer to client data */
20	greg	2.1	} LUENT;
21
22			typedef struct {
23	schorsch	2.12	lut_hashf_t hashf; / key hash function */
24			lut_keycmpf_t keycmp; / key comparison function */
25	schorsch	2.11	lut_free_t freek; / free a key */
26			lut_free_t freed; / free the data */
27	gwlarson	2.5	int tsiz; /* current table size */
28			LUENT tabl; / table, if allocated */
29			int ndel; /* number of deleted entries */
30	greg	2.1	} 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	greg	2.2	* It is therefore an error to reuse or do anything with the key
65			* field after calling lu_delete.
66	greg	2.1	*
67	gwlarson	2.4	* 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	greg	2.1	* 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	greg	2.6
80	greg	2.14	typedef int lut_doallf_t(const LUENT e, void p);
81	schorsch	2.12
82			extern lut_keycmpf_t lu_strcmp;
83	greg	2.6	extern int lu_init(LUTAB *tbl, int nel);
84	greg	2.14	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	greg	2.6	extern void lu_done(LUTAB *tbl);
89
90	schorsch	2.12	#define LU_SINIT(fk,fd) {lu_shash,lu_strcmp,fk,fd,0,NULL,0}
91	schorsch	2.8
92			#ifdef __cplusplus
93			}
94	greg	2.6	#endif
95	schorsch	2.8	#endif /* _RAD_LOOKUP_H_ */
96