Hash Tables

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.