Hash Tables

2017-11-03 09:05:08

int zend_hash_init(HashTable *ht, uint nSize, hash_func_t pHashFunction, dtor_func_t pDestructor, zend_bool persistent); int zend_hash_init_ex(HashTable *ht, uint nSize, hash_func_t pHashFunction, dtor_func_t pDestructor, zend_bool persistent, zend_bool bApplyProtection);

Creates a raw HashTable. The array_init() and zval_ptr_dtor() methods should be preferred for these tasks when possible.

Argument	Purpose
`ht`	`HashTable` object being initialized, destroyed, or cleaned.
`nSize`	Nominal count of elements the `HashTable` is expected to hold. Increasing this number will require more memory, however making it too small will encourage costly reindexing operations. Note that this value is automatically rounded up to the next higher power of 2.
`pHashFunction`	Deprecated. Older versions of the Zend Engine allowed the hashing function to be overridden. Current versions force `DJBX33A`.
`pDestructor`	Function called automatically whenever an element is removed from the `HashTable` or replaced.
`persistent`	When set to a nonzero value, persistent memory allocators will be used rather than the per-request `emalloc()` family.
`bApplyProtection`	When set to a nonzero value, attempts to traverse the `HashTable` iteratively will be throttled to a maximum number of recursions.

int zend_hash_add(HashTable *ht, char *arKey, uint nKeyLength, void *pData, uint nDataSize, void **pDest); int zend_hash_update(HashTable *ht, char *arKey, uint nKeyLength, void *pData, uint nDataSize, void **pDest); int zend_hash_quick_add(HashTable *ht, char *arKey, uint nKeyLength, ulong hash_value, void *pData, uint nDataSize, void **pDest); int zend_hash_quick_update(HashTable *ht, char *arKey, uint nKeyLength, ulong hash_value, void *pData, uint nDataSize, void **pDest); int zend_hash_index_update(HashTable *ht, ulong index, void *pData, uint nDataSize, void **pDest); int zend_hash_next_insert(HashTable *ht, void *pData, uint nDataSize, void **pDest);

Argument	Purpose
`ht`	`HashTable` being modified.
`arKey`	`NULL`-terminated associative key string.
`nKeyLength`	Length of `arKey` including trailing `NULL` byte.
`index`	Numeric hash index.
`hash_value`	Precomputed associative key hash value.
`pData`	Pointer to data to be stored.
`nDataSize`	Size of the data being stored in bytes.
`pDest`	If requested, populated with a pointer to where the duplicate of the data pointed to by `pData` resides within the `HashTable`. Allows for modifying in place.

void zend_hash_clean(HashTable *ht); void zend_hash_destroy(HashTable *ht); void zend_hash_graceful_destroy(HashTable *ht); void zend_hash_graceful_reverse_destroy(HashTable *ht);

zend_hash_clean() will merely empty a HashTable's contents while the destroy variants will deallocate all internal structures and leave the HashTable unusable. A graceful shutdown takes slightly longer; however, it keeps the HashTable in a consistent state to allow access and modifications to be made during destruction.

void zend_hash_apply(HashTable *ht, apply_func_t apply_func TSRMLS_DC); void zend_hash_apply_with_argument(HashTable *ht, apply_func_arg_t apply_func, void *arg TSRMLS_DC); void zend_hash_apply_with_arguments(HashTable *ht, apply_func_args_t apply_func, int, ...); void zend_hash_reverse_apply(HashTable *ht, apply_func_t apply_func TSRMLS_DC);

Iterates through a HashTable calling an apply function for each element while passing optional parameters.

Argument	Purpose
`ht`	`HashTable` to traverse.
`apply_func`	Callback function conforming to the appropriate prototype; refer to Chapter 8, "Working with Arrays and HashTables," for more information.
`arg`	Generic pointer argument for single `arg` passing.
`arg_count`	Number of arguments that will follow in the variable argument list.
`...`	Variable argument list containing `arg_count` arguments for the apply function.

void zend_hash_internal_pointer_reset_ex(HashTable *ht, HashPosition *pos); int zend_hash_move_forward_ex(HashTable *ht, HashPosition *pos); int zend_hash_move_backwards_ex(HashTable *ht, HashPosition *pos); void zend_hash_internal_pointer_end_ex(HashTable *ht, HashPosition *pos);

Manually traverses a HashTable using a HashPosition indicator.

Argument	Purpose
`ht`	`HashTable` being traversed.
`pos`	Ephemeral position indicator. This value will be automatically initialized by `zend_hash_internal_pointer_reset_ex()`, and does not need to be destroyed.

int zend_hash_get_current_key_type_ex(HashTable *ht, HashPosition *pos);

Determines the key type at the HashTable position indicated by pos. Returns one of three values: HASH_KEY_IS_LONG, HASH_KEY_IS_STRING, or HASH_KEY_NON_EXISTANT.

int zend_hash_get_current_key_ex(HashTable *ht, char **str_index, uint *str_length, ulong *num_index, zend_bool duplicate, HashPosition *pos); int zend_hash_get_current_data_ex(HashTable *ht, void **pData, HashPosition *pos);

Inspects the key and data elements at the current HashTable position. Data variant returns SUCCESS or FAILURE, key variant returns key type as described under zend_hash_get_current_key_type_ex().

Argument	Purpose
`ht`	`HashTable` being examined.
`str_index`	Populated with associative key name.
`str_length`	Populated with length of associative key. This value will include the trailing `NULL` byte.
`num_index`	Populated with numeric key index.
`duplicate`	Set to a nonzero value if the key name should be duplicated before being returned to the calling scope, in which case the calling scope is required to free the duplicate copy at the appropriate time.
`pData`	Populated with a pointer to the data as held in the `HashTable's` internal storage. This value can be modified directly, passively inspected, or copied into a local structure.
`pos`	Current `HashTable` TRaversal position.

