hak/lib/hak-htb.h

/*
    Copyright (c) 2016-2018 Chung, Hyung-Hwan. All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
    1. Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
    2. Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.

    THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
    IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
    THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef _HAK_HTB_H_
#define _HAK_HTB_H_

#include <hak-cmn.h>

/** \file
 * This file provides a hash table encapsulated in the #hak_htb_t type that
 * maintains buckets for key/value pairs with the same key hash chained under
 * the same bucket. Its interface is very close to #hak_rbt_t.
 *
 * This sample code adds a series of keys and values and print them
 * in the randome order.
 * \code
 * #include <hak-htb.h>
 *
 * static hak_htb_walk_t walk (hak_htb_t* htb, hak_htb_pair_t* pair, void* ctx)
 * {
 *   hak_printf (HAK_T("key = %d, value = %d\n"),
 *     *(int*)HAK_HTB_KPTR(pair), *(int*)HAK_HTB_VPTR(pair));
 *   return HAK_HTB_WALK_FORWARD;
 * }
 *
 * int main ()
 * {
 *   hak_htb_t* s1;
 *   int i;
 *
 *   hak_open_stdsios ();
 *   s1 = hak_htb_open (HAK_MMGR_GETDFL(), 0, 30, 75, 1, 1); // error handling skipped
 *   hak_htb_setstyle (s1, hak_get_htb_style(HAK_HTB_STYLE_INLINE_COPIERS));
 *
 *   for (i = 0; i < 20; i++)
 *   {
 *     int x = i * 20;
 *     hak_htb_insert (s1, &i, HAK_SIZEOF(i), &x, HAK_SIZEOF(x)); // eror handling skipped
 *   }
 *
 *   hak_htb_walk (s1, walk, HAK_NULL);
 *
 *   hak_htb_close (s1);
 *   hak_close_stdsios ();
 *   return 0;
 * }
 * \endcode
 */

typedef struct hak_htb_t hak_htb_t;
typedef struct hak_htb_pair_t hak_htb_pair_t;

/**
 * The hak_htb_walk_t type defines values that the callback function can
 * return to control hak_htb_walk().
 */
enum hak_htb_walk_t
{
        HAK_HTB_WALK_STOP    = 0,
        HAK_HTB_WALK_FORWARD = 1
};
typedef enum hak_htb_walk_t hak_htb_walk_t;

/**
 * The hak_htb_id_t type defines IDs to indicate a key or a value in various
 * functions.
 */
enum hak_htb_id_t
{
	HAK_HTB_KEY = 0,
	HAK_HTB_VAL = 1
};
typedef enum hak_htb_id_t hak_htb_id_t;

/**
 * The hak_htb_copier_t type defines a pair contruction callback.
 * A special copier #HAK_HTB_COPIER_INLINE is provided. This copier enables
 * you to copy the data inline to the internal node. No freeer is invoked
 * when the node is freeed.
 */
typedef void* (*hak_htb_copier_t) (
	hak_htb_t* htb  /* hash table */,
	void*      dptr /* pointer to a key or a value */,
	hak_oow_t dlen /* length of a key or a value */
);

/**
 * The hak_htb_freeer_t defines a key/value destruction callback
 * The freeer is called when a node containing the element is destroyed.
 */
typedef void (*hak_htb_freeer_t) (
	hak_htb_t* htb,  /**< hash table */
	void*      dptr, /**< pointer to a key or a value */
	hak_oow_t dlen  /**< length of a key or a value */
);


/**
 * The hak_htb_comper_t type defines a key comparator that is called when
 * the htb needs to compare keys. A hash table is created with a default
 * comparator which performs bitwise comparison of two keys.
 * The comparator should return 0 if the keys are the same and a non-zero
 * integer otherwise.
 */
typedef int (*hak_htb_comper_t) (
	const hak_htb_t* htb,    /**< hash table */
	const void*      kptr1,  /**< key pointer */
	hak_oow_t       klen1,  /**< key length */
	const void*      kptr2,  /**< key pointer */
	hak_oow_t       klen2   /**< key length */
);

/**
 * The hak_htb_keeper_t type defines a value keeper that is called when
 * a value is retained in the context that it should be destroyed because
 * it is identical to a new value. Two values are identical if their
 * pointers and lengths are equal.
 */
