cvs: phpdoc /en/language functions.xml

philip Sat May 17 10:29:40 2003 EDT Modified files: /phpdoc/en/language functions.xml Log: Made all informal examples formal (with titles), XML formatting, and added PHP tags. Index: phpdoc/en/language/functions.xml diff -u phpdoc/en/language/functions.xml:1.35 phpdoc/en/language/functions.xml:1.36 --- phpdoc/en/language/functions.xml:1.35 Fri May 16 23:37:43 2003 +++ phpdoc/en/language/functions.xml Sat May 17 10:29:40 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.35 $ --> +<!-- $Revision: 1.36 $ --> <chapter id="functions"> <title>Functions</title> @@ -8,18 +8,22 @@ <para> A function may be defined using syntax such as the following: - - <informalexample> + </para> + <para> + <example> + <title>Psuedo code to demonstrate function uses</title> <programlisting role="php"> <![CDATA[ +<?php function foo ($arg_1, $arg_2, ..., $arg_n) { echo "Example function.\n"; return $retval; } +?> ]]> </programlisting> - </informalexample> + </example> </para> <!-- @@ -45,6 +49,8 @@ When a function is defined in a conditional manner such as the two examples shown. Its definition must be processed <emphasis>prior</emphasis> to being called. + </para> + <para> <example> <title>Conditional functions</title> <programlisting role="php"> @@ -80,6 +86,8 @@ ]]> </programlisting> </example> + </para> + <para> <example> <title>Functions within functions</title> <programlisting role="php"> @@ -141,21 +149,23 @@ 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> + 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: + </para> + <para> + <example> + <title>Passing arrays to functions</title> <programlisting role="php"> <![CDATA[ function takes_array($input) @@ -164,7 +174,7 @@ } ]]> </programlisting> - </informalexample> + </example> </para> <sect2 id="functions.arguments.by-reference"> @@ -181,10 +191,13 @@ 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> + </para> + <para> + <example> + <title>Passing function parameters by reference</title> <programlisting role="php"> <![CDATA[ +<?php function add_some_extra(&$string) { $string .= 'and something extra.'; @@ -192,9 +205,10 @@ $str = 'This is a string, '; add_some_extra($str); echo $str; // outputs 'This is a string, and something extra.' +?> ]]> </programlisting> - </informalexample> + </example> </para> </sect2> @@ -205,24 +219,29 @@ <para> A function may define C++-style default values for scalar arguments as follows: - - <informalexample> + </para> + <para> + <example> + <title>Use of default parameters in functions</title> <programlisting role="php"> <![CDATA[ +<?php function makecoffee ($type = "cappuccino") { return "Making a cup of $type.\n"; } echo makecoffee (); echo makecoffee ("espresso"); +?> ]]> </programlisting> - </informalexample> + </example> </para> <para> The output from the above snippet is: - + </para> + <para> <screen> Making a cup of cappuccino. Making a cup of espresso. @@ -237,51 +256,60 @@ 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> + </para> + <para> + <example> + <title>Incorrect usage of default function arguments</title> <programlisting role="php"> <![CDATA[ +<?php function makeyogurt ($type = "acidophilus", $flavour) { return "Making a bowl of $type $flavour.\n"; } echo makeyogurt ("raspberry"); // won't work as expected +?> ]]> </programlisting> - </informalexample> + </example> </para> <para> The output of the above example is: - + </para> + <para> <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> + </para> + <para> + <example> + <title>Correct usage of default function arguments</title> <programlisting role="php"> <![CDATA[ +<?php function makeyogurt ($flavour, $type = "acidophilus") { return "Making a bowl of $type $flavour.\n"; } echo makeyogurt ("raspberry"); // works as expected +?> ]]> </programlisting> - </informalexample> + </example> </para> <para> The output of this example is: - + </para> + <para> <screen> Making a bowl of acidophilus raspberry. </screen> @@ -319,51 +347,65 @@ 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> + </para> + <para> + <example> + <title>Use of <function>return</function></title> <programlisting role="php"> <![CDATA[ +<?php function square ($num) { return $num * $num; } echo square (4); // outputs '16'. +?> ]]> </programlisting> - </informalexample> + </example> </para> <para> You can't return multiple values from a function, but similar results can be obtained by returning a list. - - <informalexample> + </para> + <para> + <example> + <title>Returning an array to get multiple values</title> <programlisting role="php"> <![CDATA[ +<?php function small_numbers() { return array (0, 1, 2); } list ($zero, $one, $two) = small_numbers(); +?> ]]> </programlisting> - </informalexample> + </example> </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> + </para> + <para> + <example> + <title>Returning a reference from a function</title> <programlisting role="php"> <![CDATA[ +<?php function &returns_reference() { return $someref; } $newref =& returns_reference(); +?> ]]> </programlisting> - </informalexample> + </example> </para> <simpara> For more information on references, please check out <link