8.3 使用HashTable与{数组}

当你在扩展中使用HashTable时候,95%是要存储用户端的变量,就像PHP语言中数组那样。为此,内核中已经准备好了相应的工具,来让我们更加的方便的操作HashTable存储zval*,也就是PHP语言中的数组,即IS_ARRAY常量代表的zval,以下用{数组}来代替PHP语言中的数组这个词。

创建{数组}

创建HashTable有些繁琐,虽然有辅助的宏但还是不能一步完成,而创建{数组}便简单多了,直接使用array_init(zval arrval)函数即可,注意它的参数是zval类型的! 这样,我们像用户端返回数组便简单多了:

  1. ZEND_FUNCTION(sample_array)
  2. {
  3. array_init(return_value);
  4. }
  5. //return_value是zval*类型的,所以我们直接对它调用array_init()函数即可,即把它初始化成了一个空数组。

增!

将{数组}初始化后,接下来就要向其添加元素了。因为PHP语言中有多种类型的变量,所以也对应的有多种类型的addassoc()、addindex、addnext_index*()函数。如:

  1. array_init(arrval);
  2. add_assoc_long(zval *arrval, char *key, long lval);
  3. add_index_long(zval *arrval, ulong idx, long lval);
  4. add_next_index_long(zval *arrval, long lval);

这三个函数的第一个参数都要被操作的{数组}指针,然后是索引值,最后是变量,唯一不同的是add_next_index_long()函数的索引值是其自己计算出来的。根据上一节的内容我们可以知道,这三个函数分别在内部使用了zend_hash_update()、zend_hash_index_update()与zend_hash_next_index_insert函数。

  1. //add_assoc_*系列函数:
  2. add_assoc_null(zval *aval, char *key);
  3. add_assoc_bool(zval *aval, char *key, zend_bool bval);
  4. add_assoc_long(zval *aval, char *key, long lval);
  5. add_assoc_double(zval *aval, char *key, double dval);
  6. add_assoc_string(zval *aval, char *key, char *strval, int dup);
  7. add_assoc_stringl(zval *aval, char *key,char *strval, uint strlen, int dup);
  8. add_assoc_zval(zval *aval, char *key, zval *value);
  9. //备注:其实这些函数都是宏,都是对add_assoc_*_ex函数的封装。
  10. //add_index_*系列函数:
  11. ZEND_API int add_index_long (zval *arg, ulong idx, long n);
  12. ZEND_API int add_index_null (zval *arg, ulong idx );
  13. ZEND_API int add_index_bool (zval *arg, ulong idx, int b );
  14. ZEND_API int add_index_resource (zval *arg, ulong idx, int r );
  15. ZEND_API int add_index_double (zval *arg, ulong idx, double d);
  16. ZEND_API int add_index_string (zval *arg, ulong idx, const char *str, int duplicate);
  17. ZEND_API int add_index_stringl (zval *arg, ulong idx, const char *str, uint length, int duplicate);
  18. ZEND_API int add_index_zval (zval *arg, ulong index, zval *value);
  19. //add_next_index_long函数:
  20. ZEND_API int add_next_index_long (zval *arg, long n );
  21. ZEND_API int add_next_index_null (zval *arg );
  22. ZEND_API int add_next_index_bool (zval *arg, int b );
  23. ZEND_API int add_next_index_resource (zval *arg, int r );
  24. ZEND_API int add_next_index_double (zval *arg, double d);
  25. ZEND_API int add_next_index_string (zval *arg, const char *str, int duplicate);
  26. ZEND_API int add_next_index_stringl (zval *arg, const char *str, uint length, int duplicate);
  27. ZEND_API int add_next_index_zval (zval *arg, zval *value);

每组函数最后的一个,即zend…_zval()函数,允许我们向这个{数组}中添加资源、对象、{数组}等复合类型的PHP变量。下面让我们通过一个例子来演示下它们的用法:

  1. ZEND_FUNCTION(sample_array)
  2. {
  3. zval *subarray;
  4. array_init(return_value);
  5. /* Add some scalars */
  6. add_assoc_long(return_value, "life", 42);
  7. add_index_bool(return_value, 123, 1);
  8. add_next_index_double(return_value, 3.1415926535);
  9. /* Toss in a static string, dup'd by PHP */
  10. add_next_index_string(return_value, "Foo", 1);
  11. /* Now a manually dup'd string */
  12. add_next_index_string(return_value, estrdup("Bar"), 0);
  13. /* Create a subarray */
  14. MAKE_STD_ZVAL(subarray);
  15. array_init(subarray);
  16. /* Populate it with some numbers */
  17. add_next_index_long(subarray, 1);
  18. add_next_index_long(subarray, 20);
  19. add_next_index_long(subarray, 300);
  20. /* Place the subarray in the parent */
  21. add_index_zval(return_value, 444, subarray);
  22. }

这时如果我们用户端var_dump这个函数的返回值便会得到:

  1. <?php
  2. var_dump(sample_array());

输出:

  1. array(6)
  2. {
  3. ["life"]=> int(42)
  4. [123]=> bool(true)
  5. [124]=> float(3.1415926535)
  6. [125]=> string(3) "Foo"
  7. [126]=> string(3) "Bar"
  8. [444]=> array(3)
  9. {
  10. [0]=> int(1)
  11. [1]=> int(20)
  12. [2]=> int(300)
  13. }
  14. }