Annotation of embedaddon/strongswan/src/libstrongswan/collections/hashtable.h, revision 1.1.1.1
1.1 misho 1: /*
2: * Copyright (C) 2008-2012 Tobias Brunner
3: * HSR Hochschule fuer Technik Rapperswil
4: *
5: * This program is free software; you can redistribute it and/or modify it
6: * under the terms of the GNU General Public License as published by the
7: * Free Software Foundation; either version 2 of the License, or (at your
8: * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9: *
10: * This program is distributed in the hope that it will be useful, but
11: * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12: * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13: * for more details.
14: */
15:
16: /**
17: * @defgroup hashtable hashtable
18: * @{ @ingroup collections
19: */
20:
21: #ifndef HASHTABLE_H_
22: #define HASHTABLE_H_
23:
24: #include <collections/enumerator.h>
25:
26: typedef struct hashtable_t hashtable_t;
27:
28: /**
29: * Prototype for a function that computes the hash code from the given key.
30: *
31: * @param key key to hash
32: * @return hash code
33: */
34: typedef u_int (*hashtable_hash_t)(const void *key);
35:
36: /**
37: * Hashtable hash function calculation the hash solely based on the key pointer.
38: *
39: * @param key key to hash
40: * @return hash of key
41: */
42: u_int hashtable_hash_ptr(const void *key);
43:
44: /**
45: * Hashtable hash function calculation the hash for char* keys.
46: *
47: * @param key key to hash, a char*
48: * @return hash of key
49: */
50: u_int hashtable_hash_str(const void *key);
51:
52: /**
53: * Prototype for a function that compares the two keys for equality.
54: *
55: * @param key first key (the one we are looking for)
56: * @param other_key second key
57: * @return TRUE if the keys are equal
58: */
59: typedef bool (*hashtable_equals_t)(const void *key, const void *other_key);
60:
61: /**
62: * Hashtable equals function comparing pointers.
63: *
64: * @param key key to compare
65: * @param other_key other key to compare
66: * @return TRUE if key == other_key
67: */
68: bool hashtable_equals_ptr(const void *key, const void *other_key);
69:
70: /**
71: * Hashtable equals function comparing char* keys.
72: *
73: * @param key key to compare
74: * @param other_key other key to compare
75: * @return TRUE if streq(key, other_key)
76: */
77: bool hashtable_equals_str(const void *key, const void *other_key);
78:
79: /**
80: * Class implementing a hash table.
81: *
82: * General purpose hash table. This hash table is not synchronized.
83: */
84: struct hashtable_t {
85:
86: /**
87: * Create an enumerator over the hash table key/value pairs.
88: *
89: * @return enumerator over (void *key, void *value)
90: */
91: enumerator_t *(*create_enumerator) (hashtable_t *this);
92:
93: /**
94: * Adds the given value with the given key to the hash table, if there
95: * exists no entry with that key. NULL is returned in this case.
96: * Otherwise the existing value is replaced and the function returns the
97: * old value.
98: *
99: * @param key the key to store
100: * @param value the value to store
101: * @return NULL if no item was replaced, the old value otherwise
102: */
103: void *(*put) (hashtable_t *this, const void *key, void *value);
104:
105: /**
106: * Returns the value with the given key, if the hash table contains such an
107: * entry, otherwise NULL is returned.
108: *
109: * @param key the key of the requested value
110: * @return the value, NULL if not found
111: */
112: void *(*get) (hashtable_t *this, const void *key);
113:
114: /**
115: * Returns the value with a matching key, if the hash table contains such an
116: * entry, otherwise NULL is returned.
117: *
118: * Compared to get() the given match function is used to compare the keys
119: * for equality. The hash function does have to be devised properly in
120: * order to make this work if the match function compares keys differently
121: * than the equals function provided to the constructor. This basically
122: * allows to enumerate all entries with the same hash value.
123: *
124: * @param key the key to match against
125: * @param match match function to be used when comparing keys
126: * @return the value, NULL if not found
127: */
128: void *(*get_match) (hashtable_t *this, const void *key,
129: hashtable_equals_t match);
130:
131: /**
132: * Removes the value with the given key from the hash table and returns the
133: * removed value (or NULL if no such value existed).
134: *
135: * @param key the key of the value to remove
136: * @return the removed value, NULL if not found
137: */
138: void *(*remove) (hashtable_t *this, const void *key);
139:
140: /**
141: * Removes the key and value pair from the hash table at which the given
142: * enumerator currently points.
143: *
144: * @param enumerator enumerator, from create_enumerator
145: */
146: void (*remove_at) (hashtable_t *this, enumerator_t *enumerator);
147:
148: /**
149: * Gets the number of items in the hash table.
150: *
151: * @return number of items
152: */
153: u_int (*get_count) (hashtable_t *this);
154:
155: /**
156: * Destroys a hash table object.
157: */
158: void (*destroy) (hashtable_t *this);
159:
160: /**
161: * Destroys a hash table object and calls the given function for each
162: * item and its key in the hash table.
163: *
164: * @param function function to call on each item and key
165: */
166: void (*destroy_function)(hashtable_t *this,
167: void (*)(void *val, const void *key));
168: };
169:
170: /**
171: * Creates an empty hash table object.
172: *
173: * @param hash hash function
174: * @param equals equals function
175: * @param capacity initial capacity
176: * @return hashtable_t object.
177: */
178: hashtable_t *hashtable_create(hashtable_hash_t hash, hashtable_equals_t equals,
179: u_int capacity);
180:
181: #endif /** HASHTABLE_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>