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.
 106  */
 107 APR_DECLARE(void) apr_hash_set(apr_hash_t *ht, const void *key,
 108                                apr_ssize_t klen, const void *val);
 109
 110 /**
 111  * Look up the value associated with a key in a hash table.
 112  * @param ht The hash table
 113  * @param key Pointer to the key
 114  * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length.
 115  * @return Returns NULL if the key is not present.
 116  */
 117 APR_DECLARE(void *) apr_hash_get(apr_hash_t *ht, const void *key,
 118                                  apr_ssize_t klen);
 119
 120 /**
 121  * Start iterating over the entries in a hash table.
 122  * @param p The pool to allocate the apr_hash_index_t iterator. If this
 123  *          pool is NULL, then an internal, non-thread-safe iterator is used.
 124  * @param ht The hash table
 125  * @return The iteration state
 126  * @remark  There is no restriction on adding or deleting hash entries during
 127  * an iteration (although the results may be unpredictable unless all you do
 128  * is delete the current entry) and multiple iterations can be in
 129  * progress at the same time.
 130  *
 131  * @par Example:
 132  *
 133  * @code
 134  * int sum_values(apr_pool_t *p, apr_hash_t *ht)
 135  * {
 136  *     apr_hash_index_t *hi;
 137  *     void *val;
 138  *     int sum = 0;
 139  *     for (hi = apr_hash_first(p, ht); hi; hi = apr_hash_next(hi)) {
 140  *         apr_hash_this(hi, NULL, NULL, &val);
 141  *         sum += *(int *)val;
 142  *     }
 143  *     return sum;
 144  * }
 145  * @endcode
 146  */
 147 APR_DECLARE(apr_hash_index_t *) apr_hash_first(apr_pool_t *p, apr_hash_t *ht);
 148
 149 /**
 150  * Continue iterating over the entries in a hash table.
 151  * @param hi The iteration state
 152  * @return a pointer to the updated iteration state.  NULL if there are no more
 153  *         entries.
 154  */
 155 APR_DECLARE(apr_hash_index_t *) apr_hash_next(apr_hash_index_t *hi);
 156
 157 /**
 158  * Get the current entry's details from the iteration state.
 159  * @param hi The iteration state
 160  * @param key Return pointer for the pointer to the key.
 161  * @param klen Return pointer for the key length.
 162  * @param val Return pointer for the associated value.
 163  * @remark The return pointers should point to a variable that will be set to the
 164  *         corresponding data, or they may be NULL if the data isn't interesting.
 165  */
 166 APR_DECLARE(void) apr_hash_this(apr_hash_index_t *hi, const void **key,
 167                                 apr_ssize_t *klen, void **val);
 168
 169 /**
 170  * Get the number of key/value pairs in the hash table.
 171  * @param ht The hash table
 172  * @return The number of key/value pairs in the hash table.
 173  */
 174 APR_DECLARE(unsigned int) apr_hash_count(apr_hash_t *ht);
 175
 176 /**
 177  * Clear any key/value pairs in the hash table.
 178  * @param ht The hash table
 179  */
 180 APR_DECLARE(void) apr_hash_clear(apr_hash_t *ht);
 181
 182 /**
 183  * Merge two hash tables into one new hash table. The values of the overlay
 184  * hash override the values of the base if both have the same key.  Both
 185  * hash tables must use the same hash function.
 186  * @param p The pool to use for the new hash table
 187  * @param overlay The table to add to the initial table
 188  * @param base The table that represents the initial values of the new table
 189  * @return A new hash table containing all of the data from the two passed in
 190  */
 191 APR_DECLARE(apr_hash_t *) apr_hash_overlay(apr_pool_t *p,
 192                                            const apr_hash_t *overlay,
 193                                            const apr_hash_t *base);
 194
 195 /**
 196  * Merge two hash tables into one new hash table. If the same key
 197  * is present in both tables, call the supplied merge function to
 198  * produce a merged value for the key in the new table.  Both
 199  * hash tables must use the same hash function.
 200  * @param p The pool to use for the new hash table
 201  * @param h1 The first of the tables to merge
 202  * @param h2 The second of the tables to merge
 203  * @param merger A callback function to merge values, or NULL to
 204  *  make values from h1 override values from h2 (same semantics as
 205  *  apr_hash_overlay())
 206  * @param data Client data to pass to the merger function
 207  * @return A new hash table containing all of the data from the two passed in
 208  */
 209 APR_DECLARE(apr_hash_t *) apr_hash_merge(apr_pool_t *p,
 210                                          const apr_hash_t *h1,
 211                                          const apr_hash_t *h2,
 212                                          void * (*merger)(apr_pool_t *p,
 213                                                      const void *key,
 214                                                      apr_ssize_t klen,
 215                                                      const void *h1_val,
 216                                                      const void *h2_val,
 217                                                      const void *data),
 218                                          const void *data);
 219
 220 /**
 221  * Declaration prototype for the iterator callback function of apr_hash_do().
 222  *
 223  * @param rec The data passed as the first argument to apr_hash_[v]do()
 224  * @param key The key from this iteration of the hash table
 225  * @param klen The key length from this iteration of the hash table
 226  * @param value The value from this iteration of the hash table
 227  * @remark Iteration continues while this callback function returns non-zero.
 228  * To export the callback function for apr_hash_do() it must be declared
 229  * in the _NONSTD convention.
 230  */
 231 typedef int (apr_hash_do_callback_fn_t)(void *rec, const void *key,
 232                                                    apr_ssize_t klen,
 233                                                    const void *value);
 234
 235 /**
 236  * Iterate over a hash table running the provided function once for every
 237  * element in the hash table. The @param comp function will be invoked for
 238  * every element in the hash table.
 239  *
 240  * @param comp The function to run
 241  * @param rec The data to pass as the first argument to the function
 242  * @param ht The hash table to iterate over
 243  * @return FALSE if one of the comp() iterations returned zero; TRUE if all
 244  *            iterations returned non-zero
 245  * @see apr_hash_do_callback_fn_t
 246  */
 247 APR_DECLARE(int) apr_hash_do(apr_hash_do_callback_fn_t *comp,
 248                              void *rec, const apr_hash_t *ht);
 249
 250 /**
 251  * Get a pointer to the pool which the hash table was created in
 252  */
 253 APR_POOL_DECLARE_ACCESSOR(hash);
 254
 255 /** @} */
 256
 257 #ifdef __cplusplus
 258 }
 259 #endif
 260
 261 #endif  /* !APR_HASH_H */