temelia/release/include/hash_set.h

/*!
 Temelia - Hash Set interface.

 Copyright (C) 2008 Ceata (http://cod.ceata.org/proiecte/temelia).

 @author Dascalu Laurentiu

 This program is free software; you can redistribute it and
 modify it under the terms of the GNU General Public License
 as published by the Free Software Foundation; either version 3
 of the License, or (at your option) any later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */

#ifndef HASHTABLE_H_
#define HASHTABLE_H_

#include "platform.h"

struct _hash_set_t;
typedef struct _hash_set_t *hash_set_t;

/*!
 * @brief Constructor - returns an empty hash set with given size.
 * Complexity O(1)
 *
 * @param Hash set's size
 */
DECLSPEC hash_set_t hash_set_new(int size);

/*!
 * @brief Clears hash set.
 * Complexity O(1)
 *
 * @param Hash set
 */
DECLSPEC void hash_set_clear(hash_set_t hash_set);

/*!
 * @brief Frees the memory occupied by hash set.
 * Complexity O(1)
 *
 * @param Hash set
 */
DECLSPEC void hash_set_delete(hash_set_t hash_set);

/*!
 * @brief Checks if hash set contains key. Return 1 if it does, 0 if not
 * or -1 if an error occurred.
 * Complexity O(n/memory)
 *
 * @param Hash set
 * @param Key
 * @param Pointer to hash function; function should return a number
 * between 0 and hash set size - 1, indicating on which linked list
 * should the key be inserted
 * @param Pointer to comparison function
 */
DECLSPEC char hash_set_contains(hash_set_t hash_set, void *key, int hash(void *key,
		void *context), void *hash_context, int compare(void *x, void *y,
		void *context), void *compare_context);

/*!
 * @brief Returns the backbone vector of the hash set. It's a vector instance; in order to use it
 * feel free to cast the returned pointer to vector_t.
 * Complexity O(1)
 *
 * @param Hash set
 */
DECLSPEC void *hash_set_get_backbone(hash_set_t hash_set);

/*!
 * @brief Returns the linked list consisting of keys with given hash value.
 * Complexity O(1)
 *
 * @param Hash set
 * @param Hash value
 */
DECLSPEC void *hash_set_get_collision_list(hash_set_t hash_set, int hash_value);

/*!
 * @brief Checks if hash set is empty.
 * Complexity O(1)
 *
 * @param Hash set
 */
DECLSPEC int hash_set_is_empty(hash_set_t hash_set);

/*!
 * @brief Returns the size of hash set.
 * Complexity O(1)
 *
 * @param Hash set
 */
DECLSPEC int hash_set_get_size(hash_set_t hash_set);

/*!
 * @brief Adds key to hash set. Returns 1 if key was added to hash set, 0 if not
 * or -1 if an error occurred.
 * Complexity O(n/memory)
 *
 * @param Hash set
 * @param Key
 * @param Pointer to hash function
 * @param Pointer to comparison function
 */
DECLSPEC char hash_set_put(hash_set_t hash_set, void *key, int hash(void *key,
		void *context), void *hash_context, int compare(void *x, void *y,
		void *context), void *compare_context);

/*!
 * @brief Removes key from hash set.
 * Returns 1 if success, 0 if key wasn't found or -1 if an error occurred.
 * Complexity O(n/memory)
 *
 * @param Hash set
 * @param Key reference
 * @param Pointer to hash function
 * @param Pointer to comparison function
 */
DECLSPEC int hash_set_remove(hash_set_t hash_set, void *key, int hash(void *key,
		void *context), void *hash_context, int compare(void *x, void *y,
		void *context), void *compare_context);

/*!
 * @brief Prints the content of hash set. For each linked list print the hash
 * and the keys with same hash. After each linked list, key_handler is called with
 * a NULL pointer in order to announce that it starts printing the keys of another list.
 * Complexity O(n)
 *
 * @param Hash set
 * @param Pointer to iterating function
 * @param Context
 */
DECLSPEC void hash_set_iterate(hash_set_t hash_set, void key_handler(void *key,
		void *context), void *context);

#endif /* HASHTABLE_H_ */