cvs: phpdoc-si /language functions.xml
| From: | Dejan Markic | Date: | Tue, 03 Sep 2002 13:48:29 +0000 |
| Subject: | cvs: phpdoc-si /language functions.xml | ||
| Groups: | php.doc.sl | ||
| Request: | Send a blank email to doc-sl+get-28@lists.php.net to get a copy of this message | ||
dejan Tue Sep 3 09:48:29 2002 EDT
Added files:
/phpdoc-si/language functions.xml
Log:
next one plese ;-)
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 (&) 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 & 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 -->
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 (&) 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 & 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 -->