/* Copyright 2006 Garrett Rooney.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @file etl_hash.h
 * @brief Functions for manipulating hash tables.
 */

#ifndef ETL_HASH_H
#define ETL_HASH_H

#include <stdbool.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/** A hash table. */
typedef struct etl_hash_t etl_hash_t;

/** Create a new empty hash table. */
etl_hash_t *etl_hash_create();

/** A callback for use in @c etl_hash_copy. */
typedef void * (*etl_hash_copy_val_t)(void *val, void *baton);

/** Return a copy of @a hash.
 *
 * If @a copy is non-NULL use it to copy each element of @a hash.
 */
etl_hash_t *etl_hash_copy(etl_hash_t *hash,
                          etl_hash_copy_val_t copy,
                          void *baton);

/** A callback for use in @c etl_hash_destroy. */
typedef void (*etl_hash_elt_destroy_t)(void *elt, void *baton);

/** Destroy @a hash.
 *
 * If @a destroy is non-NULL call it on each value in @a hash so
 * it can destroy them.
 */
void
etl_hash_destroy(etl_hash_t *hash,
                 etl_hash_elt_destroy_t destroy,
                 void *baton);

/**
 * Set @a key in @a hash t @a val.
 *
 * Returns the existing value, if there is one, or @c NULL if there is not.
 */
void *etl_hash_set(etl_hash_t *hash, const char *key, const void *val);

/**
 * Get the current value for @a key in @a hash, or @c NULL if there is none.
 */
void *etl_hash_get(etl_hash_t *hash, const char *key);

/**
 * Traverse the key-value pairs in @a hash, calling @a callback with
 * @a baton for each of them.
 */
void etl_hash_traverse(etl_hash_t *hash,
                       void (*callback)(const char *key,
                                        void *val,
                                        void *baton),
                       void *baton);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* ETL_HASH_H */