cvs: phpdoc-si /language functions.xml

Index: phpdoc-si/language/functions.xml
+++ phpdoc-si/language/functions.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $EN-Revision: 1.28 Maintainer: dejan Status: working -->
 <chapter id="functions">
  <title>Functions</title>

  <sect1 id="functions.user-defined">
   <title>User-defined functions</title>
 
   <para>
    A function may be defined using syntax such as the following:
 
    <informalexample>
     <programlisting role="php">
<![CDATA[
function foo ($arg_1, $arg_2, ..., $arg_n)
{
    echo "Example function.\n";
    return $retval;
}
]]>
     </programlisting>
    </informalexample>
   </para>
   
   <!--
    
    status of func(const $param) ?
    zend doesn't care at all whether or not you specify it.
    I've never seen it before... what's its use? (or was...)
    
    -->
     
   <simpara>
    Any valid PHP code may appear inside a function, even other
    functions and <link linkend="keyword.class">class</link>
    definitions.
   </simpara>
   <simpara>
    In PHP 3, functions must be defined before they are referenced. No
    such requirement exists in PHP 4.
   </simpara>
   <simpara>
    PHP does not support function overloading, nor is it possible to
    undefine or redefine previously-declared functions.
   </simpara>
   <simpara>
    PHP 3 does not support variable numbers of arguments to functions,
    although default arguments are supported (see <link
    linkend="functions.arguments.default">Default argument
    values</link> for more information). PHP 4 supports both: see <link
    linkend="functions.variable-arg-list">Variable-length argument
    lists</link> and the function references for
    <function>func_num_args</function>,
    <function>func_get_arg</function>, and
    <function>func_get_args</function> for more information.
   </simpara>

  </sect1>
 
  <sect1 id="functions.arguments">
   <title>Function arguments</title>
 
   <simpara>
    Information may be passed to functions via the argument list,
    which is a comma-delimited list of variables and/or constants.
   </simpara> 
   <para>
     PHP supports passing arguments by value (the default), <link
     linkend="functions.arguments.by-reference">passing by
     reference</link>, and <link
     linkend="functions.arguments.default">default argument
     values</link>. Variable-length argument lists are supported only
     in PHP 4 and later; see <link
     linkend="functions.variable-arg-list">Variable-length argument
     lists</link> and the function references for
     <function>func_num_args</function>,
     <function>func_get_arg</function>, and
     <function>func_get_args</function> for more information. A
     similar effect can be achieved in PHP 3 by passing an array of
     arguments to a function:
 
    <informalexample>
     <programlisting role="php">
<![CDATA[
function takes_array($input)
{
    echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}
]]>
     </programlisting>
    </informalexample>
   </para>
 
   <sect2 id="functions.arguments.by-reference">
    <title>Making arguments be passed by reference</title>
 
    <simpara>
     By default, function arguments are passed by value (so that if
     you change the value of the argument within the function, it does
     not get changed outside of the function). If you wish to allow a
     function to modify its arguments, you must pass them by
     reference.
    </simpara>
    <para>
     If you want an argument to a function to always be passed by
     reference, you can prepend an ampersand (&amp;) to the argument
     name in the function definition:
 
     <informalexample>
      <programlisting role="php">
<![CDATA[
function add_some_extra(&$string)
{
    $string .= 'and something extra.';
}
$str = 'This is a string, ';
add_some_extra($str);
echo $str;    // outputs 'This is a string, and something extra.'
]]>
      </programlisting>
     </informalexample>
    </para>
 
   </sect2>
 
   <sect2 id="functions.arguments.default">
    <title>Default argument values</title>
 
    <para>
     A function may define C++-style default values for scalar
     arguments as follows:
 
     <informalexample>
      <programlisting role="php">
<![CDATA[
function makecoffee ($type = "cappuccino")
{
    return "Making a cup of $type.\n";
}
echo makecoffee ();
echo makecoffee ("espresso");
]]>
      </programlisting>
     </informalexample>
    </para>
 
    <para>
     The output from the above snippet is:
 
     <screen>
Making a cup of cappuccino.
Making a cup of espresso.
     </screen>
    </para>
 
    <simpara>
     The default value must be a constant expression, not (for
     example) a variable or class member.
    </simpara>
    <para>
     Note that when using default arguments, any defaults should be on
     the right side of any non-default arguments; otherwise, things
     will not work as expected. Consider the following code snippet:
 
     <informalexample>
      <programlisting role="php">
