Retro video games delivered to your door every month!
Click above to get retro games delivered to your door ever month!
Returning Values
OuSob Home Page
PrevChapter 46. Zend API: Hacking the Core of PHPNext

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 Table 46-14 and Table 46-15.

Note: The macros in Table 46-14 automatically return from your function, those in Table 46-15 only set the return value; they don't return from your function.

Table 46-14. Predefined Macros for Returning Values from a Function

MacroDescription
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_FALSEReturns Boolean false.
RETURN_TRUEReturns Boolean true.

Table 46-15. Predefined Macros for Setting the Return Value of a Function

MacroDescription
RETVAL_RESOURCE(resource)Sets the return value to the specified resource.
RETVAL_BOOL(bool)Sets the return value to the specified Boolean value.
RETVAL_NULLSets 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.

PrevHomeNext
Duplicating Variable Contents: The Copy ConstructorUpPrinting Information