Capítulo 35_ Returning Values

Returning values from your functions to PHP was described briefly in an earlier section; this section gives the details_ Return values are passed via the return_value variable, which is passed to your functions as argument_ The return_value argument consists of a zval container (see the earlier discussion of the call interface) that you can freely modify_ The container itself is already allocated, so you don't have to run MAKE_STD_ZVAL on it_ Instead, you can access its members directly_

To make returning values from functions easier and to prevent hassles with accessing the internal structures of the zval container, a set of predefined macros is available (as usual)_ These macros automatically set the correspondent type and value, as described in Tabla 35_1 and Tabla 35_2_

Nota: The macros in Tabla 35_1 automatically return from your function, those in Tabla 35_2 only set the return value; they don't return from your function_

Tabla 35_1_ Predefined Macros for Returning Values from a Function

Macro	Description
`RETURN_RESOURCE(resource)`	Returns a resource_
`RETURN_BOOL(bool)`	Returns a Boolean_
`RETURN_NULL()`	Returns nothing (a NULL value)_
`RETURN_LONG(long)`	Returns a long_
`RETURN_DOUBLE(double)`	Returns a double_
`RETURN_STRING(string, duplicate)`	Returns a string_ The `duplicate` flag indicates whether the string should be duplicated using estrdup()_
`RETURN_STRINGL(string, length, duplicate)`	Returns a string of the specified length; otherwise, behaves like `RETURN_STRING`_ This macro is faster and binary_safe, however_
`RETURN_EMPTY_STRING()`	Returns an empty string_
`RETURN_FALSE`	Returns Boolean false_
`RETURN_TRUE`	Returns Boolean true_

Tabla 35_2_ Predefined Macros for Setting the Return Value of a Function

Macro	Description
`RETVAL_RESOURCE(resource)`	Sets the return value to the specified resource_
`RETVAL_BOOL(bool)`	Sets the return value to the specified Boolean value_
`RETVAL_NULL`	Sets the return value to NULL_
`RETVAL_LONG(long)`	Sets the return value to the specified long_
`RETVAL_DOUBLE(double)`	Sets the return value to the specified double_
`RETVAL_STRING(string, duplicate)`	Sets the return value to the specified string and duplicates it to Zend internal memory if desired (see also `RETURN_STRING`)_
`RETVAL_STRINGL(string, length, duplicate)`	Sets the return value to the specified string and forces the length to become `length` (see also `RETVAL_STRING`)_ This macro is faster and binary_safe, and should be used whenever the string length is known_
`RETVAL_EMPTY_STRING`	Sets the return value to an empty string_
`RETVAL_FALSE`	Sets the return value to Boolean false_
`RETVAL_TRUE`	Sets the return value to Boolean true_

Complex types such as arrays and objects can be returned by using array_init() and object_init(), as well as the corresponding hash functions on return_value_ Since these types cannot be constructed of trivial information, there are no predefined macros for them_