e38850ded2ab2d1f626ceaf0066c32bb148e6568
[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 * Prototype for a function that compares the two keys for equality.
38 *
39 * @param key first key (the one we are looking for)
40 * @param other_key second key
41 * @return TRUE if the keys are equal
42 */
43 typedef bool (*hashtable_equals_t)(void *key, void *other_key);
44
45 /**
46 * Class implementing a hash table.
47 *
48 * General purpose hash table. This hash table is not synchronized.
49 */
50 struct hashtable_t {
51
52 /**
53 * Create an enumerator over the hash table key/value pairs.
54 *
55 * @return enumerator over (void *key, void *value)
56 */
57 enumerator_t *(*create_enumerator) (hashtable_t *this);
58
59 /**
60 * Adds the given value with the given key to the hash table, if there
61 * exists no entry with that key. NULL is returned in this case.
62 * Otherwise the existing value is replaced and the function returns the
63 * old value.
64 *
65 * @param key the key to store
66 * @param value the value to store
67 * @return NULL if no item was replaced, the old value otherwise
68 */
69 void *(*put) (hashtable_t *this, void *key, void *value);
70
71 /**
72 * Returns the value with the given key, if the hash table contains such an
73 * entry, otherwise NULL is returned.
74 *
75 * @param key the key of the requested value
76 * @return the value, NULL if not found
77 */
78 void *(*get) (hashtable_t *this, void *key);
79
80 /**
81 * Returns the value with a matching key, if the hash table contains such an
82 * entry, otherwise NULL is returned.
83 *
84 * Compared to get() the given match function is used to compare the keys
85 * for equality. The hash function does have to be deviced properly in
86 * order to make this work if the match function compares keys differently
87 * than the equals function provided to the constructor. This basically
88 * allows to enumerate all entries with the same hash value.
89 *
90 * @param key the key to match against
91 * @param match match function to be used when comparing keys
92 * @return the value, NULL if not found
93 */
94 void *(*get_match) (hashtable_t *this, void *key, hashtable_equals_t match);
95
96 /**
97 * Removes the value with the given key from the hash table and returns the
98 * removed value (or NULL if no such value existed).
99 *
100 * @param key the key of the value to remove
101 * @return the removed value, NULL if not found
102 */
103 void *(*remove) (hashtable_t *this, void *key);
104
105 /**
106 * Removes the key and value pair from the hash table at which the given
107 * enumerator currently points.
108 *
109 * @param enumerator enumerator, from create_enumerator
110 */
111 void (*remove_at) (hashtable_t *this, enumerator_t *enumerator);
112
113 /**
114 * Gets the number of items in the hash table.
115 *
116 * @return number of items
117 */
118 u_int (*get_count) (hashtable_t *this);
119
120 /**
121 * Destroys a hash table object.
122 */
123 void (*destroy) (hashtable_t *this);
124
125 };
126
127 /**
128 * Creates an empty hash table object.
129 *
130 * @param hash hash function
131 * @param equals equals function
132 * @param capacity initial capacity
133 * @return hashtable_t object.
134 */
135 hashtable_t *hashtable_create(hashtable_hash_t hash, hashtable_equals_t equals,
136 u_int capacity);
137
138 #endif /** HASHTABLE_H_ @}*/