|
|
 |
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.
Table 53-1,
Table 53-2 and
Table 53-3
describe these functions. All functions return
FAILURE on failure and
SUCCESS on success.
Table 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... |
Table 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... |
Table 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 Example 53-3) and
zend_hash_index_update() for indexed arrays
(see Example 53-4):
Example 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
} |
|
Example 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.
User Contributed Notes
Arrays
Julien CROUZET jucrouzet_at_cpan.org
05-Apr-2004 05:28
All associate array functions (add_assoc_long for example) are now just aliases of their extended version (add_assoc_long_ex).
The key lenght is calculated with strlen(key) + 1, but remember that this is NOT binary safe (strlen stops on the first null byte).
Users may want to use binary keys, so always prefer extended versions with a secure length !
john dot gallet at wanadoo dot fr
26-Mar-2002 01:58
Concerning all add_*_stringl() functions :
they do not behave like snprintf() for instance, i.e. the length of the string is not a *maximum length* but an *exact* length, and you end up with null '\000' or '\@' caracters in your PHP string if the length parameter is greater than the actual length of the string to be associated with return_value.
Yes, it is clearly written but still a trick if you are used to strncpy() or snprintf().
HTH
k at ailis dot de
17-Mar-2002 08:48
There are also the following functions to add zvals to an array or hash:
ZEND_API int add_index_zval(zval *arg, uint index, zval *value);
ZEND_API int add_next_index_zval(zval *arg, zval *value);
ZEND_API int add_assoc_zval_ex(zval *arg, char *key, uint key_len, zval *value)
add_assoc_zval(__arg, __key, __value)
| |
Booleans