<![CDATA[
function makeyogurt ($type = "acidophilus", $flavour)
{
    return "Making a bowl of $type $flavour.\n";
}
 
echo makeyogurt ("raspberry");   // won't work as expected
]]>
      </programlisting>
     </informalexample>
    </para>
 
    <para>
     The output of the above example is:
 
     <screen>
Warning: Missing argument 2 in call to makeyogurt() in 
/usr/local/etc/httpd/htdocs/php3test/functest.html on line 41
Making a bowl of raspberry .
     </screen>
    </para>
 
    <para>
     Now, compare the above with this:
 
     <informalexample>
      <programlisting role="php">
<![CDATA[
function makeyogurt ($flavour, $type = "acidophilus")
{
    return "Making a bowl of $type $flavour.\n";
}
 
echo makeyogurt ("raspberry");   // works as expected
]]>
      </programlisting>
     </informalexample>
    </para>
 
    <para>
     The output of this example is:
 
     <screen>
Making a bowl of acidophilus raspberry.
     </screen>
    </para>

   </sect2>

   <sect2 id="functions.variable-arg-list">
    <title>Variable-length argument lists</title>
	
    <simpara>
     PHP 4 has support for variable-length argument lists in
     user-defined functions. This is really quite easy, using the
     <function>func_num_args</function>,
     <function>func_get_arg</function>, and
     <function>func_get_args</function> functions.
    </simpara>

    <simpara>
     No special syntax is required, and argument lists may still be
     explicitly provided with function definitions and will behave as
     normal.
    </simpara>

   </sect2>

  </sect1>
 
  <sect1 id="functions.returning-values">
   <title>Returning values</title>
 
   <para>
    Values are returned by using the optional return statement. Any
    type may be returned, including lists and objects. This causes the
    function to end its execution immediately and pass control back to
    the line from which it was called. See <function>return</function>
    for more information.
    <informalexample>
     <programlisting role="php">
<![CDATA[
function square ($num)
{
    return $num * $num;
}
echo square (4);   // outputs '16'.
]]>
     </programlisting>
    </informalexample>
   </para>
      
   <para>
    You can't return multiple values from a function, but similar
    results can be obtained by returning a list.
 
    <informalexample>
     <programlisting role="php">
<![CDATA[
function small_numbers()
{
    return array (0, 1, 2);
}
list ($zero, $one, $two) = small_numbers();
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    To return a reference from a function, you have to use
    the reference operator &amp; in both the function declaration and
    when assigning the returned value to a variable:
    <informalexample>
     <programlisting role="php">
<![CDATA[
function &returns_reference()
{
    return $someref;
}

$newref =& returns_reference();
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    For more information on references, please check out <link
    linkend="language.references">References Explained</link>.
   </simpara>
  </sect1>
 
  <sect1 id="functions.old-syntax">
   <title><literal>old_function</literal></title>
 
   <simpara>
    The <literal>old_function</literal> statement allows you to
    declare a function using a syntax identical to PHP/FI2 (except you
    must replace 'function' with 'old_function'.
   </simpara>
   <simpara>
    This is a deprecated feature, and should only be used by the
    PHP/FI2->PHP 3 convertor.
   </simpara>
   <warning>
    <para>
     Functions declared as <literal>old_function</literal> cannot be
     called from PHP's internal code. Among other things, this means
     you can't use them in functions such as
     <function>usort</function>, <function>array_walk</function>, and
     <function>register_shutdown_function</function>. You can get
     around this limitation by writing a wrapper function (in normal
     PHP 3 form) to call the <literal>old_function</literal>.
    </para>
   </warning>

  </sect1>

  <sect1 id="functions.variable-functions">
   <title>Variable functions</title>

   <para>
    PHP supports the concept of variable functions. This means that if
    a variable name has parentheses appended to it, PHP will look for
    a function with the same name as whatever the variable evaluates
    to, and will attempt to execute it. Among other things, this can
    be used to implement callbacks, function tables, and so forth.
   </para>
   <para>
    Variable functions won't work with language constructs such 
    as <function>echo</function>, <function>unset</function>,
    <function>isset</function>, <function>empty</function>, 
    <function>include</function> and <function>print</function>.
   </para>
   <para>
    <example>
     <title>Variable function example</title>
     <programlisting role="php">
<![CDATA[
<?php
function foo()
{
    echo "In foo()<br>\n";
}

function bar($arg = '')
{
    echo "In bar(); argument was '$arg'.<br>\n";
}

$func = 'foo';
$func();
$func = 'bar';
$func('test');
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    See also <link linkend="language.variables.variable">
    variable variables</link> and <function>function_exists</function>.
   </para>

  </sect1>

 </chapter>
 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->