API Macros

A set of macros was introduced into Zend's API that simplify access to zval containers (see 表格 45-19).

表格 45-19. API Macros for Accessing zval Containers

Macro	Refers to
`Z_LVAL(zval)`	`(zval).value.lval`
`Z_DVAL(zval)`	`(zval).value.dval`
`Z_STRVAL(zval)`	`(zval).value.str.val`
`Z_STRLEN(zval)`	`(zval).value.str.len`
`Z_ARRVAL(zval)`	`(zval).value.ht`
`Z_LVAL_P(zval)`	`(*zval).value.lval`
`Z_DVAL_P(zval)`	`(*zval).value.dval`
`Z_STRVAL_P(zval_p)`	`(*zval).value.str.val`
`Z_STRLEN_P(zval_p)`	`(*zval).value.str.len`
`Z_ARRVAL_P(zval_p)`	`(*zval).value.ht`
`Z_LVAL_PP(zval_pp)`	`(**zval).value.lval`
`Z_DVAL_PP(zval_pp)`	`(**zval).value.dval`
`Z_STRVAL_PP(zval_pp)`	`(**zval).value.str.val`
`Z_STRLEN_PP(zval_pp)`	`(**zval).value.str.len`
`Z_ARRVAL_PP(zval_pp)`	`(**zval).value.ht`

add a note User Contributed Notes

k at ailis dot de
06-Apr-2002 07:56


If you are using one of the above macros you definitely want to use one of those convert-functions if you are not sure what data type is stored in the zval:



  convert_to_string(zval_p)

  convert_to_long(zval_p)

  convert_to_double(zval_p)

  convert_to_boolean(zval_p)

  convert_to_array(zval_p)

  convert_to_object(zval_p)



Otherwise you may get undefined results, because Z_STRVAL_P(zval_p) returns nonsense if the zval contains not a string. If you use convert_to_string() before, the value is converted to a string and you can safely access it via the Z_STRVAL* macros.



There are more useful convert-functions:



Resets the zval to NULL:

  convert_to_null(zval_p)



Converts to a long by using a special base:

  convert_to_long_base(zval_p, base)



There are some more functions which may be useful, but I don't know exactly what they are doing. Just take a look at Zend/zend_operaters.h.

k at ailis dot de
06-Apr-2002 07:41


To complete the macro list:



Access an object:

  Z_OBJ(zval)

  Z_OBJ_P(zval)

  Z_OBJ_PP(zval)



Access object property hash table:

  Z_OBJPROP(zval)

  Z_OBJPROP_P(zval)

  Z_OBJPROP_PP(zval)



Access object class entry:

  Z_OBJCE(zval)

  Z_OBJCE_P(zval)

  Z_OBJCE_PP(zval)



Access a ressource (which is fairly the same as Z_LVAL*):

  Z_RESVAL(zval)

  Z_RESVAL_P(zval)

  Z_RESVAL_PP(zval)

k at ailis dot de
06-Apr-2002 07:33


These macros can be used to access the boolean value of a zval. Yes, you can use Z_LVAL* for booleans, too, but these macros also do a type cast to zend_bool:



Z_BVAL(zval)

Z_BVAL_P(zval)

Z_BVAL_PP(zval)

nutbar at innocent dot com
04-Jan-2002 07:51


There are also:



Z_TYPE(zval)

Z_TYPE_P(*zval)

Z_TYPE_PP(**zval)

add a note