int zend_hash_exists(HashTable *ht, char *arKey, uint nKeyLength); int zend_hash_quick_exists(HashTable *ht, char *arKey, uint nKeyLength, ulong hash_value); int zend_hash_index_exists(HashTable *ht, ulong index);

Determines whether a given position in a HashTable is occupied. Returns 1 if the index or key exists, and 0 if it doesn't.

Argument	Purpose
`ht`	`HashTable` being examined
`arKey`	Associative key name
`nKeyLength`	Length of key name including trailing `NULL` byte
`hash_value`	Precomputed key hash, as returned by `zend_get_hash_value()`
`index`	Numeric key index

int zend_hash_find(HashTable *ht, char *arKey, uint nKeyLength, void **pData); int zend_hash_quick_find(HashTable *ht, char *arKey, uint nKeyLength, ulong hash_value, void **pData); int zend_hash_index_find(HashTable *ht, ulong index, void **pData);

Fetches a data element from a HashTable by key or index.

Argument	Purpose
`ht`	`HashTable` being examined
`arKey`	Associative key name
`nKeyLength`	Length of key name including trailing `NULL` byte
`hash_value`	Pre-computed key hash, as returned by `zend_get_hash_value()`
`index`	Numeric key index

int zend_hash_update_current_key_ex(HashTable *ht, int key_type, char *str_index, uint str_length, ulong num_index, HashPosition *pos);

Changes the key or index associated with the current data bucket. May also change a given HashTable position from indexed to associative or vice versa.

Argument	Purpose
`ht`	`HashTable` being modified
`key_type`	New key type: `HASH_KEY_IS_LONG`, or `HASH_KEY_IS_STRING`
`str_index`	Associative key valueonly used with `HASH_KEY_IS_STRING`
`str_length`	Length of associative key value
`index`	Numeric indexonly used with `HASH_KEY_IS_LONG`
`pos`	Current `HashTable` traversal position

int zend_hash_del(HashTable *ht, char *arKey, uint nKeyLength); int zend_hash_index_del(HashTable *ht, ulong index);

Deletes an element from a HashTable by index or associative key.

Argument	Purpose
`ht`	`HashTable` being modified
`arKey`	`NULL`-terminated associative key
`nKeyLength`	Length of `arKey` including the terminating `NULL` byte
`index`	Numeric index value

void zend_hash_copy(HashTable *dst, HashTable *src, copy_ctor_func_t pCopyConstructor, void *tmp, uint size); void zend_hash_merge(HashTable *dst, HashTable *src, copy_ctor_func_t pCopyConstructor, void *tmp, uint size, int overwrite); void zend_hash_merge_ex(HashTable *dst, HashTable *src, copy_ctor_func_t pCopyConstructor, uint size, merge_checker_func_t pMergeSource, void *pParam);

Copies elements from src to dst using the pCopyConstructor method to perform additional resource duplication if needed. With zend_hash_copy(), every element in src will be copied to dst. zend_hash_merge() behaves the same way unless the value of overwrite is set to zero, in which case existing keys/indexes will remain unchanged. zend_hash_merge_ex() uses a callback method to determine on an individual basis if an element should or should not be replaced. Refer to Chapter 8, "Working with Arrays and HashTables" for more information.

Argument	Purpose
`dst`	Destination `HashTable`.
`src`	Source `HashTable`.
`tmp`	Temporary holder variable with enough space to store any one element from `src`. Note: Unused since PHP version 4.0.3.
`size`	Size of member elements.
`pCopyConstructor`	Callback used to duplicate element subdata.
`pMergeChecker`	Callback to compare source and dest keys and values to determine if they should be replaced.
`pParam`	Arbitrary parameter to pass along to `pMergeChecker` function.
`overwrite`	Set to a nonzero value to make `zend_hash_merge()` behave like `zend_hash_copy()`.

int zend_hash_sort(HashTable *ht, sort_func_t sort_func, compare_func_t compare_func, int renumber TSRMLS_DC); int zend_hash_compare(HashTable *ht, HashTable *ht2, compare_func_t compare_func, zend_bool ordered TSRMLS_DC);

Sorts a given HashTable or compare it to another one. For examples of using these API calls, refer to Chapter 8.

Argument	Purpose
`ht`	Main `HashTable` being sorted or compared.
`ht2`	Secondary `HashTable` being compared to.
`sort_func`	Callback to method that will handle the actual sort operation.
`compare_func`	Callback to compare an individual element of `ht` to an individual element of `ht2`.
`renumber`	Set to nonzero if numeric indexes should be renumbered from zero as they are sorted.
`ordered`	Set to nonzero to compare based on order within the `HashTable` rather than intrinsic index or key value.

int zend_hash_num_elements(HashTable *ht); ulong zend_hash_next_free_element(HashTable *ht); int zend_hash_minmax(HashTable *ht, compare_func_t compare_func, int findmax, void **pData TSRMLS_DC);

Returns the number of elements, the next assignable index number, and the lowest/highest valued data in a HashTable respectively.

Argument	Purpose
`ht`	`HashTable` being inspected.
`compare_func`	Comparison function for determining the greatest/least value.
`findmax`	Set to nonzero to find the maximum value, or zero to find the minimum value.
`pData`	Populated with the minimum/maximum value as determined by `compare_func`.

ulong zend_hash_func(char *arKey, uint nKeyLength); ulong zend_get_hash_value(char *arKey, uint nKeyLength);

Identical functions meant to return a hash value based on arKey and nKeyLength using the built-in DJBX33A hashing function.

Категории