Annotation of win32/apache22/srclib/apr/include/apr_hash.h, revision 1.1
1.1 ! moko 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 */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to apr_hash.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / apache22 / srclib / apr / include