<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 332491 $ -->
<chapter xml:id="internals2.variables" xmlns="http://docbook.org/ns/docbook">
 <title>Working with Variables</title>
 <section xml:id="internals2.variables.intro">
  <title>Introduction to Variables</title>
  <para>
   A good understanding of how variables are stored and manipulated is essential to becoming a <code>Hacker</code>.
   The engine attempts to cover up the complexity of the concept of a variable that can be any type by 
   providing a uniform and intuitive set of macros for accessing the structures various fields. As the <code>Hacker</code> works
   through this chapter, they should become comfortable with the terminology and concepts involved with Variables in PHP.
  </para>
  <note>
   <para>PHP is a dynamic, loosely typed language, that uses copy-on-write and reference counting.</para>
  </note>
  <para>
   To clarify what exactly is meant by the statement above: PHP is a high level language, weak typing is implicit of the engines preference to
   convert, or coerce variables into the required type at execution type. Reference counting is the means by which the engine can deduce when a
   variable no longer has any references in the users code, and so is able to free the structures associated with the variable.
  </para>
  <para>
   All variables in PHP are represented by one structure, the <code>zval</code>:
  </para>
  <screen>
<![CDATA[
typedef struct _zval_struct {
    zvalue_value value;        /* variable value */
    zend_uint refcount__gc;    /* reference counter */
    zend_uchar type;           /* value type */
    zend_uchar is_ref__gc;     /* reference flag */
} zval;]]>
  </screen>
  <para>
   The <code>zval_value</code> is a union which can represent all types a variable may hold:
  </para>
  <screen>
