Sophie: php-manual-en-4.3.0-2mdk noarch

php-manual-en-4.3.0-2mdk.noarch.rpm

<HTML
><HEAD
><TITLE
>Returning Values</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="PHP Manual"
HREF="index.html"><LINK
REL="UP"
TITLE="Extending PHP 4.0"
HREF="zend.html"><LINK
REL="PREVIOUS"
TITLE="Duplicating Variable Contents: The Copy Constructor"
HREF="zend.copy-constructor.html"><LINK
REL="NEXT"
TITLE="Printing Information"
HREF="zend.printing.html"><META
HTTP-EQUIV="Content-type"
CONTENT="text/html; charset=ISO-8859-1"></HEAD
><BODY
CLASS="chapter"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PHP Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="zend.copy-constructor.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="zend.printing.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="chapter"
><H1
><A
NAME="zend.returning"
>Chapter 35. Returning Values</A
></H1
><P
>&#13;   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 <TT
CLASS="envar"
>return_value</TT
> variable,
   which is passed to your functions as argument. The
   <TT
CLASS="envar"
>return_value</TT
> argument consists of a
   <TT
CLASS="envar"
>zval</TT
> 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
   <TT
CLASS="literal"
>MAKE_STD_ZVAL</TT
> on it. Instead, you can access its
   members directly.
  </P
><P
>&#13;   To make returning values from functions easier and to prevent
   hassles with accessing the internal structures of the
   <TT
CLASS="envar"
>zval</TT
> container, a set of predefined macros is
   available (as usual). These macros automatically set the
   correspondent type and value, as described in 
   <A
HREF="zend.returning.html#tab.return"
>Table 35-1</A
> and <A
HREF="zend.returning.html#tab.retval"
>Table 35-2</A
>.
  </P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
    The macros in <A
HREF="zend.returning.html#tab.return"
>Table 35-1</A
> automatically 
    <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>return</I
></SPAN
> from your function, those in 
    <A
HREF="zend.returning.html#tab.retval"
>Table 35-2</A
> only <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>set</I
></SPAN
> 
    the return value; they don't return from your function.
   </P
></BLOCKQUOTE
></DIV
><DIV
CLASS="table"
><A
NAME="tab.return"
></A
><P
><B
>Table 35-1. Predefined Macros for Returning Values from a
    Function</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Macro</TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Description</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETURN_RESOURCE(resource)</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Returns a resource.</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETURN_BOOL(bool)</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Returns a Boolean.</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETURN_NULL()</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Returns nothing (a NULL value).</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETURN_LONG(long)</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Returns a long.</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETURN_DOUBLE(double)</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Returns a double.</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        <TT
CLASS="literal"
>RETURN_STRING(string, duplicate)</TT
>
       </TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        Returns a string. The <TT
CLASS="envar"
>duplicate</TT
> flag indicates
        whether the string should be duplicated using
        <B
CLASS="function"
>estrdup()</B
>.
       </TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        <TT
CLASS="literal"
>RETURN_STRINGL(string, length, duplicate)</TT
>
       </TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        Returns a string of the specified length; otherwise, behaves
        like <TT
CLASS="literal"
>RETURN_STRING</TT
>. This macro is faster
        and binary-safe, however.
       </TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETURN_EMPTY_STRING()</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Returns an empty string.</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETURN_FALSE</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Returns Boolean false.</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETURN_TRUE</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Returns Boolean true.</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="table"
><A
NAME="tab.retval"
></A
><P
><B
>Table 35-2. Predefined Macros for Setting the Return Value
    of a Function</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Macro</TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Description</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETVAL_RESOURCE(resource)</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Sets the return value to the specified
        resource.</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETVAL_BOOL(bool)</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Sets the return value to the specified
        Boolean value.</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETVAL_NULL</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Sets the return value to NULL.</TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETVAL_LONG(long)</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        Sets the return value to the specified long.
       </TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETVAL_DOUBLE(double)</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        Sets the return value to the specified double.
       </TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        <TT
CLASS="literal"
>RETVAL_STRING(string, duplicate)</TT
>
       </TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        Sets the return value to the specified string and duplicates
        it to Zend internal memory if desired (see also
        <TT
CLASS="literal"
>RETURN_STRING</TT
>).
       </TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        <TT
CLASS="literal"
>RETVAL_STRINGL(string, length, duplicate)</TT
>
       </TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        Sets the return value to the specified string and forces the
        length to become <TT
CLASS="envar"
>length</TT
> (see also
        <TT
CLASS="literal"
>RETVAL_STRING</TT
>). This macro is faster and
        binary-safe, and should be used whenever the string length is
        known.
       </TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        <TT
CLASS="literal"
>RETVAL_EMPTY_STRING</TT
>
       </TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        Sets the return value to an empty string.
       </TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETVAL_FALSE</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        Sets the return value to Boolean false.
       </TD
></TR
><TR
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>RETVAL_TRUE</TT
></TD
><TD
WIDTH="50%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>&#13;        Sets the return value to Boolean true.
       </TD
></TR
></TBODY
></TABLE
></DIV
><P
>&#13;   Complex types such as arrays and objects can be returned by using
   <B
CLASS="function"
>array_init()</B
> and
   <B
CLASS="function"
>object_init()</B
>, as well as the corresponding hash
   functions on <TT
CLASS="envar"
>return_value</TT
>. Since these types cannot
   be constructed of trivial information, there are no predefined
   macros for them.
  </P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="zend.copy-constructor.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="zend.printing.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Duplicating Variable Contents: The Copy Constructor</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="zend.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Printing Information</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>