hashtable: add common hashtable hash/equals functions for pointer/string keys
[strongswan.git] / src / libstrongswan / collections / hashtable.h
1 /*
2 * Copyright (C) 2008-2012 Tobias Brunner
3 * 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)(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(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(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)(void *key, 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(void *key, 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(void *key, 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, 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, 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 deviced 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, void *key, hashtable_equals_t match);
129
130 /**
131 * Removes the value with the given key from the hash table and returns the
132 * removed value (or NULL if no such value existed).
133 *
134 * @param key the key of the value to remove
135 * @return the removed value, NULL if not found
136 */
137 void *(*remove) (hashtable_t *this, void *key);
138
139 /**
140 * Removes the key and value pair from the hash table at which the given
141 * enumerator currently points.
142 *
143 * @param enumerator enumerator, from create_enumerator
144 */
145 void (*remove_at) (hashtable_t *this, enumerator_t *enumerator);
146
147 /**
148 * Gets the number of items in the hash table.
149 *
150 * @return number of items
151 */
152 u_int (*get_count) (hashtable_t *this);
153
154 /**
155 * Destroys a hash table object.
156 */
157 void (*destroy) (hashtable_t *this);
158 };
159
160 /**
161 * Creates an empty hash table object.
162 *
163 * @param hash hash function
164 * @param equals equals function
165 * @param capacity initial capacity
166 * @return hashtable_t object.
167 */
168 hashtable_t *hashtable_create(hashtable_hash_t hash, hashtable_equals_t equals,
169 u_int capacity);
170
171 #endif /** HASHTABLE_H_ @}*/