Arrays

Arrays are stored using Zend's internal hash tables, which can be accessed using the zend_hash_*() API. For every array that you want to create, you need a new hash table handle, which will be stored in the ht member of the zval.value container.

There's a whole API solely for the creation of arrays, which is extremely handy. To start a new array, you call array_init().

zval *new_array;

MAKE_STD_ZVAL(new_array);

array_init(new_array);

array_init() always returns SUCCESS.

To add new elements to the array, you can use numerous functions, depending on what you want to do. Tabla 53-1, Tabla 53-2 and Tabla 53-3 describe these functions. All functions return FAILURE on failure and SUCCESS on success.

Tabla 53-1. Zend's API for Associative Arrays

Function	Description
*add_assoc_long(zval array, char key, long n);()*	Adds an element of type `long`.
*add_assoc_unset(zval array, char key);()*	Adds an unset element.
*add_assoc_bool(zval array, char key, int b);()*	Adds a Boolean element.
*add_assoc_resource(zval array, char key, int r);()*	Adds a resource to the array.
*add_assoc_double(zval array, char key, double d);()*	Adds a floating-point value.
*add_assoc_string(zval array, char key, char str, int duplicate);()**	Adds a string to the array. The flag `duplicate` specifies whether the string contents have to be copied to Zend internal memory.
*add_assoc_stringl(zval array, char key, char str, uint length, int duplicate); ()**	Adds a string with the desired length `length` to the array. Otherwise, behaves like add_assoc_string().
*add_assoc_zval(zval array, char key, zval value);()**	Adds a zval to the array. Useful for adding other arrays, objects, streams, etc...

Tabla 53-2. Zend's API for Indexed Arrays, Part 1

Function	Description
*add_index_long(zval array, uint idx, long n);()**	Adds an element of type `long`.
*add_index_unset(zval array, uint idx);()**	Adds an unset element.
*add_index_bool(zval array, uint idx, int b);()**	Adds a Boolean element.
*add_index_resource(zval array, uint idx, int r);()**	Adds a resource to the array.
*add_index_double(zval array, uint idx, double d);()**	Adds a floating-point value.
*add_index_string(zval array, uint idx, char str, int duplicate);()*	Adds a string to the array. The flag `duplicate` specifies whether the string contents have to be copied to Zend internal memory.
*add_index_stringl(zval array, uint idx, char str, uint length, int duplicate);()*	Adds a string with the desired length `length` to the array. This function is faster and binary-safe. Otherwise, behaves like add_index_string()().
*add_index_zval(zval array, uint idx, zval value);()*	Adds a zval to the array. Useful for adding other arrays, objects, streams, etc...

Tabla 53-3. Zend's API for Indexed Arrays, Part 2

Function	Description
*add_next_index_long(zval array, long n);()**	Adds an element of type `long`.
*add_next_index_unset(zval array);()**	Adds an unset element.
*add_next_index_bool(zval array, int b);()**	Adds a Boolean element.
*add_next_index_resource(zval array, int r);()**	Adds a resource to the array.
*add_next_index_double(zval array, double d);()**	Adds a floating-point value.
*add_next_index_string(zval array, char str, int duplicate);()*	Adds a string to the array. The flag `duplicate` specifies whether the string contents have to be copied to Zend internal memory.
*add_next_index_stringl(zval array, char str, uint length, int duplicate);()*	Adds a string with the desired length `length` to the array. This function is faster and binary-safe. Otherwise, behaves like add_index_string()().
*add_next_index_zval(zval array, zval value);()*	Adds a zval to the array. Useful for adding other arrays, objects, streams, etc...

All these functions provide a handy abstraction to Zend's internal hash API. Of course, you can also use the hash functions directly - for example, if you already have a zval container allocated that you want to insert into an array. This is done using zend_hash_update()() for associative arrays (see Ejemplo 53-3) and zend_hash_index_update() for indexed arrays (see Ejemplo 53-4):

Ejemplo 53-3. Adding an element to an associative array.

zval *new_array, *new_element;
char *key = "element_key";
      
MAKE_STD_ZVAL(new_array);
MAKE_STD_ZVAL(new_element);

array_init(new_array);

ZVAL_LONG(new_element, 10);

if(zend_hash_update(new_array->value.ht, key, strlen(key) + 1, (void *)&new_element, sizeof(zval *), NULL) == FAILURE)
{
    // do error handling here
}

Ejemplo 53-4. Adding an element to an indexed array.

zval *new_array, *new_element;
int key = 2;

MAKE_STD_ZVAL(new_array);
MAKE_STD_ZVAL(new_element);

array_init(new_array);

ZVAL_LONG(new_element, 10);

if(zend_hash_index_update(new_array->value.ht, key, (void *)&new_element, sizeof(zval *), NULL) == FAILURE)
{
    // do error handling here
}

To emulate the functionality of add_next_index_*(), you can use this:

zend_hash_next_index_insert(ht, zval **new_element, sizeof(zval *), NULL)

Note: To return arrays from a function, use array_init() and all following actions on the predefined variable return_value (given as argument to your exported function; see the earlier discussion of the call interface). You do not have to use MAKE_STD_ZVAL on this.

Tip: To avoid having to write new_array->value.ht every time, you can use HASH_OF(new_array), which is also recommended for compatibility and style reasons.