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);
if(array_init(new_array) != SUCCESS)
{
// do error handling here
} |
To add new elements to the array, you can use numerous functions, depending on what you want to do. Tables 9.8, 9.9, and 9.10 describe these functions. All functions return FAILURE on failure and SUCCESS on success.
Figure 33-3. Table 9.8. Zend's API for Associative Arrays
Note: The functions in Table 9.8 all operate on the array "array" with the key "key". The key string doesn't have to reside in Zend internal memory; it will be duplicated by the API. |
| 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(). |
Figure 33-4. Table 9.9. Zend's API for Indexed Arrays, Part 1
Note: The functions in Table 9.9 all operate on the array "array" with the index "idx". The index is always an integer. |
| 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()(). |
Figure 33-5. Table 9.10. Zend's API for Indexed Arrays, Part 2
Note: The functions in Table 9.10 all operate on the array "array". These functions automatically generate a new index based on the highest index found in the array. |
| 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()(). |
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 Listing 9.12) and zend_hash_index_update() for indexed arrays (see Listing 9.13):
Figure 33-6. Listing 9.12. 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);
if(array_init(new_array) == FAILURE)
{
// do error handling here
}
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
} |
Figure 33-7. Listing 9.13. 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);
if(array_init(new_array) == FAILURE)
{
// do error handling here
}
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.