botan: Add support for Ed25519 keys
[strongswan.git] / src / libstrongswan / collections / hashtable.h
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 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, 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_ @}*/