typedef void (*hak_htb_keeper_t) (
	hak_htb_t* htb,    /**< hash table */
	void*      vptr,   /**< value pointer */
	hak_oow_t vlen    /**< value length */
);

/**
 * The hak_htb_sizer_t type defines a bucket size claculator that is called
 * when hash table should resize the bucket. The current bucket size + 1 is
 * passed as the hint.
 */
typedef hak_oow_t (*hak_htb_sizer_t) (
	hak_htb_t* htb,  /**< htb */
	hak_oow_t  hint  /**< sizing hint */
);

/**
 * The hak_htb_hasher_t type defines a key hash function
 */
typedef hak_oow_t (*hak_htb_hasher_t) (
	const hak_htb_t*  htb,   /**< hash table */
	const void*       kptr,  /**< key pointer */
	hak_oow_t        klen   /**< key length in bytes */
);

/**
 * The hak_htb_walker_t defines a pair visitor.
 */
typedef hak_htb_walk_t (*hak_htb_walker_t) (
	hak_htb_t*      htb,   /**< htb */
	hak_htb_pair_t* pair,  /**< pointer to a key/value pair */
	void*           ctx    /**< pointer to user-defined data */
);

/**
 * The hak_htb_cbserter_t type defines a callback function for hak_htb_cbsert().
 * The hak_htb_cbserter() function calls it to allocate a new pair for the
 * key pointed to by \a kptr of the length \a klen and the callback context
 * \a ctx. The second parameter \a pair is passed the pointer to the existing
 * pair for the key or #HAK_NULL in case of no existing key. The callback
 * must return a pointer to a new or a reallocated pair. When reallocating the
 * existing pair, this callback must destroy the existing pair and return the
 * newly reallocated pair. It must return #HAK_NULL for failure.
 */
typedef hak_htb_pair_t* (*hak_htb_cbserter_t) (
	hak_htb_t*      htb,    /**< hash table */
	hak_htb_pair_t* pair,   /**< pair pointer */
	void*            kptr,   /**< key pointer */
	hak_oow_t       klen,   /**< key length */
	void*            ctx     /**< callback context */
);


/**
 * The hak_htb_pair_t type defines hash table pair. A pair is composed of a key
 * and a value. It maintains pointers to the beginning of a key and a value
 * plus their length. The length is scaled down with the scale factor
 * specified in an owning hash table.
 */
struct hak_htb_pair_t
{
	hak_ptl_t key;
	hak_ptl_t val;

	/* management information below */
	hak_htb_pair_t* next;
};

typedef struct hak_htb_style_t hak_htb_style_t;

struct hak_htb_style_t
{
	hak_htb_copier_t copier[2];
	hak_htb_freeer_t freeer[2];
	hak_htb_comper_t comper;   /**< key comparator */
	hak_htb_keeper_t keeper;   /**< value keeper */
	hak_htb_sizer_t  sizer;    /**< bucket capacity recalculator */
	hak_htb_hasher_t hasher;   /**< key hasher */
};

/**
 * The hak_htb_style_kind_t type defines the type of predefined
 * callback set for pair manipulation.
 */
enum hak_htb_style_kind_t
{
	/** store the key and the value pointer */
	HAK_HTB_STYLE_DEFAULT,
	/** copy both key and value into the pair */
	HAK_HTB_STYLE_INLINE_COPIERS,
	/** copy the key into the pair but store the value pointer */
	HAK_HTB_STYLE_INLINE_KEY_COPIER,
	/** copy the value into the pair but store the key pointer */
	HAK_HTB_STYLE_INLINE_VALUE_COPIER
};

typedef enum hak_htb_style_kind_t  hak_htb_style_kind_t;

/**
 * The hak_htb_t type defines a hash table.
 */
struct hak_htb_t
{
	hak_t*                 hak;
	const hak_htb_style_t* style;

	hak_uint8_t            scale[2]; /**< length scale */
	hak_uint8_t            factor;   /**< load factor in percentage */

	hak_oow_t              size;
	hak_oow_t              capa;
	hak_oow_t              threshold;
	hak_oow_t              rev;

	hak_htb_pair_t**        bucket;
};

