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.


The PHP Life Cycle

Variables from the Inside Out

Memory Management

Setting Up a Build Environment

Your First Extension

Returning Values

Accepting Parameters

Working with Arrays and HashTables

The Resource Data Type

PHP4 Objects

PHP5 Objects

Startup, Shutdown, and a Few Points in Between

INI Settings

Accessing Streams

Implementing Streams

Diverting the Stream

Configuration and Linking

Extension Generators

Setting Up a Host Environment

Advanced Embedding

Appendix A. A Zend API Reference

Appendix B. PHPAPI

Appendix C. Extending and Embedding Cookbook

Appendix D. Additional Resources



Extending and Embedding PHP
Extending and Embedding PHP
ISBN: 067232704X
EAN: 2147483647
Year: 2007
Pages: 175
Authors: Sara Golemon

Flylib.com © 2008-2020.
If you may any questions please contact us: flylib@qtcs.net