cannam@226: /*
cannam@226:   Copyright 2011-2015 David Robillard <http://drobilla.net>
cannam@226: 
cannam@226:   Permission to use, copy, modify, and/or distribute this software for any
cannam@226:   purpose with or without fee is hereby granted, provided that the above
cannam@226:   copyright notice and this permission notice appear in all copies.
cannam@226: 
cannam@226:   THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
cannam@226:   WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
cannam@226:   MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
cannam@226:   ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
cannam@226:   WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
cannam@226:   ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
cannam@226:   OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
cannam@226: */
cannam@226: 
cannam@226: #ifndef ZIX_HASH_H
cannam@226: #define ZIX_HASH_H
cannam@226: 
cannam@226: #include <stddef.h>
cannam@226: #include <stdint.h>
cannam@226: 
cannam@226: #include "zix/common.h"
cannam@226: 
cannam@226: #ifdef __cplusplus
cannam@226: extern "C" {
cannam@226: #endif
cannam@226: 
cannam@226: /**
cannam@226:    @addtogroup zix
cannam@226:    @{
cannam@226:    @name Hash
cannam@226:    @{
cannam@226: */
cannam@226: 
cannam@226: typedef struct ZixHashImpl ZixHash;
cannam@226: 
cannam@226: /**
cannam@226:    Function for computing the hash of an element.
cannam@226: */
cannam@226: typedef uint32_t (*ZixHashFunc)(const void* value);
cannam@226: 
cannam@226: /**
cannam@226:    Function to visit a hash element.
cannam@226: */
cannam@226: typedef void (*ZixHashVisitFunc)(void* value,
cannam@226:                                  void* user_data);
cannam@226: 
cannam@226: /**
cannam@226:    Create a new hash table.
cannam@226: 
cannam@226:    To minimize space overhead, unlike many hash tables this stores a single
cannam@226:    value, not a key and a value.  Any size of value can be stored, but all the
cannam@226:    values in the hash table must be the same size, and the values must be safe
cannam@226:    to copy with memcpy.  To get key:value behaviour, simply insert a struct
cannam@226:    with a key and value into the hash.
cannam@226: 
cannam@226:    @param hash_func The hashing function.
cannam@226:    @param equal_func A function to test value equality.
cannam@226:    @param value_size The size of the values to be stored.
cannam@226: */
cannam@226: ZIX_API ZixHash*
cannam@226: zix_hash_new(ZixHashFunc  hash_func,
cannam@226:              ZixEqualFunc equal_func,
cannam@226:              size_t       value_size);
cannam@226: 
cannam@226: /**
cannam@226:    Free `hash`.
cannam@226: */
cannam@226: ZIX_API void
cannam@226: zix_hash_free(ZixHash* hash);
cannam@226: 
cannam@226: /**
cannam@226:    Return the number of elements in `hash`.
cannam@226: */
cannam@226: ZIX_API size_t
cannam@226: zix_hash_size(const ZixHash* hash);
cannam@226: 
cannam@226: /**
cannam@226:    Insert an item into `hash`.
cannam@226: 
cannam@226:    If no matching value is found, ZIX_STATUS_SUCCESS will be returned, and @p
cannam@226:    inserted will be pointed to the copy of `value` made in the new hash node.
cannam@226: 
cannam@226:    If a matching value already exists, ZIX_STATUS_EXISTS will be returned, and
cannam@226:    `inserted` will be pointed to the existing value.
cannam@226: 
cannam@226:    @param hash The hash table.
cannam@226:    @param value The value to be inserted.
cannam@226:    @param inserted The copy of `value` in the hash table.
cannam@226:    @return ZIX_STATUS_SUCCESS, ZIX_STATUS_EXISTS, or ZIX_STATUS_NO_MEM.
cannam@226: */
cannam@226: ZIX_API ZixStatus
cannam@226: zix_hash_insert(ZixHash*     hash,
cannam@226:                 const void*  value,
cannam@226:                 const void** inserted);
cannam@226: 
cannam@226: /**
cannam@226:    Remove an item from `hash`.
cannam@226: 
cannam@226:    @param hash The hash table.
cannam@226:    @param value The value to remove.
cannam@226:    @return ZIX_STATUS_SUCCES or ZIX_STATUS_NOT_FOUND.
cannam@226: */
cannam@226: ZIX_API ZixStatus
cannam@226: zix_hash_remove(ZixHash*    hash,
cannam@226:                 const void* value);
cannam@226: 
cannam@226: /**
cannam@226:    Search for an item in `hash`.
cannam@226: 
cannam@226:    @param hash The hash table.
cannam@226:    @param value The value to search for.
cannam@226: */
cannam@226: ZIX_API const void*
cannam@226: zix_hash_find(const ZixHash* hash,
cannam@226:               const void*    value);
cannam@226: 
cannam@226: /**
cannam@226:    Call `f` on each value in `hash`.
cannam@226: 
cannam@226:    @param hash The hash table.
cannam@226:    @param f The function to call on each value.
cannam@226:    @param user_data The user_data parameter passed to `f`.
cannam@226: */
cannam@226: ZIX_API void
cannam@226: zix_hash_foreach(ZixHash*         hash,
cannam@226:                  ZixHashVisitFunc f,
cannam@226:                  void*            user_data);
cannam@226: 
cannam@226: /**
cannam@226:    @}
cannam@226:    @}
cannam@226: */
cannam@226: 
cannam@226: #ifdef __cplusplus
cannam@226: }  /* extern "C" */
cannam@226: #endif
cannam@226: 
cannam@226: #endif  /* ZIX_HASH_H */