struct hak_htb_itr_t
{
	hak_htb_pair_t* pair;
	hak_oow_t       buckno;
};

typedef struct hak_htb_itr_t hak_htb_itr_t;

/**
 * The HAK_HTB_COPIER_SIMPLE macros defines a copier that remembers the
 * pointer and length of data in a pair.
 **/
#define HAK_HTB_COPIER_SIMPLE ((hak_htb_copier_t)1)

/**
 * The HAK_HTB_COPIER_INLINE macros defines a copier that copies data into
 * a pair.
 **/
#define HAK_HTB_COPIER_INLINE ((hak_htb_copier_t)2)

#define HAK_HTB_COPIER_DEFAULT (HAK_HTB_COPIER_SIMPLE)
#define HAK_HTB_FREEER_DEFAULT (HAK_NULL)
#define HAK_HTB_COMPER_DEFAULT (hak_htb_dflcomp)
#define HAK_HTB_KEEPER_DEFAULT (HAK_NULL)
#define HAK_HTB_SIZER_DEFAULT  (HAK_NULL)
#define HAK_HTB_HASHER_DEFAULT (hak_htb_dflhash)

/**
 * The HAK_HTB_SIZE() macro returns the number of pairs in a hash table.
 */
#define HAK_HTB_SIZE(m) ((const hak_oow_t)(m)->size)

/**
 * The HAK_HTB_CAPA() macro returns the maximum number of pairs that can be
 * stored in a hash table without further reorganization.
 */
#define HAK_HTB_CAPA(m) ((const hak_oow_t)(m)->capa)

#define HAK_HTB_REV(m) ((const hak_oow_t)(m)->rev)

#define HAK_HTB_FACTOR(m) (*(const int*)&(m)->factor)
#define HAK_HTB_KSCALE(m) (*(const int*)&(m)->scale[HAK_HTB_KEY])
#define HAK_HTB_VSCALE(m) (*(const int*)&(m)->scale[HAK_HTB_VAL])

#define HAK_HTB_KPTL(p) (&(p)->key)
#define HAK_HTB_VPTL(p) (&(p)->val)

#define HAK_HTB_KPTR(p) ((p)->key.ptr)
#define HAK_HTB_KLEN(p) ((p)->key.len)
#define HAK_HTB_VPTR(p) ((p)->val.ptr)
#define HAK_HTB_VLEN(p) ((p)->val.len)

#define HAK_HTB_NEXT(p) ((p)->next)

