contrib/apr/include/apr_hash.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef APR_HASH_H
  18 #define APR_HASH_H
  19
  20 /**
  21  * @file apr_hash.h
  22  * @brief APR Hash Tables
  23  */
  24
  25 #include "apr_pools.h"
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /**
  32  * @defgroup apr_hash Hash Tables
  33  * @ingroup APR
  34  * @{
  35  */
  36
  37 /**
  38  * When passing a key to apr_hash_set or apr_hash_get, this value can be
  39  * passed to indicate a string-valued key, and have apr_hash compute the
  40  * length automatically.
  41  *
  42  * @remark apr_hash will use strlen(key) for the length. The NUL terminator
  43  *         is not included in the hash value (why throw a constant in?).
  44  *         Since the hash table merely references the provided key (rather
  45  *         than copying it), apr_hash_this() will return the NUL-term'd key.
  46  */
  47 #define APR_HASH_KEY_STRING     (-1)
  48
  49 /**
  50  * Abstract type for hash tables.
  51  */
  52 typedef struct apr_hash_t apr_hash_t;
  53
  54 /**
  55  * Abstract type for scanning hash tables.
  56  */
  57 typedef struct apr_hash_index_t apr_hash_index_t;
  58
  59 /**
  60  * Callback functions for calculating hash values.
  61  * @param key The key.
  62  * @param klen The length of the key, or APR_HASH_KEY_STRING to use the string
  63  *             length. If APR_HASH_KEY_STRING then returns the actual key length.
  64  */
  65 typedef unsigned int (*apr_hashfunc_t)(const char *key, apr_ssize_t *klen);
  66
  67 /**
  68  * The default hash function.
  69  */
  70 APR_DECLARE_NONSTD(unsigned int) apr_hashfunc_default(const char *key,
  71                                                       apr_ssize_t *klen);
  72
  73 /**
  74  * Create a hash table.
  75  * @param pool The pool to allocate the hash table out of
  76  * @return The hash table just created
  77   */
  78 APR_DECLARE(apr_hash_t *) apr_hash_make(apr_pool_t *pool);
  79
  80 /**
  81  * Create a hash table with a custom hash function
  82  * @param pool The pool to allocate the hash table out of
  83  * @param hash_func A custom hash function.
  84  * @return The hash table just created
  85   */
  86 APR_DECLARE(apr_hash_t *) apr_hash_make_custom(apr_pool_t *pool,
  87                                                apr_hashfunc_t hash_func);
  88
  89 /**
  90  * Make a copy of a hash table
  91  * @param pool The pool from which to allocate the new hash table
  92  * @param h The hash table to clone
  93  * @return The hash table just created
  94  * @remark Makes a shallow copy
  95  */
  96 APR_DECLARE(apr_hash_t *) apr_hash_copy(apr_pool_t *pool,
  97                                         const apr_hash_t *h);
  98
  99 /**
 100  * Associate a value with a key in a hash table.
 101  * @param ht The hash table
 102  * @param key Pointer to the key
 103  * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length.
 104  * @param val Value to associate with the key
 105  * @remark If the value is NULL the hash entry is deleted. The key is stored as is,
 106  *         and so must have a lifetime at least as long as the hash table's pool.
 107  */
 108 APR_DECLARE(void) apr_hash_set(apr_hash_t *ht, const void *key,
 109                                apr_ssize_t klen, const void *val);
 110
 111 /**
 112  * Look up the value associated with a key in a hash table.
 113  * @param ht The hash table
 114  * @param key Pointer to the key
 115  * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length.
 116  * @return Returns NULL if the key is not present.
 117  */
 118 APR_DECLARE(void *) apr_hash_get(apr_hash_t *ht, const void *key,
 119                                  apr_ssize_t klen);
 120
 121 /**
 122  * Start iterating over the entries in a hash table.
 123  * @param p The pool to allocate the apr_hash_index_t iterator. If this
 124  *          pool is NULL, then an internal, non-thread-safe iterator is used.
 125  * @param ht The hash table
 126  * @return The iteration state
 127  * @remark  There is no restriction on adding or deleting hash entries during
 128  * an iteration (although the results may be unpredictable unless all you do
 129  * is delete the current entry) and multiple iterations can be in
 130  * progress at the same time.
 131  *
 132  * @par Example:
 133  *
 134  * @code
 135  * int sum_values(apr_pool_t *p, apr_hash_t *ht)
 136  * {
 137  *     apr_hash_index_t *hi;
 138  *     void *val;
 139  *     int sum = 0;
 140  *     for (hi = apr_hash_first(p, ht); hi; hi = apr_hash_next(hi)) {
 141  *         apr_hash_this(hi, NULL, NULL, &val);
 142  *         sum += *(int *)val;
 143  *     }
 144  *     return sum;
 145  * }
 146  * @endcode
 147  */
 148 APR_DECLARE(apr_hash_index_t *) apr_hash_first(apr_pool_t *p, apr_hash_t *ht);
 149
 150 /**
 151  * Continue iterating over the entries in a hash table.
 152  * @param hi The iteration state
 153  * @return a pointer to the updated iteration state.  NULL if there are no more
 154  *         entries.
 155  */
 156 APR_DECLARE(apr_hash_index_t *) apr_hash_next(apr_hash_index_t *hi);
 157
 158 /**
 159  * Get the current entry's details from the iteration state.
 160  * @param hi The iteration state
 161  * @param key Return pointer for the pointer to the key.
 162  * @param klen Return pointer for the key length.
 163  * @param val Return pointer for the associated value.
 164  * @remark The return pointers should point to a variable that will be set to the
 165  *         corresponding data, or they may be NULL if the data isn't interesting.
 166  */
 167 APR_DECLARE(void) apr_hash_this(apr_hash_index_t *hi, const void **key,
 168                                 apr_ssize_t *klen, void **val);
 169
 170 /**
 171  * Get the current entry's key from the iteration state.
 172  * @param hi The iteration state
 173  * @return The pointer to the key
 174  */
 175 APR_DECLARE(const void*) apr_hash_this_key(apr_hash_index_t *hi);
 176
 177 /**
 178  * Get the current entry's key length from the iteration state.
 179  * @param hi The iteration state
 180  * @return The key length
 181  */
 182 APR_DECLARE(apr_ssize_t) apr_hash_this_key_len(apr_hash_index_t *hi);
 183
 184 /**
 185  * Get the current entry's value from the iteration state.
 186  * @param hi The iteration state
 187  * @return The pointer to the value
 188  */
 189 APR_DECLARE(void*) apr_hash_this_val(apr_hash_index_t *hi);
 190
 191 /**
 192  * Get the number of key/value pairs in the hash table.
 193  * @param ht The hash table
 194  * @return The number of key/value pairs in the hash table.
 195  */
 196 APR_DECLARE(unsigned int) apr_hash_count(apr_hash_t *ht);
 197
 198 /**
 199  * Clear any key/value pairs in the hash table.
 200  * @param ht The hash table
 201  */
 202 APR_DECLARE(void) apr_hash_clear(apr_hash_t *ht);
 203
 204 /**
 205  * Merge two hash tables into one new hash table. The values of the overlay
 206  * hash override the values of the base if both have the same key.  Both
 207  * hash tables must use the same hash function.
 208  * @param p The pool to use for the new hash table
 209  * @param overlay The table to add to the initial table
 210  * @param base The table that represents the initial values of the new table
 211  * @return A new hash table containing all of the data from the two passed in
 212  */
 213 APR_DECLARE(apr_hash_t *) apr_hash_overlay(apr_pool_t *p,
 214                                            const apr_hash_t *overlay,
 215                                            const apr_hash_t *base);
 216
 217 /**
 218  * Merge two hash tables into one new hash table. If the same key
 219  * is present in both tables, call the supplied merge function to
 220  * produce a merged value for the key in the new table.  Both
 221  * hash tables must use the same hash function.
 222  * @param p The pool to use for the new hash table
 223  * @param h1 The first of the tables to merge
 224  * @param h2 The second of the tables to merge
 225  * @param merger A callback function to merge values, or NULL to
 226  *  make values from h1 override values from h2 (same semantics as
 227  *  apr_hash_overlay())
 228  * @param data Client data to pass to the merger function
 229  * @return A new hash table containing all of the data from the two passed in
 230  */
 231 APR_DECLARE(apr_hash_t *) apr_hash_merge(apr_pool_t *p,
 232                                          const apr_hash_t *h1,
 233                                          const apr_hash_t *h2,
 234                                          void * (*merger)(apr_pool_t *p,
 235                                                      const void *key,
 236                                                      apr_ssize_t klen,
 237                                                      const void *h1_val,
 238                                                      const void *h2_val,
 239                                                      const void *data),
 240                                          const void *data);
 241
 242 /**
 243  * Declaration prototype for the iterator callback function of apr_hash_do().
 244  *
 245  * @param rec The data passed as the first argument to apr_hash_[v]do()
 246  * @param key The key from this iteration of the hash table
 247  * @param klen The key length from this iteration of the hash table
 248  * @param value The value from this iteration of the hash table
 249  * @remark Iteration continues while this callback function returns non-zero.
 250  * To export the callback function for apr_hash_do() it must be declared
 251  * in the _NONSTD convention.
 252  */
 253 typedef int (apr_hash_do_callback_fn_t)(void *rec, const void *key,
 254                                                    apr_ssize_t klen,
 255                                                    const void *value);
 256
 257 /**
 258  * Iterate over a hash table running the provided function once for every
 259  * element in the hash table. The @param comp function will be invoked for
 260  * every element in the hash table.
 261  *
 262  * @param comp The function to run
 263  * @param rec The data to pass as the first argument to the function
 264  * @param ht The hash table to iterate over
 265  * @return FALSE if one of the comp() iterations returned zero; TRUE if all
 266  *            iterations returned non-zero
 267  * @see apr_hash_do_callback_fn_t
 268  */
 269 APR_DECLARE(int) apr_hash_do(apr_hash_do_callback_fn_t *comp,
 270                              void *rec, const apr_hash_t *ht);
 271
 272 /**
 273  * Get a pointer to the pool which the hash table was created in
 274  */
 275 APR_POOL_DECLARE_ACCESSOR(hash);
 276
 277 /** @} */
 278
 279 #ifdef __cplusplus
 280 }
 281 #endif
 282
 283 #endif  /* !APR_HASH_H */