Kapitola 37. 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 37-1 and 37-2.

Pozn�mka: The macros in 37-1 automatically return from your function, those in 37-2 only set the return value; they don't return from your function.

Tabulka 37-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.

Tabulka 37-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.

add a note User Contributed Notes
Returning Values

Julien CROUZET jucrouzet_at_cpan.org
07-Apr-2004 09:51


Remember that even if RETURN_* macros sets the return_value to return variable to user, they also RETURN FROM YOU CODE by a "return ;", any code after these macro will be ignored.



If you want to place code after a return of variable (which is not a good idea for code readability), you'll have to use RETVAL_* macro instead.

Julien CROUZET jucrouzet_at_cpan.org
07-Apr-2004 09:44


Just an example of the way of the way of returning array :



/*

** Creates a array of on element (a long of value 42)

*/

ZEND_FUNCTION("make_42_array")

{

  zval *my_long;



  // Declaring and allocating return_value to be an array

  array_init(return_value);



  //Creates and assign the long element at (long)42

  MAKE_STD_ZVAL(my_long);

  ZVAL_LONG(new_element, 42);



  //Make this our $array[0] I do not use add_index_long to

  //to show a "by-hand" assignation

  zend_hash_index_update(HASH_OF(return_value), 0, (void *)&my_long, sizeof(zval *), NULL);



  //Returns nothing to satisfy the void prototype

  return ;



}

add a note


	downloads \| documentation \| faq \| getting help \| mailing lists \| \| php.net sites \| links \| my php.net

search for in the