#if defined(__cplusplus)
extern "C" {
#endif

/**
 * The hak_get_htb_style() functions returns a predefined callback set for
 * pair manipulation.
 */
HAK_EXPORT const hak_htb_style_t* hak_get_htb_style (
	hak_htb_style_kind_t kind
);

/**
 * The hak_htb_open() function creates a hash table with a dynamic array
 * bucket and a list of values chained. The initial capacity should be larger
 * than 0. The load factor should be between 0 and 100 inclusive and the load
 * factor of 0 disables bucket resizing. If you need extra space associated
 * with hash table, you may pass a non-zero value for \a xtnsize.
 * The HAK_HTB_XTN() macro and the hak_htb_getxtn() function return the
 * pointer to the beginning of the extension.
 * The \a kscale and \a vscale parameters specify the unit of the key and
 * value size.
 * \return #hak_htb_t pointer on success, #HAK_NULL on failure.
 */
HAK_EXPORT hak_htb_t* hak_htb_open (
	hak_t*     hak,
	hak_oow_t  xtnsize, /**< extension size in bytes */
	hak_oow_t  capa,    /**< initial capacity */
	int        factor,  /**< load factor */
	int        kscale,  /**< key scale - 1 to 255 */
	int        vscale   /**< value scale - 1 to 255 */
);


/**
 * The hak_htb_close() function destroys a hash table.
 */
HAK_EXPORT void hak_htb_close (
	hak_htb_t* htb /**< hash table */
);

/**
 * The hak_htb_init() function initializes a hash table
 */
HAK_EXPORT int hak_htb_init (
	hak_htb_t* htb,    /**< hash table */
	hak_t*     hak,
	hak_oow_t  capa,    /**< initial capacity */
	int        factor,  /**< load factor */
	int        kscale,  /**< key scale */
	int        vscale   /**< value scale */
);

/**
 * The hak_htb_fini() funtion finalizes a hash table
 */
HAK_EXPORT void hak_htb_fini (
	hak_htb_t* htb
);

#if defined(HAK_HAVE_INLINE)
static HAK_INLINE void* hak_htb_getxtn (hak_htb_t* htb) { return (void*)(htb + 1); }
#else
#define hak_htb_getxtn(htb) ((void*)((hak_htb_t*)(htb) + 1))
#endif

/**
 * The hak_htb_getstyle() function gets manipulation callback function set.
 */
HAK_EXPORT const hak_htb_style_t* hak_htb_getstyle (
	const hak_htb_t* htb /**< hash table */
);

/**
 * The hak_htb_setstyle() function sets internal manipulation callback
 * functions for data construction, destruction, resizing, hashing, etc.
 * The callback structure pointed to by \a style must outlive the hash
 * table pointed to by \a htb as the hash table doesn't copy the contents
 * of the structure.
 */
HAK_EXPORT void hak_htb_setstyle (
	hak_htb_t*              htb,  /**< hash table */
	const hak_htb_style_t*  style /**< callback function set */
);

/**
 * The hak_htb_getsize() function gets the number of pairs in hash table.
 */
HAK_EXPORT hak_oow_t hak_htb_getsize (
	const hak_htb_t* htb
);

/**
 * The hak_htb_getcapa() function gets the number of slots allocated
 * in a hash bucket.
 */
HAK_EXPORT hak_oow_t hak_htb_getcapa (
	const hak_htb_t* htb /**< hash table */
);

HAK_EXPORT hak_oow_t hak_htb_getrev (
	const hak_htb_t* htb /**< hash table */
);

/**
 * The hak_htb_search() function searches a hash table to find a pair with a
 * matching key. It returns the pointer to the pair found. If it fails
 * to find one, it returns HAK_NULL.
 * \return pointer to the pair with a maching key,
 *         or #HAK_NULL if no match is found.
 */
HAK_EXPORT hak_htb_pair_t* hak_htb_search (
	const hak_htb_t* htb,   /**< hash table */
	const void*      kptr,  /**< key pointer */
	hak_oow_t       klen   /**< key length */
);

/**
 * The hak_htb_upsert() function searches a hash table for the pair with a
 * matching key. If one is found, it updates the pair. Otherwise, it inserts
 * a new pair with the key and value given. It returns the pointer to the
 * pair updated or inserted.
 * \return pointer to the updated or inserted pair on success,
 *         #HAK_NULL on failure.
 */
HAK_EXPORT hak_htb_pair_t* hak_htb_upsert (
	hak_htb_t* htb,   /**< hash table */
	void*      kptr,  /**< key pointer */
	hak_oow_t klen,  /**< key length */
	void*      vptr,  /**< value pointer */
	hak_oow_t vlen   /**< value length */
);

/**
 * The hak_htb_ensert() function inserts a new pair with the key and the value
 * given. If there exists a pair with the key given, the function returns
 * the pair containing the key.
 * \return pointer to a pair on success, #HAK_NULL on failure.
 */
HAK_EXPORT hak_htb_pair_t* hak_htb_ensert (
	hak_htb_t* htb,   /**< hash table */
	void*      kptr,  /**< key pointer */
	hak_oow_t klen,  /**< key length */
	void*      vptr,  /**< value pointer */
	hak_oow_t vlen   /**< value length */
);

/**
 * The hak_htb_insert() function inserts a new pair with the key and the value
 * given. If there exists a pair with the key given, the function returns
 * #HAK_NULL without channging the value.
 * \return pointer to the pair created on success, #HAK_NULL on failure.
 */
HAK_EXPORT hak_htb_pair_t* hak_htb_insert (
	hak_htb_t* htb,   /**< hash table */
	void*      kptr,  /**< key pointer */
	hak_oow_t klen,  /**< key length */
	void*      vptr,  /**< value pointer */
	hak_oow_t vlen   /**< value length */
);

/**
 * The hak_htb_update() function updates the value of an existing pair
 * with a matching key.
 * \return pointer to the pair on success, #HAK_NULL on no matching pair
 */
HAK_EXPORT hak_htb_pair_t* hak_htb_update (
	hak_htb_t* htb,   /**< hash table */
	void*      kptr,  /**< key pointer */
	hak_oow_t klen,  /**< key length */
	void*      vptr,  /**< value pointer */
	hak_oow_t vlen   /**< value length */
);

/**
 * The hak_htb_cbsert() function inserts a key/value pair by delegating pair
 * allocation to a callback function. Depending on the callback function,
 * it may behave like hak_htb_insert(), hak_htb_upsert(), hak_htb_update(),
 * hak_htb_ensert(), or totally differently. The sample code below inserts
 * a new pair if the key is not found and appends the new value to the
 * existing value delimited by a comma if the key is found.
 *
 * \code
 * #include <hak-htb.h>
 *
 * hak_htb_walk_t print_map_pair (hak_htb_t* map, hak_htb_pair_t* pair, void* ctx)
 * {
 *   hak_printf (HAK_T("%.*s[%d] => %.*s[%d]\n"),
 *     HAK_HTB_KLEN(pair), HAK_HTB_KPTR(pair), (int)HAK_HTB_KLEN(pair),
 *     HAK_HTB_VLEN(pair), HAK_HTB_VPTR(pair), (int)HAK_HTB_VLEN(pair));
 *   return HAK_HTB_WALK_FORWARD;
 * }
 *
 * hak_htb_pair_t* cbserter (
 *   hak_htb_t* htb, hak_htb_pair_t* pair,
 *   void* kptr, hak_oow_t klen, void* ctx)
 * {
 *   hak_oocs_t* v = (hak_oocs_t*)ctx;
 *   if (pair == HAK_NULL)
 *   {
 *     // no existing key for the key
 *     return hak_htb_allocpair(htb, kptr, klen, v->ptr, v->len);
 *   }
 *   else
 *   {
 *     // a pair with the key exists.
 *     // in this sample, i will append the new value to the old value
 *     // separated by a comma
 *     hak_htb_pair_t* new_pair;
 *     hak_ooch_t comma = HAK_T(',');
 *     hak_uint8_t* vptr;
 *
 *     // allocate a new pair, but without filling the actual value.
 *     // note vptr is given HAK_NULL for that purpose
 *     new_pair = hak_htb_allocpair(
 *       htb, kptr, klen, HAK_NULL, HAK_HTB_VLEN(pair) + 1 + v->len);
 *     if (new_pair == HAK_NULL) return HAK_NULL;
 *
 *     // fill in the value space
 *     vptr = HAK_HTB_VPTR(new_pair);
 *     hak_memcpy (vptr, HAK_HTB_VPTR(pair), HAK_HTB_VLEN(pair)*HAK_SIZEOF(hak_ooch_t));
 *     vptr += HAK_HTB_VLEN(pair)*HAK_SIZEOF(hak_ooch_t);
 *     hak_memcpy (vptr, &comma, HAK_SIZEOF(hak_ooch_t));
 *     vptr += HAK_SIZEOF(hak_ooch_t);
 *     hak_memcpy (vptr, v->ptr, v->len*HAK_SIZEOF(hak_ooch_t));
 *
 *     // this callback requires the old pair to be destroyed
 *     hak_htb_freepair (htb, pair);
 *
 *     // return the new pair
 *     return new_pair;
 *   }
 * }
 *
 * int main ()
 * {
 *   hak_htb_t* s1;
 *   int i;
 *   hak_ooch_t* keys[] = { HAK_T("one"), HAK_T("two"), HAK_T("three") };
 *   hak_ooch_t* vals[] = { HAK_T("1"), HAK_T("2"), HAK_T("3"), HAK_T("4"), HAK_T("5") };
 *
 *   hak_open_stdsios ();
 *   s1 = hak_htb_open (
 *     HAK_MMGR_GETDFL(), 0, 10, 70,
 *     HAK_SIZEOF(hak_ooch_t), HAK_SIZEOF(hak_ooch_t)
 *   ); // note error check is skipped
 *   hak_htb_setstyle (s1, hak_get_htb_style(HAK_HTB_STYLE_INLINE_COPIERS));
 *
 *   for (i = 0; i < HAK_COUNTOF(vals); i++)
 *   {
 *     hak_oocs_t ctx;
 *     ctx.ptr = vals[i]; ctx.len = hak_count_oocstr(vals[i]);
 *     hak_htb_cbsert (s1,
 *       keys[i%HAK_COUNTOF(keys)], hak_count_oocstr(keys[i%HAK_COUNTOF(keys)]),
 *       cbserter, &ctx
 *     ); // note error check is skipped
 *   }
 *   hak_htb_walk (s1, print_map_pair, HAK_NULL);
 *
 *   hak_htb_close (s1);
 *   hak_close_stdsios ();
 *   return 0;
 * }
 * \endcode
 */
HAK_EXPORT hak_htb_pair_t* hak_htb_cbsert (
	hak_htb_t*         htb,      /**< hash table */
	void*              kptr,     /**< key pointer */
	hak_oow_t          klen,     /**< key length */
	hak_htb_cbserter_t cbserter, /**< callback function */
	void*              ctx       /**< callback context */
);

/**
 * The hak_htb_delete() function deletes a pair with a matching key
 * \return 0 on success, -1 on failure
 */
HAK_EXPORT int hak_htb_delete (
	hak_htb_t*  htb,   /**< hash table */
	const void* kptr, /**< key pointer */
	hak_oow_t   klen   /**< key length */
);

/**
 * The hak_htb_clear() function empties a hash table
 */
HAK_EXPORT void hak_htb_clear (
	hak_htb_t* htb /**< hash table */
);

/**
 * The hak_htb_walk() function traverses a hash table.
 */
HAK_EXPORT void hak_htb_walk (
	hak_htb_t*       htb,    /**< hash table */
	hak_htb_walker_t walker, /**< callback function for each pair */
	void*            ctx     /**< pointer to user-specific data */
);

HAK_EXPORT void hak_init_htb_itr (
	hak_htb_itr_t* itr
);

/**
 * The hak_htb_getfirstpair() function returns the pointer to the first pair
 * in a hash table.
 */
HAK_EXPORT hak_htb_pair_t* hak_htb_getfirstpair (
	hak_htb_t*     htb,   /**< hash table */
	hak_htb_itr_t* itr    /**< iterator*/
);

/**
 * The hak_htb_getnextpair() function returns the pointer to the next pair
 * to the current pair \a pair in a hash table.
 */
HAK_EXPORT hak_htb_pair_t* hak_htb_getnextpair (
	hak_htb_t*      htb,    /**< hash table */
	hak_htb_itr_t*  itr    /**< iterator*/
);

/**
 * The hak_htb_allocpair() function allocates a pair for a key and a value
 * given. But it does not chain the pair allocated into the hash table \a htb.
 * Use this function at your own risk.
 *
 * Take note of he following special behavior when the copier is
 * #HAK_HTB_COPIER_INLINE.
 * - If \a kptr is #HAK_NULL, the key space of the size \a klen is reserved but
 *   not propagated with any data.
 * - If \a vptr is #HAK_NULL, the value space of the size \a vlen is reserved
 *   but not propagated with any data.
 */
HAK_EXPORT hak_htb_pair_t* hak_htb_allocpair (
	hak_htb_t* htb,
	void*      kptr,
	hak_oow_t  klen,
	void*      vptr,
	hak_oow_t  vlen
);

/**
 * The hak_htb_freepair() function destroys a pair. But it does not detach
 * the pair destroyed from the hash table \a htb. Use this function at your
 * own risk.
 */
HAK_EXPORT void hak_htb_freepair (
	hak_htb_t*      htb,
	hak_htb_pair_t* pair
);

/**
 * The hak_htb_dflhash() function is a default hash function.
 */
HAK_EXPORT hak_oow_t hak_htb_dflhash (
	const hak_htb_t*  htb,
	const void*       kptr,
	hak_oow_t         klen
);

/**
 * The hak_htb_dflcomp() function is default comparator.
 */
HAK_EXPORT int hak_htb_dflcomp (
	const hak_htb_t* htb,
	const void*      kptr1,
	hak_oow_t        klen1,
	const void*      kptr2,
	hak_oow_t        klen2
);

#if defined(__cplusplus)
}
#endif

#endif