<![CDATA[
typedef union _zvalue_value {
    long lval;                 /* long value */
    double dval;               /* double value */
    struct {                   
        char *val;
        int len;               /* this will always be set for strings */
    } str;                     /* string (always has length) */
    HashTable *ht;             /* an array */
    zend_object_value obj;     /* stores an object store handle, and handlers */
} zvalue_value;
]]>
  </screen>
  <para>
   It should be clear from the structures above that a variable can be of one type, the variable data is represented by the appropriate field in the <code>zval_value</code> union. The <code>zval</code> itself holds the type, reference count and a flag to indicate if a variable is a reference.
  </para>
  <table xml:id="internals2.variables.types.api">
   <title>Native Type Constants</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Constant</entry>
      <entry>Mapping</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry><code>IS_NULL</code></entry>
      <entry>no value is set in this case</entry>
     </row>
     
     <row>
      <entry><code>IS_LONG</code></entry>
      <entry>lval</entry>
     </row>
     
     <row>
      <entry><code>IS_DOUBLE</code></entry>
      <entry>dval</entry>
     </row>
     
     <row>
      <entry><code>IS_BOOL</code></entry>
      <entry>lval</entry>
     </row>
     
     <row>
      <entry>IS_RESOURCE</entry>
      <entry>lval</entry>
     </row>
     
     <row>
      <entry>IS_STRING</entry>
      <entry>str</entry>
     </row>
     
     <row>
      <entry><code>IS_ARRAY</code></entry>
      <entry>ht</entry>
     </row>
     
     <row>
      <entry><code>IS_OBJECT</code></entry>
      <entry>obj</entry>
     </row>
     
    </tbody>
   </tgroup>
  </table>
  
  <note>
   <para>There are additional constants that help to identify internal types such as constant arrays and callable objects, their usage is outside the scope of this part of the documentation.</para>
  </note>
  
  <para>
   The following table defines the macros exposed by the engine for working with <code>zval</code> values:
  </para>
  
  <table xml:id="internals2.variables.zvals.api">
   <title>Accessor Macros</title>
   <tgroup cols="3">
    <thead>
     <row>
      <entry>Prototype</entry>
      <entry>Accesses</entry>
      <entry>Description</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry><code>zend_uchar Z_TYPE(zval zv)</code></entry>
      <entry>type</entry>
      <entry>returns the type of the <code>value</code></entry>
     </row>
     
     <row>
      <entry><code>long Z_LVAL(zval zv)</code></entry>
      <entry>value.lval</entry>
      <entry></entry>
     </row>
     
     <row>
      <entry><code>zend_bool Z_BVAL(zval zv)</code></entry>
      <entry>value.lval</entry>
      <entry>cast long <code>value</code> to zend_bool</entry>
     </row>
     
     <row>
      <entry><code>double Z_DVAL(zval zv)</code></entry>
      <entry>value.dval</entry>
      <entry></entry>
     </row>
     
     <row>
      <entry><code>long Z_RESVAL(zval zv)</code></entry>
      <entry>value.lval</entry>
      <entry>returns the resource list identifier for <code>value</code></entry>
     </row>
     
     <row>
      <entry><code>char* Z_STRVAL(zval zv)</code></entry>
      <entry>value.str.val</entry>
      <entry>return the string <code>value</code></entry>
     </row>
     
     <row>
      <entry><code>int Z_STRLEN(zval zv)</code></entry>
      <entry>value.str.len</entry>
      <entry>return the length of the string <code>value</code></entry>
     </row>
     
     <row>
      <entry><code>HashTable* Z_ARRVAL(zval zv)</code></entry>
      <entry>value.ht</entry>
      <entry>return the HashTable (array) <code>value</code></entry>
     </row>
     
     <row>
      <entry><code>zend_object_value Z_OBJVAL(zval zv)</code></entry>
      <entry>value.obj</entry>
      <entry>returns object <code>value</code></entry>
     </row>
     
     <row>
      <entry><code>uint Z_OBJ_HANDLE(zval zv)</code></entry>
      <entry>value.obj.handle</entry>
      <entry>returns the object handle for object <code>value</code></entry>
     </row>
     
     <row>
      <entry><code>zend_object_handlers* Z_OBJ_HT_P(zval zv)</code></entry>
      <entry>value.obj.handlers</entry>
      <entry>returns the handler table for object <code>value</code></entry>
     </row>
     
     <row>
      <entry><code>zend_class_entry* Z_OBJCE(zval zv)</code></entry>
      <entry>value.obj</entry>
      <entry>returns the class entry for object <code>value</code></entry>
     </row>
     
     <row>
      <entry><code>HashTable* Z_OBJPROP(zval zv)</code></entry>
      <entry>value.obj</entry>
      <entry>returns the properties of object <code>value</code></entry>
     </row>
     
     <row>
      <entry><code>HashTable* Z_OBJPROP(zval zv)</code></entry>
      <entry>value.obj</entry>
      <entry>returns the properties of object <code>value</code></entry>
     </row>
     
     <row>
      <entry><code>HashTable* Z_OBJDEBUG(zval zv)</code></entry>
      <entry>value.obj</entry>
      <entry>if an object has the get_debug_info handler set, it is called, else Z_OBJPROP is called</entry>
     </row>
     
    </tbody>
   </tgroup>
  </table>
  
  <!-- this is not good enough information -->
  <para>Please check the <xref linkend="features.gc.refcounting-basics"/> chapter for details how reference counting and references work in detail.</para>
  
  <table xml:id="internals2.variables.refcounts.api">
   <title>Reference Count Manipulation</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Prototype</entry>
      <entry>Description</entry>
     </row>
    </thead>
    
    <tbody>
     <row>
      <entry><code>zend_uint Z_REFCOUNT(zval zv)</code></entry>
      <entry>returns the reference count of the <code>value</code></entry>
     </row>
     
     <row>
      <entry><code>zend_uint Z_SET_REFCOUNT(zval zv)</code></entry>
      <entry>sets the reference count of the <code>value</code>, returning it</entry>
     </row>
     
     <row>
      <entry><code>zend_uint Z_ADDREF(zval zv)</code></entry>
      <entry>pre-increments the reference count of <code>value</code>, returning it</entry>
     </row>
     
     <row>
      <entry><code>zend_uint Z_DELREF(zval zv)</code></entry>
      <entry>pre-decrements the reference count of <code>value</code>, returning it</entry>
     </row>
     
     <row>
      <entry><code>zend_bool Z_ISREF(zval zv)</code></entry>
      <entry>tells if the zval is a reference</entry>
     </row>
     
     <row>
      <entry><code>void Z_UNSET_ISREF(zval zv)</code></entry>
      <entry>set is_ref__gc to 0</entry>
     </row>
     
     <row>
      <entry><code>void Z_SET_ISREF(zval zv)</code></entry>
      <entry>set is_ref__gc to 1</entry>
     </row>
     
     <row>
      <entry><code>void Z_SET_ISREF_TO(zval zv, zend_uchar to)</code></entry>
      <entry>set is_ref__gc to <code>to</code></entry>
     </row>
     
    </tbody>
   </tgroup>
  </table>
  
  <note>
   <para>The Z_* macros above all take a zval, they are all defined again suffixed with _P to take a pointer to a zval, for example <code>zend_uchar Z_TYPE_P(zval* pzv)</code>, and again suffixed with _PP to take a pointer to a pointer to a zval, for example <code>zend_uchar Z_TYPE_PP(zval** ppzv)</code></para>
  </note>
  
  <table xml:id="internals2.variables.general.api">
   <title>Creation, Destruction, Separation and Copying</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Prototype</entry>
      <entry>Description</entry>
     </row>
    </thead>
    
    <tbody>
     <row>
      <entry><code>ALLOC_ZVAL(zval* pzval)</code></entry>
      <entry>emallocs <code>pzval</code></entry>
     </row>
     
     <row>
      <entry><code>ALLOC_INIT_ZVAL(zval* pzval)</code></entry>
      <entry>emallocs <code>pzval</code>, and points <code>pzval</code> at a null typed zval for sanity</entry>
     </row>
     
     <row>
      <entry><code>MAKE_STD_ZVAL(zval* pzval)</code></entry>
      <entry>emallocs <code>pzval</code>, setting the refcount to <code>1</code></entry>
     </row>
     
     <row>
      <entry><code>ZVAL_COPY_VALUE(zval* dst, zval* src)</code></entry>
      <entry>sets the value and type of <code>dst</code> from the value and type of <code>src</code></entry>
     </row>
     
     <row>
      <entry><code>INIT_PZVAL_COPY(zval* dst, zval*dst) </code></entry>
      <entry>performs ZVAL_COPY_VALUE, setting refcount of <code>dst</code> to 1, and setting is_ref__gc to <code>0</code></entry>
     </row>
     
     <row>
      <entry><code>SEPARATE_ZVAL(zval** ppzval)</code></entry>
      <entry>if the refcount of <code>ppzval</code> is >1, redirects <code>*ppzval</code> to a newly emalloc'd, copied, and constructed zval of the same type and value</entry>
     </row>
     
     <row>
      <entry><code>SEPARATE_ZVAL_IF_NOT_REF(zval** ppzval)</code></entry>
      <entry>if <code>*ppzval</code> is not a reference, will perform SEPARATE_ZVAL on <code>ppzval</code></entry>
     </row>
     
     <row>
      <entry><code>SEPARATE_ZVAL_TO_MAKE_IS_REF(zval** ppzval)</code></entry>
      <entry>if <code>*ppzval</code> is not a reference, performs SEPARATE_ZVAL then Z_SET_ISREF_PP on <code>ppzval</code></entry>
     </row>
     
     <row>
      <entry><code>COPY_PZVAL_TO_ZVAL(zval dst, zval** src)</code></entry>
      <entry>results in <code>dst</code> being a copy of <code>src</code> without affecting the refcount of <code>src</code></entry>
     </row>
     
     <row>
      <entry><code>MAKE_COPY_ZVAL(zval** src, zval* dst)</code></entry>
      <entry>performs INIT_PZVAL_COPY, then zval_copy_ctor on the new zval</entry>
     </row>
     
     <row>
      <entry><code>void zval_copy_ctor(zval** pzval)</code></entry>
      <entry>performs maintenance of reference counts, used widely throughout the engine</entry>
     </row>
     
     <row>
      <entry><code>void zval_ptr_dtor(zval* pzval)</code></entry>
      <entry>decrements the refcount for the variable, if no refcounts remain the variable is destroyed</entry>
     </row>
     
     <row>
      <entry><code>FREE_ZVAL(zval* pzval)</code></entry>
      <entry>efrees <code>pzval</code></entry>
     </row>
     
    </tbody>
   </tgroup>
  </table>
  
  <note>
   <para>Objects and Resources have a reference count as part of their respective structures, when zval_ptr_dtor is called on either, their appropriate del_ref method is executed. See Working with Objects and Working with Resources for more information.</para>
  </note>
  
  <para>If the <code>Hacker</code> only has room to remember two more functions, they should be <code>zval_copy_ctor</code> and <code>zval_ptr_dtor</code>, these are at the basis of the engines reference counting mechanisms and it is important to note that <code>zval_copy_ctor</code> does not actually result in any copying occuring under normal circumstances, it simply increases the reference count. By the same token, <code>zval_ptr_dtor</code> only really destroys a variable when there are no references remaining to it and the refcount is at 0.</para>
  
  <para>PHP is weakly typed, as such the engine provides API functions for converting variables from one type to another.</para>
  
  <table xml:id="internals2.variables.conversion.api">
   <title>Type Conversion</title>
   <tgroup cols="1">
    <thead>
     <row>
      <entry>Prototype</entry>
     </row>
    </thead>
    <tbody>
     
     <row>
      <entry><code>void convert_to_long(zval* pzval)</code></entry>
     </row>
     
     <row>
      <entry><code>void convert_to_double(zval* pzval)</code></entry>
     </row>
     
     <row>
      <entry><code>void convert_to_long_base(zval* pzval, int base)</code></entry>
     </row>
     
     <row>
      <entry><code>void convert_to_null(zval* pzval)</code></entry>
     </row>
     
     <row>
      <entry><code>void convert_to_boolean(zval* pzval)</code></entry>
     </row>
     
     <row>
      <entry><code>void convert_to_array(zval* pzval)</code></entry>
     </row>
     
     <row>
      <entry><code>void convert_to_object(zval* pzval)</code></entry>
     </row>
     
     <row>
      <entry><code>void convert_object_to_type(zval* pzval, convert_func_t converter)</code></entry>
     </row>
     
    </tbody>
   </tgroup>
  </table>
  
  <note>
   <para><code>convert_func_t</code> functions should have the prototype <code>(void) (zval* pzval)</code></para>
  </note>
  
  <para>By now you should have a good understanding of: the types that are native to the engine, how to detect types and read zval values, how to manipulate refcounts, and other zval flags</para>
  
 </section>
 
 <section xml:id="internals2.variables.arrays">
  <title>Working with Arrays</title>
  <para>
   Arrays are stored in HashTable strucures, and have the zval type IS_ARRAY. The API functions for creating, destroying and manipulating these structures as variables are documented here and can be found in <code>Zend/zend_API.h</code>
  </para>
  
  <table xml:id="internals2.variables.arrays.api">
   <title>HashTable as Variable API</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Prototype</entry>
      <entry>Description</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry><code>void array_init(zval* pzval)</code></entry>
      <entry>initializes the variable as a <code>HashTable</code>, setting type and appropriate destructor function for the <code>HashTable</code></entry>
     </row>
     
     <row>
      <entry><code>void array_init_size(zval* pzval)</code></entry>
      <entry>initializes the variable as array_init with a minimum of <code>size</code> buckets</entry>
     </row>
     
    </tbody>
   </tgroup>
  </table>
  
  <note>
   <para>Do not squint too hard looking for array_destroy: to destroy a variable array you should call <code>zval_ptr_dtor</code> on the variable, if there are no other references to the variable it will result in the array being destroyed.</para>
  </note>
  
  <table xml:id="internals2.variables.iarrays.api">
   <title>Indexed Arrays API</title>
   <tgroup cols="1">
    <thead>
     <row>
      <entry>Prototype</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry><code>int add_index_long(zval* pzval, ulong index, long value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_index_null(zval* pzval, ulong index)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_index_bool(zval* pzval, ulong index, zend_bool value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_index_bool(zval* pzval, ulong index, zend_bool value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_index_resource(zval* pzval, ulong index, uint value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_index_double(zval* pzval, ulong index, double value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_index_string(zval* pzval, ulong index, char* string, zend_bool duplicate)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_index_stringl(zval* pzval, ulong index, char* string, uint length, zend_bool duplicate)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_index_zval(zval* pzval, ulong index, zval* value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_next_index_long(zval* pzval, long value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_next_index_null(zval* pzval)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_next_index_bool(zval* pzval, zend_bool value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_next_index_resource(zval* pzval, uint value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_next_index_double(zval* pzval, double value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_next_index_string(zval* pzval, const char* string, zend_bool dulpicate)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_next_index_stringl(zval* pzval, const char* string, uint length, zend_bool duplicate)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_next_index_zval(zval* pzval, zval* value)</code></entry>
     </row>
     
    </tbody>
   </tgroup>
  </table>
  
  <table xml:id="internals2.variables.aarrays.api">
   <title>Associative Arrays API</title>
   <tgroup cols="1">
    <thead>
     <row>
      <entry>Prototype</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry><code>int add_assoc_long(zval* pzval, const char* key, long value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_long_ex(zval* pzval, const char* key, uint klen, long value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_null(zval* pzval, const char* key)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_null_ex(zval* pzval, const char* key, uint klen)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_bool(zval* pzval, const char* key, zend_bool value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_bool(zval* pzval, const char* key, zend_bool value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_bool_ex(zval* pzval, const char* key, uint klen, zend_bool value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_resource(zval* pzval, const char* key, uint value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_resource_ex(zval* pzval, const char* key, uint klen, uint value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_double(zval* pzval, const char* key, double value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_double_ex(zval* pzval, const char* key, uint klen, double value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_string(zval* pzval, const char* key, const char* value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_string_ex(zval* pzval, const char* key, uint klen, const char* value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_stringl(zval* pzval, const char* key, const char* value, uint vlen, zend_bool duplicate)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_stringl_ex(zval* pzval, const char* key, uint klen, const char* value, uint vlen, zend_bool duplicate)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_zval(zval* pzval, const char* key, zval* value)</code></entry>
     </row>
     
     <row>
      <entry><code>int add_assoc_zval_ex(zval* pzval, const char* key, uint klen, zval* value)</code></entry>
     </row>
     
    </tbody>
   </tgroup>
  </table>
  
  <note>
   <para>add_*_string functions that accept a parameter named duplicate, will duplicate the string with <code>estrndup</code> when <code>duplicate</code> is true</para>
  </note>
  
  <note>
   <para>add_*_zval functions do not adjust the refcount of the <code>value</code> parameter</para>
  </note>
  
  <para>
   To perform more advanced operations on array variables we must use the HashTable API directly.
  </para>
 </section>
 
 <section xml:id="internals2.variables.tables">
  <title>Working with HashTable</title>
  
  <para>The <code>HashTable</code> structure serves many purposes in PHP and can be found everywhere, a good understanding of it's functionality is a preqrequisite of being a good <code>Hacker</code>.</para>
  
  <para>The <code>HashTable</code> implemented by the engine is a standard <code>HashTable</code>, that is to say, a key =&gt; value based store, where the keys are always strings, whose hashes are calculated with a built in hashing algorithm <code>zend_inline_hash_func(const char* key, uint length)</code>, which results in good distribution, and reasonable usage.</para>
  
  <para>The internal structure and exact operation of <code>HashTable</code> is out of the scope of this document, this document serves to inform you of the API's available and how best to use them. For a more detailed picture of the HashTable see <code>Zend/zend_hash.h</code>.</para>
  
  <para>Unless otherwise stated, these functions all return <code>FAILURE</code> if the requested opeation fails for any reason, otherwise <code>SUCCESS</code> is returned.</para>
  
  <note>
   <para>It is important to remember that ordinarily <code>HashTable</code> API functions expect key lengths to be the length of the null terminated string, including the null termination, in other words they expect <code>strlen(key) + 1</code></para>
  </note>
  
  <para>Below are some typedefs you should know when interacting with <code>HashTable</code>. They are mostly self explanitory and will allow the <code>Hacker</code> to fully understand the prototypes below properly.</para>
  
  <screen>
<![CDATA[
typedef ulong (*hash_func_t)(const char *arKey, uint nKeyLength); /* mostly redundant */
typedef int  (*compare_func_t)(const void *, const void * TSRMLS_DC); /* comparison function */
typedef void (*sort_func_t)(void *, size_t, register size_t, compare_func_t TSRMLS_DC); /* sorting function */
typedef void (*dtor_func_t)(void *pDest); /* destructor function */
typedef void (*copy_ctor_func_t)(void *pElement); /* copy constructor */
typedef void (*copy_ctor_param_func_t)(void *pElement, void *pParam); /* copy with argument constructor */
typedef int (*apply_func_t)(void *pDest TSRMLS_DC); /* apply function */
typedef int (*apply_func_arg_t)(void *pDest, void *argument TSRMLS_DC); /* apply with argument function */
typedef int (*apply_func_args_t)(void *pDest TSRMLS_DC, int num_args, va_list args, zend_hash_key *hash_key); /* apply with multiple arguments function */
]]>
  </screen>
  
  <table xml:id="internals2.variables.advrrays.api">
   <title>HashTable API</title>
   <tgroup cols="1">
    <tbody>
     <row>
      <entry><code>int zend_hash_init(HashTable* ht, uint size, hash_func_t hash, dtor_func_t destructor, zend_bool persistent)</code></entry>
     </row>
     
     <row>
      <entry>Initializes the hash table to hold at least <code>size</code> elements, <code>hash</code> exists for historical reasons and is always ignored, <code>zend_inline_hash_func</code> is always used as the hashing function. <code>destructor</code> may be <code>NULL</code>.</entry>
     </row>
     
     <row>
      <entry><code>int zend_hash_add(HashTable* ht, const char* key, uint klen, void* data, uint dlen, void** dest)</code></entry>
     </row>
     
     <row>
      <entry>adds <code>data</code> to the table using the specified <code>key</code>, where the key  is <code>length</code> bytes long (and will be copied from <code>key</code> to the table). If the key is set FAILURE will be returned.</entry>
     </row>
     
     <row>
      <entry><code>int zend_hash_update(HashTable* ht, const char* key, uint klen, void* data, uint dlen, void** dest)</code></entry>
     </row>
     
     <row>
      <entry>adds <code>data</code> to the table using the specified <code>key</code>, where the key  is <code>length</code> bytes long (and will be copied from <code>key</code> to the table). If the key has been set previously the old data has <code>dtor_func_t</code> called on it and the existing data is replaced with <code>data</code></entry>
     </row>
     
     <row>
      <entry><code>int zend_hash_find(HashTable* ht, const char* key, uint klen, void** data)</code></entry>
     </row>
     
     <row>
      <entry>searches the table for <code>key</code>, setting <code>*data</code> and returning SUCCESS if it is found.</entry>
     </row>
     
     <row>
      <entry><code>zend_bool zend_hash_exists(HashTable* ht, const char* key, uint klen)</code></entry>
     </row>
     
     <row>
      <entry>returns positively if <code>key</code> is found in <code>ht</code></entry>
     </row>
     
     <row>
      <entry><code>int zend_hash_del(HashTable* ht, const char* key, uint klen)</code></entry> 
     </row>
     
     <row>
      <entry>removes the entry identified by <code>key</code> from the table if found</entry>
     </row>
     
     <row>
      <entry><code>int zend_hash_index_update(HashTable* ht, ulong index, void* data, uint dsize, void** dest)</code></entry>
     </row>
     
     <row>
      <entry>updates the entry at <code>index</code> in <code>ht</code>, with the data at <code>data</code></entry>
     </row>
     
     <row>
      <entry><code>int zend_hash_index_del(HashTable* ht, ulong index)</code></entry>
     </row>
     
     <row>
      <entry>deletes the entry at <code>index</code> from <code>ht</code></entry>
     </row>
     
     <row>
      <entry><code>int zend_hash_index_find(HashTable* ht, ulong index, void** data)</code></entry>
     </row>
     
     <row>
      <entry>redirects <code>*data</code> to the data identified by <code>index</code> in <code>ht</code></entry>
     </row>
     
     <row>
      <entry><code>int zend_hash_index_exists(HashTable* ht, ulong index)</code></entry>
     </row>
     
     <row>
      <entry>returns positively if <code>index</code> is found in <code>ht</code></entry>
     </row>
     
     <row>
      <entry><code>ulong zend_hash_next_free_element(HashTable* ht)</code></entry>
     </row>
     
     <row>
      <entry>returns the index of the next free element in <code>ht</code></entry>
     </row>
     
    </tbody>
   </tgroup>
  </table>
  
  <caution>
   <para>zend_hash_* functions that accept <code>void* data</code> should normally cast it to <code>(void**)</code> (ie, <code>(void**) &amp;data</code>)</para>
  </caution>
  
  <para>Traversing the HashTable is often necessary, to do this you provide a pointer to a <code>HashTable</code>, with an optional <code>HashPosition</code> - a structure internal to the HashTable API that allows traversal not to affect the internal position of HashTable. The following traversal functions are provided, and an example usage found below.</para>
  
  <table xml:id="internals2.variables.trarrays.api">
   <title>HashTable Traversal API</title>
   <tgroup cols="1">
    <tbody>
     <row>
      <entry><code>int zend_hash_internal_pointer_reset(HashTable* ht)</code></entry>
     </row>
     <row>
      <entry>resets the internal pointer of <code>ht</code> to the start</entry>
     </row>
     <row>
      <entry><code>int zend_hash_internal_pointer_reset_ex(HashTable* ht, HashPosition position)</code></entry>
     </row>
     <row>
      <entry>sets <code>position</code> the the start of <code>ht</code></entry>
     </row>
     <row>
      <entry><code>int zend_hash_get_current_data(HashTable* ht, void* data)</code></entry>
     </row>
     <row>
      <entry>gets the data at the current position in <code>ht</code>, <code>data</code> should be cast to <code>void**</code>, ie: <code>(void**) &amp;data</code></entry>
     </row>
     <row>
      <entry><code>int zend_hash_get_current_data_ex(HashTable* ht, void* data, HashPosition position)</code></entry>
     </row>
     <row>
      <entry>sets <code>data</code> to the data at <code>position</code> in <code>ht</code></entry>
     </row>
     <row>
      <entry><code>int zend_hash_get_current_key(HashTable* ht, void* data, char**key, uint klen, ulong index, zend_bool duplicate)</code></entry>
     </row>
     <row>
      <entry>sets <code>key</code>, <code>klen</code>, and <code>index</code> from the key information at the current position. The possible return values HASH_KEY_IS_STRING and HASH_KEY_IS_LONG are indicative of the kind of key found at the current posision.</entry>
     </row>
     <row>
      <entry><code>int zend_hash_get_current_key_ex(HashTable* ht, void* data, char**key, uint klen, ulong index, zend_bool duplicate, HashPosition position)</code></entry>
     </row>
     <row>
      <entry>sets <code>key</code>, <code>klen</code>, and <code>index</code> from the key information at <code>position</code>. The possible return values <code>HASH_KEY_IS_STRING</code> and <code>HASH_KEY_IS_LONG</code> are indicative of the kind of key found at <code>position</code>.</entry>
     </row>
     <row>
      <entry><code>int zend_hash_move_forward(HashTable* ht)</code></entry>
     </row>
     <row>
      <entry>moves the internal pointer of <code>ht</code> to the next entry in <code>ht</code></entry>
     </row>
     <row>
      <entry><code>int zend_hash_move_forward_ex(HashTable* ht, HashPosition position)</code></entry>
     </row>
     <row>
      <entry>moves <code>position</code> to the next entry in <code>ht</code> </entry>
     </row>
    </tbody>
   </tgroup>
  </table>
  
  <para>The functions above allow traversal over a <code>HashTable</code> to be much like a normal loop, which will look something like:</para>
  
  <screen>
<![CDATA[
HashPosition position;
zval **data = NULL;

for (zend_hash_internal_pointer_reset_ex(ht, &position);
     zend_hash_get_current_data_ex(ht, (void**) &data, &position) == SUCCESS;
     zend_hash_move_forward_ex(ht, &position)) {
     
     /* by now we have data set and can use Z_ macros for accessing type and variable data */

     char *key = NULL;
     uint  klen;
     ulong index;

     if (zend_hash_get_current_key_ex(ht, &key, &klen, &index, 0, &position) == HASH_KEY_IS_STRING) {
         /* the key is a string, key and klen will be set */
     } else {
         /* we assume the key to be long, index will be set */
     }
}
]]>
  </screen>
  
  <note>
   <para>If a <code>HashTable</code> has been passed into the engine, it is a good idea to use the zend_hash_*_ex API to avoid unexpected behaviour in userland.</para>
  </note>
  
  <note>
   <para>If a <code>duplicate</code> of the key is requested and <code>HAS_KEY_IS_STRING</code> is returned the caller must <code>efree</code> the duplicated key</para>
  </note>
  
  <para>In addition to traversal, the engine provides API functions for merging, copying, and comparing HashTables. These are all concepts that the <code>Hacker</code> should be familiar with. A concept possibly not in the repertoire of the <code>Hacker</code> is <code>applying</code>, which is lamens terms is functionality of the <code>HashTable</code> API allowing the <code>Hacker</code> to pass a callback function to be executed on every entry in a <code>HashTable</code>.</para>
  
  <table xml:id="internals2.variables.coparrays.api">
   <title>Copying, Merging and Sorting</title>
   <tgroup cols="1">
    <tbody>
     <row>
      <entry><code>void zend_hash_copy(HashTable *target, HashTable *source, copy_ctor_func_t pCopyConstructor, void *tmp, uint size)</code></entry>
     </row>
     
     <row>
      <entry>Copies the contents of <code>source</code> to <code>target</code>. <code>tmp</code> should be an unallocated temporary pointer of the appropriate type, used during copying. <code>size</code> is the size of each element.</entry>
     </row>
     
     <row>
      <entry><code>void zend_hash_merge(HashTable *target, HashTable *source, copy_ctor_func_t pCopyConstructor, void *tmp, uint size, zend_bool overwrite)</code></entry>
     </row>
     
     <row>
      <entry>Merges the contents of <code>source</code> into <code>destination</code>, replacing existing entries only where <code>overwrite</code> is true.</entry>
     </row>
     
     <row>
      <entry><code>void int zend_hash_sort(HashTable *ht, sort_func_t sort_func, compare_func_t compare_func, int renumber TSRMLS_DC)</code></entry>
     </row>
     
     <row>
      <entry><code>renumber</code> controls if indexes should be preserved, see the typedefs at the start of this section for more information</entry>
     </row>
     
    </tbody>
   </tgroup>
  </table>
  
  <note>
   <para>When a function accepts a <code>copy_ctor_func_t pCopyConstructor</code>, the function passed with be executed upon creation of every new entry in the <code>HashTable</code>. The most common copy constructor used within the engine is a wrapper around <code>zval_copy_ctor</code>, the macro <code>ZVAL_COPY_CTOR</code>.
   </para>
  </note>
  
 </section>
 
 <section xml:id="internals2.variables.objects">
  <title>Working with Objects</title>
  <para>
   <!-- ... -->
  </para>
 </section>
 
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->