rubbos/app/httpd-2.0.64/srclib/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 null-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 null-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  * Create a hash table.
  61  * @param pool The pool to allocate the hash table out of
  62  * @return The hash table just created
  63   */
  64 APR_DECLARE(apr_hash_t *) apr_hash_make(apr_pool_t *pool);
  65
  66 /**
  67  * Make a copy of a hash table
  68  * @param pool The pool from which to allocate the new hash table
  69  * @param h The hash table to clone
  70  * @return The hash table just created
  71  * @remark Makes a shallow copy
  72  */
  73 APR_DECLARE(apr_hash_t *) apr_hash_copy(apr_pool_t *pool,
  74                                         const apr_hash_t *h);
  75
  76 /**
  77  * Associate a value with a key in a hash table.
  78  * @param ht The hash table
  79  * @param key Pointer to the key
  80  * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length.
  81  * @param val Value to associate with the key
  82  * @remark If the value is NULL the hash entry is deleted.
  83  */
  84 APR_DECLARE(void) apr_hash_set(apr_hash_t *ht, const void *key,
  85                                apr_ssize_t klen, const void *val);
  86
  87 /**
  88  * Look up the value associated with a key in a hash table.
  89  * @param ht The hash table
  90  * @param key Pointer to the key
  91  * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length.
  92  * @return Returns NULL if the key is not present.
  93  */
  94 APR_DECLARE(void *) apr_hash_get(apr_hash_t *ht, const void *key,
  95                                  apr_ssize_t klen);
  96
  97 /**
  98  * Start iterating over the entries in a hash table.
  99  * @param p The pool to allocate the apr_hash_index_t iterator. If this
 100  *          pool is NULL, then an internal, non-thread-safe iterator is used.
 101  * @param ht The hash table
 102  * @remark  There is no restriction on adding or deleting hash entries during
 103  * an iteration (although the results may be unpredictable unless all you do
 104  * is delete the current entry) and multiple iterations can be in
 105  * progress at the same time.
 106
 107  * @example
 108  */
 109 /**
 110  * <PRE>
 111  *
 112  * int sum_values(apr_pool_t *p, apr_hash_t *ht)
 113  * {
 114  *     apr_hash_index_t *hi;
 115  *     void *val;
 116  *     int sum = 0;
 117  *     for (hi = apr_hash_first(p, ht); hi; hi = apr_hash_next(hi)) {
 118  *         apr_hash_this(hi, NULL, NULL, &val);
 119  *         sum += *(int *)val;
 120  *     }
 121  *     return sum;
 122  * }
 123  * </PRE>
 124  */
 125 APR_DECLARE(apr_hash_index_t *) apr_hash_first(apr_pool_t *p, apr_hash_t *ht);
 126
 127 /**
 128  * Continue iterating over the entries in a hash table.
 129  * @param hi The iteration state
 130  * @return a pointer to the updated iteration state.  NULL if there are no more
 131  *         entries.
 132  */
 133 APR_DECLARE(apr_hash_index_t *) apr_hash_next(apr_hash_index_t *hi);
 134
 135 /**
 136  * Get the current entry's details from the iteration state.
 137  * @param hi The iteration state
 138  * @param key Return pointer for the pointer to the key.
 139  * @param klen Return pointer for the key length.
 140  * @param val Return pointer for the associated value.
 141  * @remark The return pointers should point to a variable that will be set to the
 142  *         corresponding data, or they may be NULL if the data isn't interesting.
 143  */
 144 APR_DECLARE(void) apr_hash_this(apr_hash_index_t *hi, const void **key,
 145                                 apr_ssize_t *klen, void **val);
 146
 147 /**
 148  * Get the number of key/value pairs in the hash table.
 149  * @param ht The hash table
 150  * @return The number of key/value pairs in the hash table.
 151  */
 152 APR_DECLARE(unsigned int) apr_hash_count(apr_hash_t *ht);
 153
 154 /**
 155  * Merge two hash tables into one new hash table. The values of the overlay
 156  * hash override the values of the base if both have the same key.
 157  * @param p The pool to use for the new hash table
 158  * @param overlay The table to add to the initial table
 159  * @param base The table that represents the initial values of the new table
 160  * @return A new hash table containing all of the data from the two passed in
 161  */
 162 APR_DECLARE(apr_hash_t *) apr_hash_overlay(apr_pool_t *p,
 163                                            const apr_hash_t *overlay,
 164                                            const apr_hash_t *base);
 165
 166 /**
 167  * Merge two hash tables into one new hash table. If the same key
 168  * is present in both tables, call the supplied merge function to
 169  * produce a merged value for the key in the new table.
 170  * @param p The pool to use for the new hash table
 171  * @param h1 The first of the tables to merge
 172  * @param h2 The second of the tables to merge
 173  * @param merger A callback function to merge values, or NULL to
 174  *  make values from h1 override values from h2 (same semantics as
 175  *  apr_hash_overlay())
 176  * @param data Client data to pass to the merger function
 177  * @return A new hash table containing all of the data from the two passed in
 178  */
 179 APR_DECLARE(apr_hash_t *) apr_hash_merge(apr_pool_t *p,
 180                                          const apr_hash_t *h1,
 181                                          const apr_hash_t *h2,
 182                                          void * (*merger)(apr_pool_t *p,
 183                                                      const void *key,
 184                                                      apr_ssize_t klen,
 185                                                      const void *h1_val,
 186                                                      const void *h2_val,
 187                                                      const void *data),
 188                                          const void *data);
 189
 190 /**
 191  * Get a pointer to the pool which the hash table was created in
 192  */
 193 APR_POOL_DECLARE_ACCESSOR(hash);
 194
 195 /** @} */
 196
 197 #ifdef __cplusplus
 198 }
 199 #endif
 200
 201 #endif  /* !APR_HASH_H */