Back to index

php5  5.3.10
zend_hash.h
Go to the documentation of this file.
00001 /*
00002    +----------------------------------------------------------------------+
00003    | Zend Engine                                                          |
00004    +----------------------------------------------------------------------+
00005    | Copyright (c) 1998-2012 Zend Technologies Ltd. (http://www.zend.com) |
00006    +----------------------------------------------------------------------+
00007    | This source file is subject to version 2.00 of the Zend license,     |
00008    | that is bundled with this package in the file LICENSE, and is        | 
00009    | available through the world-wide-web at the following url:           |
00010    | http://www.zend.com/license/2_00.txt.                                |
00011    | If you did not receive a copy of the Zend license and are unable to  |
00012    | obtain it through the world-wide-web, please send a note to          |
00013    | license@zend.com so we can mail you a copy immediately.              |
00014    +----------------------------------------------------------------------+
00015    | Authors: Andi Gutmans <andi@zend.com>                                |
00016    |          Zeev Suraski <zeev@zend.com>                                |
00017    +----------------------------------------------------------------------+
00018 */
00019 
00020 /* $Id: zend_hash.h 321634 2012-01-01 13:15:04Z felipe $ */
00021 
00022 #ifndef ZEND_HASH_H
00023 #define ZEND_HASH_H
00024 
00025 #include <sys/types.h>
00026 #include "zend.h"
00027 
00028 #define HASH_KEY_IS_STRING 1
00029 #define HASH_KEY_IS_LONG 2
00030 #define HASH_KEY_NON_EXISTANT 3
00031 
00032 #define HASH_UPDATE         (1<<0)
00033 #define HASH_ADD                   (1<<1)
00034 #define HASH_NEXT_INSERT    (1<<2)
00035 
00036 #define HASH_DEL_KEY 0
00037 #define HASH_DEL_INDEX 1
00038 #define HASH_DEL_KEY_QUICK 2
00039 
00040 #define HASH_UPDATE_KEY_IF_NONE    0
00041 #define HASH_UPDATE_KEY_IF_BEFORE  1
00042 #define HASH_UPDATE_KEY_IF_AFTER   2
00043 #define HASH_UPDATE_KEY_ANYWAY     3
00044 
00045 typedef ulong (*hash_func_t)(const char *arKey, uint nKeyLength);
00046 typedef int  (*compare_func_t)(const void *, const void * TSRMLS_DC);
00047 typedef void (*sort_func_t)(void *, size_t, register size_t, compare_func_t TSRMLS_DC);
00048 typedef void (*dtor_func_t)(void *pDest);
00049 typedef void (*copy_ctor_func_t)(void *pElement);
00050 typedef void (*copy_ctor_param_func_t)(void *pElement, void *pParam);
00051 
00052 struct _hashtable;
00053 
00054 typedef struct bucket {
00055        ulong h;                                         /* Used for numeric indexing */
00056        uint nKeyLength;
00057        void *pData;
00058        void *pDataPtr;
00059        struct bucket *pListNext;
00060        struct bucket *pListLast;
00061        struct bucket *pNext;
00062        struct bucket *pLast;
00063        char arKey[1]; /* Must be last element */
00064 } Bucket;
00065 
00066 typedef struct _hashtable {
00067        uint nTableSize;
00068        uint nTableMask;
00069        uint nNumOfElements;
00070        ulong nNextFreeElement;
00071        Bucket *pInternalPointer;   /* Used for element traversal */
00072        Bucket *pListHead;
00073        Bucket *pListTail;
00074        Bucket **arBuckets;
00075        dtor_func_t pDestructor;
00076        zend_bool persistent;
00077        unsigned char nApplyCount;
00078        zend_bool bApplyProtection;
00079 #if ZEND_DEBUG
00080        int inconsistent;
00081 #endif
00082 } HashTable;
00083 
00084 
00085 typedef struct _zend_hash_key {
00086        char *arKey;
00087        uint nKeyLength;
00088        ulong h;
00089 } zend_hash_key;
00090 
00091 
00092 typedef zend_bool (*merge_checker_func_t)(HashTable *target_ht, void *source_data, zend_hash_key *hash_key, void *pParam);
00093 
00094 typedef Bucket* HashPosition;
00095 
00096 BEGIN_EXTERN_C()
00097 
00098 /* startup/shutdown */
00099 ZEND_API int _zend_hash_init(HashTable *ht, uint nSize, hash_func_t pHashFunction, dtor_func_t pDestructor, zend_bool persistent ZEND_FILE_LINE_DC);
00100 ZEND_API int _zend_hash_init_ex(HashTable *ht, uint nSize, hash_func_t pHashFunction, dtor_func_t pDestructor, zend_bool persistent, zend_bool bApplyProtection ZEND_FILE_LINE_DC);
00101 ZEND_API void zend_hash_destroy(HashTable *ht);
00102 ZEND_API void zend_hash_clean(HashTable *ht);
00103 #define zend_hash_init(ht, nSize, pHashFunction, pDestructor, persistent)                                       _zend_hash_init((ht), (nSize), (pHashFunction), (pDestructor), (persistent) ZEND_FILE_LINE_CC)
00104 #define zend_hash_init_ex(ht, nSize, pHashFunction, pDestructor, persistent, bApplyProtection)           _zend_hash_init_ex((ht), (nSize), (pHashFunction), (pDestructor), (persistent), (bApplyProtection) ZEND_FILE_LINE_CC)
00105 
00106 /* additions/updates/changes */
00107 ZEND_API int _zend_hash_add_or_update(HashTable *ht, const char *arKey, uint nKeyLength, void *pData, uint nDataSize, void **pDest, int flag ZEND_FILE_LINE_DC);
00108 #define zend_hash_update(ht, arKey, nKeyLength, pData, nDataSize, pDest) \
00109               _zend_hash_add_or_update(ht, arKey, nKeyLength, pData, nDataSize, pDest, HASH_UPDATE ZEND_FILE_LINE_CC)
00110 #define zend_hash_add(ht, arKey, nKeyLength, pData, nDataSize, pDest) \
00111               _zend_hash_add_or_update(ht, arKey, nKeyLength, pData, nDataSize, pDest, HASH_ADD ZEND_FILE_LINE_CC)
00112 
00113 ZEND_API int _zend_hash_quick_add_or_update(HashTable *ht, const char *arKey, uint nKeyLength, ulong h, void *pData, uint nDataSize, void **pDest, int flag ZEND_FILE_LINE_DC);
00114 #define zend_hash_quick_update(ht, arKey, nKeyLength, h, pData, nDataSize, pDest) \
00115               _zend_hash_quick_add_or_update(ht, arKey, nKeyLength, h, pData, nDataSize, pDest, HASH_UPDATE ZEND_FILE_LINE_CC)
00116 #define zend_hash_quick_add(ht, arKey, nKeyLength, h, pData, nDataSize, pDest) \
00117               _zend_hash_quick_add_or_update(ht, arKey, nKeyLength, h, pData, nDataSize, pDest, HASH_ADD ZEND_FILE_LINE_CC)
00118 
00119 ZEND_API int _zend_hash_index_update_or_next_insert(HashTable *ht, ulong h, void *pData, uint nDataSize, void **pDest, int flag ZEND_FILE_LINE_DC);
00120 #define zend_hash_index_update(ht, h, pData, nDataSize, pDest) \
00121               _zend_hash_index_update_or_next_insert(ht, h, pData, nDataSize, pDest, HASH_UPDATE ZEND_FILE_LINE_CC)
00122 #define zend_hash_next_index_insert(ht, pData, nDataSize, pDest) \
00123               _zend_hash_index_update_or_next_insert(ht, 0, pData, nDataSize, pDest, HASH_NEXT_INSERT ZEND_FILE_LINE_CC)
00124 
00125 ZEND_API int zend_hash_add_empty_element(HashTable *ht, const char *arKey, uint nKeyLength);
00126 
00127 
00128 #define ZEND_HASH_APPLY_KEEP                            0
00129 #define ZEND_HASH_APPLY_REMOVE                          1<<0
00130 #define ZEND_HASH_APPLY_STOP                            1<<1
00131 
00132 typedef int (*apply_func_t)(void *pDest TSRMLS_DC);
00133 typedef int (*apply_func_arg_t)(void *pDest, void *argument TSRMLS_DC);
00134 typedef int (*apply_func_args_t)(void *pDest TSRMLS_DC, int num_args, va_list args, zend_hash_key *hash_key);
00135 
00136 ZEND_API void zend_hash_graceful_destroy(HashTable *ht);
00137 ZEND_API void zend_hash_graceful_reverse_destroy(HashTable *ht);
00138 ZEND_API void zend_hash_apply(HashTable *ht, apply_func_t apply_func TSRMLS_DC);
00139 ZEND_API void zend_hash_apply_with_argument(HashTable *ht, apply_func_arg_t apply_func, void * TSRMLS_DC);
00140 ZEND_API void zend_hash_apply_with_arguments(HashTable *ht TSRMLS_DC, apply_func_args_t apply_func, int, ...);
00141 
00142 /* This function should be used with special care (in other words,
00143  * it should usually not be used).  When used with the ZEND_HASH_APPLY_STOP
00144  * return value, it assumes things about the order of the elements in the hash.
00145  * Also, it does not provide the same kind of reentrancy protection that
00146  * the standard apply functions do.
00147  */
00148 ZEND_API void zend_hash_reverse_apply(HashTable *ht, apply_func_t apply_func TSRMLS_DC);
00149 
00150 
00151 /* Deletes */
00152 ZEND_API int zend_hash_del_key_or_index(HashTable *ht, const char *arKey, uint nKeyLength, ulong h, int flag);
00153 #define zend_hash_del(ht, arKey, nKeyLength) \
00154               zend_hash_del_key_or_index(ht, arKey, nKeyLength, 0, HASH_DEL_KEY)
00155 #define zend_hash_quick_del(ht, arKey, nKeyLength, h) \
00156               zend_hash_del_key_or_index(ht, arKey, nKeyLength, h, HASH_DEL_KEY_QUICK)
00157 #define zend_hash_index_del(ht, h) \
00158               zend_hash_del_key_or_index(ht, NULL, 0, h, HASH_DEL_INDEX)
00159 
00160 ZEND_API ulong zend_get_hash_value(const char *arKey, uint nKeyLength);
00161 
00162 /* Data retreival */
00163 ZEND_API int zend_hash_find(const HashTable *ht, const char *arKey, uint nKeyLength, void **pData);
00164 ZEND_API int zend_hash_quick_find(const HashTable *ht, const char *arKey, uint nKeyLength, ulong h, void **pData);
00165 ZEND_API int zend_hash_index_find(const HashTable *ht, ulong h, void **pData);
00166 
00167 /* Misc */
00168 ZEND_API int zend_hash_exists(const HashTable *ht, const char *arKey, uint nKeyLength);
00169 ZEND_API int zend_hash_quick_exists(const HashTable *ht, const char *arKey, uint nKeyLength, ulong h);
00170 ZEND_API int zend_hash_index_exists(const HashTable *ht, ulong h);
00171 ZEND_API ulong zend_hash_next_free_element(const HashTable *ht);
00172 
00173 
00174 /* traversing */
00175 #define zend_hash_has_more_elements_ex(ht, pos) \
00176        (zend_hash_get_current_key_type_ex(ht, pos) == HASH_KEY_NON_EXISTANT ? FAILURE : SUCCESS)
00177 ZEND_API int zend_hash_move_forward_ex(HashTable *ht, HashPosition *pos);
00178 ZEND_API int zend_hash_move_backwards_ex(HashTable *ht, HashPosition *pos);
00179 ZEND_API int zend_hash_get_current_key_ex(const HashTable *ht, char **str_index, uint *str_length, ulong *num_index, zend_bool duplicate, HashPosition *pos);
00180 ZEND_API int zend_hash_get_current_key_type_ex(HashTable *ht, HashPosition *pos);
00181 ZEND_API int zend_hash_get_current_data_ex(HashTable *ht, void **pData, HashPosition *pos);
00182 ZEND_API void zend_hash_internal_pointer_reset_ex(HashTable *ht, HashPosition *pos);
00183 ZEND_API void zend_hash_internal_pointer_end_ex(HashTable *ht, HashPosition *pos);
00184 ZEND_API int zend_hash_update_current_key_ex(HashTable *ht, int key_type, const char *str_index, uint str_length, ulong num_index, int mode, HashPosition *pos);
00185 
00186 typedef struct _HashPointer {
00187        HashPosition pos;
00188        ulong h;
00189 } HashPointer;
00190 
00191 ZEND_API int zend_hash_get_pointer(const HashTable *ht, HashPointer *ptr);
00192 ZEND_API int zend_hash_set_pointer(HashTable *ht, const HashPointer *ptr);
00193 
00194 #define zend_hash_has_more_elements(ht) \
00195        zend_hash_has_more_elements_ex(ht, NULL)
00196 #define zend_hash_move_forward(ht) \
00197        zend_hash_move_forward_ex(ht, NULL)
00198 #define zend_hash_move_backwards(ht) \
00199        zend_hash_move_backwards_ex(ht, NULL)
00200 #define zend_hash_get_current_key(ht, str_index, num_index, duplicate) \
00201        zend_hash_get_current_key_ex(ht, str_index, NULL, num_index, duplicate, NULL)
00202 #define zend_hash_get_current_key_type(ht) \
00203        zend_hash_get_current_key_type_ex(ht, NULL)
00204 #define zend_hash_get_current_data(ht, pData) \
00205        zend_hash_get_current_data_ex(ht, pData, NULL)
00206 #define zend_hash_internal_pointer_reset(ht) \
00207        zend_hash_internal_pointer_reset_ex(ht, NULL)
00208 #define zend_hash_internal_pointer_end(ht) \
00209        zend_hash_internal_pointer_end_ex(ht, NULL)
00210 #define zend_hash_update_current_key(ht, key_type, str_index, str_length, num_index) \
00211        zend_hash_update_current_key_ex(ht, key_type, str_index, str_length, num_index, HASH_UPDATE_KEY_ANYWAY, NULL)
00212 
00213 /* Copying, merging and sorting */
00214 ZEND_API void zend_hash_copy(HashTable *target, HashTable *source, copy_ctor_func_t pCopyConstructor, void *tmp, uint size);
00215 ZEND_API void _zend_hash_merge(HashTable *target, HashTable *source, copy_ctor_func_t pCopyConstructor, void *tmp, uint size, int overwrite ZEND_FILE_LINE_DC);
00216 ZEND_API void zend_hash_merge_ex(HashTable *target, HashTable *source, copy_ctor_func_t pCopyConstructor, uint size, merge_checker_func_t pMergeSource, void *pParam);
00217 ZEND_API int zend_hash_sort(HashTable *ht, sort_func_t sort_func, compare_func_t compare_func, int renumber TSRMLS_DC);
00218 ZEND_API int zend_hash_compare(HashTable *ht1, HashTable *ht2, compare_func_t compar, zend_bool ordered TSRMLS_DC);
00219 ZEND_API int zend_hash_minmax(const HashTable *ht, compare_func_t compar, int flag, void **pData TSRMLS_DC);
00220 
00221 #define zend_hash_merge(target, source, pCopyConstructor, tmp, size, overwrite)                                 \
00222        _zend_hash_merge(target, source, pCopyConstructor, tmp, size, overwrite ZEND_FILE_LINE_CC)
00223 
00224 ZEND_API int zend_hash_num_elements(const HashTable *ht);
00225 
00226 ZEND_API int zend_hash_rehash(HashTable *ht);
00227 
00228 /*
00229  * DJBX33A (Daniel J. Bernstein, Times 33 with Addition)
00230  *
00231  * This is Daniel J. Bernstein's popular `times 33' hash function as
00232  * posted by him years ago on comp.lang.c. It basically uses a function
00233  * like ``hash(i) = hash(i-1) * 33 + str[i]''. This is one of the best
00234  * known hash functions for strings. Because it is both computed very
00235  * fast and distributes very well.
00236  *
00237  * The magic of number 33, i.e. why it works better than many other
00238  * constants, prime or not, has never been adequately explained by
00239  * anyone. So I try an explanation: if one experimentally tests all
00240  * multipliers between 1 and 256 (as RSE did now) one detects that even
00241  * numbers are not useable at all. The remaining 128 odd numbers
00242  * (except for the number 1) work more or less all equally well. They
00243  * all distribute in an acceptable way and this way fill a hash table
00244  * with an average percent of approx. 86%. 
00245  *
00246  * If one compares the Chi^2 values of the variants, the number 33 not
00247  * even has the best value. But the number 33 and a few other equally
00248  * good numbers like 17, 31, 63, 127 and 129 have nevertheless a great
00249  * advantage to the remaining numbers in the large set of possible
00250  * multipliers: their multiply operation can be replaced by a faster
00251  * operation based on just one shift plus either a single addition
00252  * or subtraction operation. And because a hash function has to both
00253  * distribute good _and_ has to be very fast to compute, those few
00254  * numbers should be preferred and seems to be the reason why Daniel J.
00255  * Bernstein also preferred it.
00256  *
00257  *
00258  *                  -- Ralf S. Engelschall <rse@engelschall.com>
00259  */
00260 
00261 static inline ulong zend_inline_hash_func(const char *arKey, uint nKeyLength)
00262 {
00263        register ulong hash = 5381;
00264 
00265        /* variant with the hash unrolled eight times */
00266        for (; nKeyLength >= 8; nKeyLength -= 8) {
00267               hash = ((hash << 5) + hash) + *arKey++;
00268               hash = ((hash << 5) + hash) + *arKey++;
00269               hash = ((hash << 5) + hash) + *arKey++;
00270               hash = ((hash << 5) + hash) + *arKey++;
00271               hash = ((hash << 5) + hash) + *arKey++;
00272               hash = ((hash << 5) + hash) + *arKey++;
00273               hash = ((hash << 5) + hash) + *arKey++;
00274               hash = ((hash << 5) + hash) + *arKey++;
00275        }
00276        switch (nKeyLength) {
00277               case 7: hash = ((hash << 5) + hash) + *arKey++; /* fallthrough... */
00278               case 6: hash = ((hash << 5) + hash) + *arKey++; /* fallthrough... */
00279               case 5: hash = ((hash << 5) + hash) + *arKey++; /* fallthrough... */
00280               case 4: hash = ((hash << 5) + hash) + *arKey++; /* fallthrough... */
00281               case 3: hash = ((hash << 5) + hash) + *arKey++; /* fallthrough... */
00282               case 2: hash = ((hash << 5) + hash) + *arKey++; /* fallthrough... */
00283               case 1: hash = ((hash << 5) + hash) + *arKey++; break;
00284               case 0: break;
00285 EMPTY_SWITCH_DEFAULT_CASE()
00286        }
00287        return hash;
00288 }
00289 
00290 
00291 ZEND_API ulong zend_hash_func(const char *arKey, uint nKeyLength);
00292 
00293 #if ZEND_DEBUG
00294 /* debug */
00295 void zend_hash_display_pListTail(const HashTable *ht);
00296 void zend_hash_display(const HashTable *ht);
00297 #endif
00298 
00299 END_EXTERN_C()
00300 
00301 #define ZEND_INIT_SYMTABLE(ht)                                                      \
00302        ZEND_INIT_SYMTABLE_EX(ht, 2, 0)
00303 
00304 #define ZEND_INIT_SYMTABLE_EX(ht, n, persistent)               \
00305        zend_hash_init(ht, n, NULL, ZVAL_PTR_DTOR, persistent)
00306 
00307 #define ZEND_HANDLE_NUMERIC(key, length, func) do {                                               \
00308        register const char *tmp = key;                                                                          \
00309                                                                                                                                      \
00310        if (*tmp == '-') {                                                                                              \
00311               tmp++;                                                                                                          \
00312        }                                                                                                                             \
00313        if (*tmp >= '0' && *tmp <= '9') { /* possibly a numeric index */             \
00314               const char *end = key + length - 1;                                                               \
00315               ulong idx;                                                                                                      \
00316                                                                                                                                      \
00317               if ((*end != '\0') /* not a null terminated string */                        \
00318                || (*tmp == '0' && length > 2) /* numbers with leading zeros */      \
00319                || (end - tmp > MAX_LENGTH_OF_LONG - 1) /* number too long */        \
00320                || (SIZEOF_LONG == 4 &&                                                                          \
00321                    end - tmp == MAX_LENGTH_OF_LONG - 1 &&                                                \
00322                    *tmp > '2')) { /* overflow */                                                         \
00323                      break;                                                                                                   \
00324               }                                                                                                                      \
00325               idx = (*tmp - '0');                                                                                      \
00326               while (++tmp != end && *tmp >= '0' && *tmp <= '9') {                         \
00327                      idx = (idx * 10) + (*tmp - '0');                                                    \
00328               }                                                                                                                      \
00329               if (tmp == end) {                                                                                        \
00330                      if (*key == '-') {                                                                                \
00331                             if (idx-1 > LONG_MAX) { /* overflow */                                       \
00332                                    break;                                                                                     \
00333                             }                                                                                                        \
00334                             idx = (ulong)(-(long)idx);                                                          \
00335                      } else if (idx > LONG_MAX) { /* overflow */                                         \
00336                             break;                                                                                            \
00337                      }                                                                                                               \
00338                      return func;                                                                                      \
00339               }                                                                                                                      \
00340        }                                                                                                                             \
00341 } while (0)
00342 
00343 static inline int zend_symtable_update(HashTable *ht, const char *arKey, uint nKeyLength, void *pData, uint nDataSize, void **pDest)                             \
00344 {
00345        ZEND_HANDLE_NUMERIC(arKey, nKeyLength, zend_hash_index_update(ht, idx, pData, nDataSize, pDest));
00346        return zend_hash_update(ht, arKey, nKeyLength, pData, nDataSize, pDest);
00347 }
00348 
00349 
00350 static inline int zend_symtable_del(HashTable *ht, const char *arKey, uint nKeyLength)
00351 {
00352        ZEND_HANDLE_NUMERIC(arKey, nKeyLength, zend_hash_index_del(ht, idx));
00353        return zend_hash_del(ht, arKey, nKeyLength);
00354 }
00355 
00356 
00357 static inline int zend_symtable_find(HashTable *ht, const char *arKey, uint nKeyLength, void **pData)
00358 {
00359        ZEND_HANDLE_NUMERIC(arKey, nKeyLength, zend_hash_index_find(ht, idx, pData));
00360        return zend_hash_find(ht, arKey, nKeyLength, pData);
00361 }
00362 
00363 
00364 static inline int zend_symtable_exists(HashTable *ht, const char *arKey, uint nKeyLength)
00365 {
00366        ZEND_HANDLE_NUMERIC(arKey, nKeyLength, zend_hash_index_exists(ht, idx));
00367        return zend_hash_exists(ht, arKey, nKeyLength);
00368 }
00369 
00370 static inline int zend_symtable_update_current_key_ex(HashTable *ht, const char *arKey, uint nKeyLength, int mode, HashPosition *pos)
00371 {
00372        ZEND_HANDLE_NUMERIC(arKey, nKeyLength, zend_hash_update_current_key_ex(ht, HASH_KEY_IS_LONG, NULL, 0, idx, mode, pos));
00373        return zend_hash_update_current_key_ex(ht, HASH_KEY_IS_STRING, arKey, nKeyLength, 0, mode, pos);
00374 }
00375 #define zend_symtable_update_current_key(ht,arKey,nKeyLength,mode) \
00376        zend_symtable_update_current_key_ex(ht, arKey, nKeyLength, mode, NULL)
00377 
00378 
00379 #endif                                           /* ZEND_HASH_H */
00380 
00381 /*
00382  * Local variables:
00383  * tab-width: 4
00384  * c-basic-offset: 4
00385  * indent-tabs-mode: t
00386  * End:
00387  */