PHP: Returning Values - Manual

downloads | documentation | faq | getting help | mailing lists | reporting bugs | php.net sites | links | conferences | my php.net

search for in the

Printing Information Duplicating Variable Contents: The Copy Constructor

Last updated: Fri, 26 Jan 2007

view this page in

# 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 Табл. 46-14 and Табл. 46-15.

> Замечание: The macros in Табл. 46-14 automatically return from your function, those in Табл. 46-15 only set the return value; they don't return from your function.

Таблица 46-14. 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.

Таблица 46-15. 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 02: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 02: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
Printing Information Duplicating Variable Contents: The Copy Constructor

Last updated: Fri, 26 Jan 2007
show source | credits | stats | sitemap | contact | advertising | mirror sites
Copyright © 2001-2007 The PHP Group
All rights reserved.
This mirror generously provided by: Yahoo! Inc.
Last updated: Sat Mar 10 10:36:09 2007 PST