util/include/axutil_hash.h

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.
 */

#ifndef AXUTIL_HASH_H
#define AXUTIL_HASH_H

/**
 * @file axutil_hash.h
 * @brief Axis2 Hash Tables
 */

#include <axutil_utils_defines.h>
#include <axutil_env.h>

#ifdef __cplusplus
extern "C"
{
#endif

    /**
     * @defgroup axutil_hash hash
     * @ingroup axis2_util
     * @{
     */

    /**
     * When passing a key to axutil_hash_set or axutil_hash_get, this value can be
     * passed to indicate a string-valued key, and have axutil_hash compute the
     * length automatically.
     *
     * @remark axutil_hash will use strlen(key) for the length. The NUL terminator
     *         is not included in the hash value (why throw a constant in?).
     *         Since the hash table merely references the provided key (rather
     *         than copying it), axutil_hash_this() will return the NUL-term'd key.
     */
#define AXIS2_HASH_KEY_STRING     (unsigned int)(-1)

    /**
     * Abstract type for hash tables.
     */
    typedef struct axutil_hash_t axutil_hash_t;

    /**
     * Abstract type for scanning hash tables.
     */
    typedef struct axutil_hash_index_t axutil_hash_index_t;

    /**
     * Callback functions for calculating hash values.
     * @param key The key.
     * @param klen The length of the key, or AXIS2_HASH_KEY_STRING to use the string
     *             length. If AXIS2_HASH_KEY_STRING then returns the actual key length.
     */
    typedef unsigned int(
        *axutil_hashfunc_t)(
            const char *key,
            axis2_ssize_t * klen);

    /**
     * The default hash function.
     */
    unsigned int axutil_hashfunc_default(
        const char *key,
        axis2_ssize_t * klen);

    /**
     * Create a hash table.
     * @param env The environment to allocate the hash table out of
     * @return The hash table just created
      */
    AXIS2_EXTERN axutil_hash_t *AXIS2_CALL
    axutil_hash_make(
        const axutil_env_t * env);

    /**
     * Create a hash table with a custom hash function
     * @param env The environment to allocate the hash table out of
     * @param hash_func A custom hash function.
     * @return The hash table just created
      */
    AXIS2_EXTERN axutil_hash_t *AXIS2_CALL
    axutil_hash_make_custom(
        const axutil_env_t * env,
        axutil_hashfunc_t hash_func);

    /**
     * Make a copy of a hash table
     * @param ht The hash table to clone
     * @param env The environment from which to allocate the new hash table
     * @return The hash table just created
     * @remark Makes a shallow copy. axutil_hash_free should not be used to free the copy.
     */
    AXIS2_EXTERN axutil_hash_t *AXIS2_CALL
    axutil_hash_copy(
        const axutil_hash_t * ht,
        const axutil_env_t * env);

    /**
     * Associate a value with a key in a hash table.
     * @param ht The hash table
     * @param key Pointer to the key
     * @param klen Length of the key. Can be AXIS2_HASH_KEY_STRING to use the string length.
     * @param val Value to associate with the key
     * @remark If the value is NULL the hash entry is deleted.
     */
    AXIS2_EXTERN void AXIS2_CALL
    axutil_hash_set(
        axutil_hash_t * ht,
        const void *key,
        axis2_ssize_t klen,
        const void *val);

    /**
     * Look up the value associated with a key in a hash table.
     * @param ht The hash table
     * @param key Pointer to the key
     * @param klen Length of the key. Can be AXIS2_HASH_KEY_STRING to use the string length.
     * @return Returns NULL if the key is not present.
     */
    AXIS2_EXTERN void *AXIS2_CALL
    axutil_hash_get(
        axutil_hash_t * ht,
        const void *key,
        axis2_ssize_t klen);

    /**
     * Start iterating over the entries in a hash table.
     * @param ht The hash table
     * @param p The environment to allocate the axutil_hash_index_t iterator. If this
     *          environment is NULL, then an internal, non-thread-safe iterator is used.
     * @remark  There is no restriction on adding or deleting hash entries during
     * an iteration (although the results may be unpredictable unless all you do
     * is delete the current entry) and multiple iterations can be in
     * progress at the same time.

     * @example
     */

    /**
     * <PRE>
     *
     * int sum_values(const axutil_env_t *env, axutil_hash_t *ht)
     * {
     *     axutil_hash_index_t *hi;
     *     void *val;
     *     int sum = 0;
     *     for (hi = axutil_hash_first(p, ht); hi; hi = axutil_hash_next(p, hi)) {
     *         axutil_hash_this(hi, NULL, NULL, &val);
     *         sum += *(int *)val;
     *     }
     *     return sum;
     * }
     * </PRE>
     */
    AXIS2_EXTERN axutil_hash_index_t *AXIS2_CALL
    axutil_hash_first(
        axutil_hash_t * ht,
        const axutil_env_t * env);

    /**
     * Continue iterating over the entries in a hash table.
     * @param hi The iteration state
     * @return a pointer to the updated iteration state.  NULL if there are no more
     *         entries.
     */
    AXIS2_EXTERN axutil_hash_index_t *AXIS2_CALL
    axutil_hash_next(
        const axutil_env_t * env,
        axutil_hash_index_t * hi);

    /**
     * Get the current entry's details from the iteration state.
     * @param hi The iteration state
     * @param key Return pointer for the pointer to the key.
     * @param klen Return pointer for the key length.
     * @param val Return pointer for the associated value.
     * @remark The return pointers should point to a variable that will be set to the
     *         corresponding data, or they may be NULL if the data isn't interesting.
     */
    AXIS2_EXTERN void AXIS2_CALL
    axutil_hash_this(
        axutil_hash_index_t * hi,
        const void **key,
        axis2_ssize_t * klen,
        void **val);

    /**
     * Get the number of key/value pairs in the hash table.
     * @param ht The hash table
     * @return The number of key/value pairs in the hash table.
     */
    AXIS2_EXTERN unsigned int AXIS2_CALL
    axutil_hash_count(
        axutil_hash_t * ht);

    /**
     * Merge two hash tables into one new hash table. The values of the overlay
     * hash override the values of the base if both have the same key.  Both
     * hash tables must use the same hash function.
     * @param overlay The table to add to the initial table
     * @param p The environment to use for the new hash table
     * @param base The table that represents the initial values of the new table
     * @return A new hash table containing all of the data from the two passed in
     */
    AXIS2_EXTERN axutil_hash_t *AXIS2_CALL
    axutil_hash_overlay(
        const axutil_hash_t * overlay,
        const axutil_env_t * env,
        const axutil_hash_t * base);

    /**
     * Merge two hash tables into one new hash table. If the same key
     * is present in both tables, call the supplied merge function to
     * produce a merged value for the key in the new table.  Both
     * hash tables must use the same hash function.
     * @param h1 The first of the tables to merge
     * @param p The environment to use for the new hash table
     * @param h2 The second of the tables to merge
     * @param merger A callback function to merge values, or NULL to
     *  make values from h1 override values from h2 (same semantics as
     *  axutil_hash_overlay())
     * @param data Client data to pass to the merger function
     * @return A new hash table containing all of the data from the two passed in
     */
    AXIS2_EXTERN axutil_hash_t *AXIS2_CALL
    axutil_hash_merge(
        const axutil_hash_t * h1,
        const axutil_env_t * env,
        const axutil_hash_t * h2,
        void *(*merger)(const axutil_env_t * env,
                const void *key,
                axis2_ssize_t klen,
                const void *h1_val,
                const void *h2_val,
                const void *data),
        const void *data);

    /**
     * Query whether the hash table provided as parameter contains the
     * key provided as parameter.
     *
     * @param ht hash table to be queried for key
     * @return return whether hash table contains key
     */
    AXIS2_EXTERN axis2_bool_t AXIS2_CALL
    axutil_hash_contains_key(
        axutil_hash_t * ht,
        const axutil_env_t * env,
        const axis2_char_t * key);

    /**
     * @param ht hash table to be freed
     * @param env The environment to use for hash table
     * @return return status code
     *
     */

    AXIS2_EXTERN void AXIS2_CALL
    axutil_hash_free(
        axutil_hash_t * ht,
        const axutil_env_t * env);

    /**
     * Free a hash table with hash table given as void
     * @param ht hash table to be freed as a void *
     * @param env The environment to use for hash table
     * @return return status code
     */

    AXIS2_EXTERN void AXIS2_CALL
    axutil_hash_free_void_arg(
        void *ht_void,
        const axutil_env_t * env);

    AXIS2_EXTERN void AXIS2_CALL
    axutil_hash_set_env(
        axutil_hash_t * ht,
        const axutil_env_t * env);

    /** @} */

#ifdef __cplusplus
}
#endif

#endif                          /* !AXIS2_HASH_H */