Go to the source code of this file.
Classes | |
| struct | zhash_iterator |
Typedefs | |
| typedef struct zhash_iterator | zhash_iterator_t |
| typedef struct zhash | zhash_t |
Functions | |
| void | zhash_clear (zhash_t *zh) |
| int | zhash_contains (const zhash_t *zh, const void *key) |
| zhash_t * | zhash_copy (const zhash_t *other) |
| zhash_t * | zhash_create (size_t keysz, size_t valuesz, uint32_t(*hash)(const void *a), int(*equals)(const void *a, const void *b)) |
| void | zhash_debug (zhash_t *zh) |
| void | zhash_destroy (zhash_t *zh) |
| int | zhash_get (const zhash_t *zh, const void *key, void *out_value) |
| int | zhash_get_volatile (const zhash_t *zh, const void *key, void *out_p) |
| static int | zhash_int_equals (const void *_a, const void *_b) |
| static uint32_t | zhash_int_hash (const void *_a) |
| void | zhash_iterator_init (zhash_t *zh, zhash_iterator_t *zit) |
| void | zhash_iterator_init_const (const zhash_t *zh, zhash_iterator_t *zit) |
| int | zhash_iterator_next (zhash_iterator_t *zit, void *outkey, void *outvalue) |
| int | zhash_iterator_next_volatile (zhash_iterator_t *zit, void *outkey, void *outvalue) |
| void | zhash_iterator_remove (zhash_iterator_t *zit) |
| zarray_t * | zhash_keys (const zhash_t *zh) |
| void | zhash_map_keys (zhash_t *zh, void(*f)()) |
| void | zhash_map_values (zhash_t *zh, void(*f)()) |
| int | zhash_ptr_equals (const void *a, const void *b) |
| uint32_t | zhash_ptr_hash (const void *a) |
| int | zhash_put (zhash_t *zh, const void *key, const void *value, void *oldkey, void *oldvalue) |
| int | zhash_remove (zhash_t *zh, const void *key, void *oldkey, void *oldvalue) |
| int | zhash_size (const zhash_t *zh) |
| int | zhash_str_equals (const void *a, const void *b) |
| uint32_t | zhash_str_hash (const void *a) |
| static zhash_t * | zhash_str_str_create (void) |
| static void | zhash_str_str_destroy (zhash_t *zh) |
| static char * | zhash_str_str_get (zhash_t *zh, const char *key) |
| static void | zhash_str_str_put (zhash_t *zh, char *key, char *value) |
| int | zhash_uint32_equals (const void *a, const void *b) |
| uint32_t | zhash_uint32_hash (const void *a) |
| int | zhash_uint64_equals (const void *a, const void *b) |
| uint32_t | zhash_uint64_hash (const void *a) |
| zarray_t * | zhash_values (const zhash_t *zh) |
| void | zhash_vmap_keys (zhash_t *vh, void(*f)()) |
| void | zhash_vmap_values (zhash_t *vh, void(*f)()) |
Typedef Documentation
◆ zhash_iterator_t
| typedef struct zhash_iterator zhash_iterator_t |
◆ zhash_t
A hash table for structs and primitive types that stores entries by value.
- The size of the key/values must be known at instantiation time, and remain fixed. e.g. for pointers: zhash_create(sizeof(void*), sizeof(void*)....) for structs: zhash_create(sizeof(struct key_struct), sizeof(struct value_struct)...) for bytes: zhash_create(sizeof(uint8_t), sizeof(uint8_t)...)
- Entries are copied by value. This means you must always pass a reference to the start of 'key_size' and 'value_size' bytes, which you have already malloc'd or stack allocated
- This data structure can be used to store types of any size, from bytes & doubles to user defined structs Note: if zhash stores pointers, user must be careful to manually manage the lifetime of the memory they point to.
Function Documentation
◆ zhash_clear()
| void zhash_clear | ( | zhash_t * | zh | ) |
Removes all entries in the has table to create the equivalent of starting from a zhash_create(), using the same size parameters. If any elements need to be freed manually, this will need to occur before calling clear.
◆ zhash_contains()
| int zhash_contains | ( | const zhash_t * | zh, |
| const void * | key | ||
| ) |
Determines whether the supplied key value exists as an entry in the zhash table. If zhash stores pointer types as keys, this function can differentiate between a non-existent key and a key mapped to NULL. Returns 1 if the supplied key exists in the zhash table, else 0.
◆ zhash_copy()
Creates and returns a new identical copy of the zhash (i.e. a "shallow" copy). If you're storing pointers, be sure not to double free their pointees! It is the caller's responsibility to call zhash_destroy() on the returned array when it is no longer needed (in addition to the zhash_destroy() call for the original zhash).
◆ zhash_create()
| zhash_t* zhash_create | ( | size_t | keysz, |
| size_t | valuesz, | ||
| uint32_t(*)(const void *a) | hash, | ||
| int(*)(const void *a, const void *b) | equals | ||
| ) |
Create, initializes, and returns an empty hash table structure. It is the caller's responsibility to call zhash_destroy() on the returned array when it is no longer needed.
The size of values used in the hash and equals function must match 'keysz'. I.e. if keysz = sizeof(uint64_t), then hash() and equals() should accept parameters as *uint64_t.
◆ zhash_debug()
◆ zhash_destroy()
| void zhash_destroy | ( | zhash_t * | zh | ) |
Frees all resources associated with the hash table structure which was created by zhash_create(). After calling, 'zh' will no longer be valid for storage.
If 'zh' contains pointer data, it is the caller's responsibility to manage the resources pointed to by those pointers.
◆ zhash_get()
| int zhash_get | ( | const zhash_t * | zh, |
| const void * | key, | ||
| void * | out_value | ||
| ) |
Retrieves the value for the given key, if it exists, by copying its contents into the space pointed to by 'out_value', which must already be allocated. Returns 1 if the supplied key exists in the table, else 0, in which case the contents of 'out_value' will be unchanged.
◆ zhash_get_volatile()
| int zhash_get_volatile | ( | const zhash_t * | zh, |
| const void * | key, | ||
| void * | out_p | ||
| ) |
Similar to zhash_get(), but more dangerous. Provides a pointer to the zhash's internal storage. This can be used to make simple modifications to the underlying data while avoiding the memcpys associated with zhash_get and zhash_put. However, some zhash operations (that resize the underlying storage, in particular) render this pointer invalid. For maximum safety, call no other zhash functions for the period during which you intend to use the pointer. 'out_p' should be a pointer to the pointer which will be set to the internal data address.
◆ zhash_int_equals()
|
inlinestatic |
◆ zhash_int_hash()
|
inlinestatic |
◆ zhash_iterator_init()
| void zhash_iterator_init | ( | zhash_t * | zh, |
| zhash_iterator_t * | zit | ||
| ) |
Initializes an iterator which can be used to traverse the key/value pairs of the supplied zhash table via successive calls to zhash_iterator_next() or zhash_iterator_next_volatile(). The iterator can also be used to remove elements from the zhash with zhash_iterator_remove().
Any modifications to the zhash table structure will invalidate the iterator, with the exception of zhash_iterator_remove().
◆ zhash_iterator_init_const()
| void zhash_iterator_init_const | ( | const zhash_t * | zh, |
| zhash_iterator_t * | zit | ||
| ) |
Initializes an iterator which can be used to traverse the key/value pairs of the supplied zhash table via successive calls to zhash_iterator_next() or zhash_iterator_next_volatile().
An iterator initialized with this function cannot be used with zhash_iterator_remove(). For that you must use zhash_iterator_init().
Any modifications to the zhash table structure will invalidate the iterator.
◆ zhash_iterator_next()
| int zhash_iterator_next | ( | zhash_iterator_t * | zit, |
| void * | outkey, | ||
| void * | outvalue | ||
| ) |
Retrieves the next key/value pair from a zhash table via the (previously- initialized) iterator. Copies the key and value data into the space pointed to by outkey and outvalue, respectively, if they are not NULL.
Returns 1 if the call retrieved the next available key/value pair, else 0 indicating that no entries remain, in which case the contents of outkey and outvalue will remain unchanged.
◆ zhash_iterator_next_volatile()
| int zhash_iterator_next_volatile | ( | zhash_iterator_t * | zit, |
| void * | outkey, | ||
| void * | outvalue | ||
| ) |
Similar to zhash_iterator_next() except that it retrieves a pointer to zhash's internal storage. This can be used to avoid the memcpys associated with zhash_iterator_next(). Call no other zhash functions for the period during which you intend to use the pointer. 'outkey' and 'outvalue' should be pointers to the pointers which will be set to the internal data addresses.
Example: key_t *outkey; value_t *outvalue; if (zhash_iterator_next_volatile(&zit, &outkey, &outvalue)) // access internal key and value storage via outkey and outvalue
Returns 1 if the call retrieved the next available key/value pair, else 0 indicating that no entries remain, in which case the pointers outkey and outvalue will remain unchanged.
◆ zhash_iterator_remove()
| void zhash_iterator_remove | ( | zhash_iterator_t * | zit | ) |
Removes from the zhash table the key/value pair most recently returned via a call to zhash_iterator_next() or zhash_iterator_next_volatile() for the supplied iterator.
Requires that the iterator was initialized with zhash_iterator_init(), not zhash_iterator_init_const().
◆ zhash_keys()
Returns an array which contains copies of all of the hash table's keys, in no particular order. It is the caller's responsibility to call zarray_destroy() on the returned structure when it is no longer needed.
◆ zhash_map_keys()
| void zhash_map_keys | ( | zhash_t * | zh, |
| void(*)() | f | ||
| ) |
Calls the supplied function with a pointer to every key in the hash table in turn. The function will be passed a pointer to the table's internal storage for the key, which the caller should not modify, as the hash table will not be re-indexed. The function may be NULL, in which case no action is taken.
◆ zhash_map_values()
| void zhash_map_values | ( | zhash_t * | zh, |
| void(*)() | f | ||
| ) |
Calls the supplied function with a pointer to every value in the hash table in turn. The function will be passed a pointer to the table's internal storage for the value, which the caller may safely modify. The function may be NULL, in which case no action is taken.
◆ zhash_ptr_equals()
| int zhash_ptr_equals | ( | const void * | a, |
| const void * | b | ||
| ) |
Defines a function to compare zhash values for pointer input data. Can be used with zhash_create() for a key size of sizeof(void*).
◆ zhash_ptr_hash()
| uint32_t zhash_ptr_hash | ( | const void * | a | ) |
Defines a hash function which will calculate a zhash value for pointer input data. Can be used with zhash_create() for a key size of sizeof(void*). Will use only the pointer value itself for computing the hash value.
◆ zhash_put()
| int zhash_put | ( | zhash_t * | zh, |
| const void * | key, | ||
| const void * | value, | ||
| void * | oldkey, | ||
| void * | oldvalue | ||
| ) |
Adds a key/value pair to the hash table, if the supplied key does not already exist in the table, or overwrites the value for the supplied key if it does already exist. In the latter case, the previous contents of the key and value will be copied into the spaces pointed to by 'oldkey' and 'oldvalue', respectively, if they are not NULL.
The key/value is added to / updated in the hash table by copying 'keysz' bytes from the data pointed to by 'key' and 'valuesz' bytes from the data pointed to by 'value'. It is up to the caller to manage the memory allocation of the passed-in values, zhash will store and manage a copy.
NOTE: If the key is a pointer type (such as a string), the contents of the data that it points to must not be modified after the call to zhash_put(), or future zhash calls will not successfully locate the key (using either its previous or new value).
NOTE: When using array data as a key (such as a string), the array should not be passed directly or it will cause a segmentation fault when it is dereferenced. Instead, pass a pointer which points to the array location, i.e.: char key[strlen]; char *keyptr = key; zhash_put(zh, &keyptr, ...)
Example: char * key = ...; zarray_t * val = ...; char * old_key = NULL; zarray_t * old_val = NULL; if (zhash_put(zh, &key, &val, &old_key, &old_value)) // manage resources for old_key and old_value
Returns 1 if the supplied key previously existed in the table, else 0, in which case the data pointed to by 'oldkey' and 'oldvalue' will be set to zero if they are not NULL.
◆ zhash_remove()
| int zhash_remove | ( | zhash_t * | zh, |
| const void * | key, | ||
| void * | oldkey, | ||
| void * | oldvalue | ||
| ) |
Removes from the zhash table the key/value pair for the supplied key, if it exists. If it does, the contents of the key and value will be copied into the spaces pointed to by 'oldkey' and 'oldvalue', respectively, if they are not NULL. If the key does not exist, the data pointed to by 'oldkey' and 'oldvalue' will be set to zero if they are not NULL.
Returns 1 if the key existed and was removed, else 0, indicating that the table contents were not changed.
◆ zhash_size()
| int zhash_size | ( | const zhash_t * | zh | ) |
◆ zhash_str_equals()
| int zhash_str_equals | ( | const void * | a, |
| const void * | b | ||
| ) |
Defines a function to compare zhash values for string input data. Can be used with zhash_create() for a key size of sizeof(char*).
◆ zhash_str_hash()
| uint32_t zhash_str_hash | ( | const void * | a | ) |
Defines a hash function which will calculate a zhash value for string input data. Can be used with zhash_create() for a key size of sizeof(char*). Will use the contents of the string in computing the hash value.
◆ zhash_str_str_create()
◆ zhash_str_str_destroy()
|
inlinestatic |
◆ zhash_str_str_get()
|
inlinestatic |
◆ zhash_str_str_put()
|
inlinestatic |
◆ zhash_uint32_equals()
| int zhash_uint32_equals | ( | const void * | a, |
| const void * | b | ||
| ) |
Defines a function to compare zhash values for uint32_t input data. Can be used with zhash_create() for a key size of sizeof(uint32_t).
◆ zhash_uint32_hash()
| uint32_t zhash_uint32_hash | ( | const void * | a | ) |
Defines a hash function which will calculate a zhash value for uint32_t input data. Can be used with zhash_create() for a key size of sizeof(uint32_t).
◆ zhash_uint64_equals()
| int zhash_uint64_equals | ( | const void * | a, |
| const void * | b | ||
| ) |
Defines a function to compare zhash values for uint64_t input data. Can be used with zhash_create() for a key size of sizeof(uint64_t).
◆ zhash_uint64_hash()
| uint32_t zhash_uint64_hash | ( | const void * | a | ) |
Defines a hash function which will calculate a zhash value for uint64_t input data. Can be used with zhash_create() for a key size of sizeof(uint64_t).
◆ zhash_values()
Returns an array which contains copies of all of the hash table's values, in no particular order. It is the caller's responsibility to call zarray_destroy() on the returned structure when it is no longer needed.
◆ zhash_vmap_keys()
| void zhash_vmap_keys | ( | zhash_t * | vh, |
| void(*)() | f | ||
| ) |
Calls the supplied function with a copy of every key in the hash table in turn. While zhash_map_keys() passes a pointer to internal storage, this function passes a copy of the actual storage. If the zhash stores pointers to data, functions like free() can be used directly with zhash_vmap_keys(). The function may be NULL, in which case no action is taken.
NOTE: zhash_vmap_keys() can only be used with pointer-data keys. Use with non-pointer keys (i.e. integer, double, etc.) will likely cause a segmentation fault.
◆ zhash_vmap_values()
| void zhash_vmap_values | ( | zhash_t * | vh, |
| void(*)() | f | ||
| ) |
Calls the supplied function with a copy of every value in the hash table in turn. While zhash_map_values() passes a pointer to internal storage, this function passes a copy of the actual storage. If the zhash stores pointers to data, functions like free() can be used directly with zhash_vmap_values(). The function may be NULL, in which case no action is taken.
NOTE: zhash_vmap_values() can only be used with pointer-data values. Use with non-pointer values (i.e. integer, double, etc.) will likely cause a segmentation fault.