CVS update: phpdoc/language

Date: Sunday June 27, 1999 @ 22:25 Author: jim Update of /repository/phpdoc/language In directory php:/tmp/cvs-serv2649/language Modified Files: control-structures.sgml Added Files: functions.sgml Log Message: Break functions stuff into its own (as yet skimpy) chapter. Index: phpdoc/language/control-structures.sgml diff -u phpdoc/language/control-structures.sgml:1.1 phpdoc/language/control-structures.sgml:1.2 --- phpdoc/language/control-structures.sgml:1.1 Sat Jun 19 22:25:34 1999 +++ phpdoc/language/control-structures.sgml Sun Jun 27 22:25:19 1999 @@ -138,7 +138,7 @@ preceding <literal>elseif</literal> expressions evaluated to <literal>FALSE</literal>, and the current <literal>elseif</literal> expression evaluated to <literal>TRUE</literal>. - <sect1> + <sect1 id="control-structures.alternative-syntax"> <title>Alternative syntax for <literal>if</literal> structures: <literal>if(): ... endif;</literal></title> <para> @@ -646,216 +646,6 @@ <para> See also <function>readfile</function>, <function>require</function>, <function>virtual</function>. - - <sect1 id="keyword.function"> - <title><literal>function</literal></title> - - <para> - A function may be defined using syntax such as the following: - - <informalexample> - <programlisting> - function foo ($arg_1, $arg_2, ..., $arg_n) { - echo "Example function.\n"; - return $retval; - } - </programlisting> - </informalexample> - - <simpara> - Any valid PHP code may appear inside a function, even other - functions and <link linkend="keyword.class">class</link> - definitions. - - <simpara> - Functions must be defined before they are referenced. - - <sect1 id="keyword.function.return"> - <title>Returning values</title> - - <para> - Values are returned by using the optional return statement. Any - type may be returned, including lists and objects. - - <informalexample> - <programlisting> - function my_sqrt ($num) { - return $num * $num; - } - echo my_sqrt (4); // outputs '16'. - </programlisting> - </informalexample> - - <para> - Multiple values may not be returned, but the same effect can be - achieved by returning a list: - - <informalexample> - <programlisting> - function foo() { - return array (0, 1, 2); - } - list ($zero, $one, $two) = foo(); - </programlisting> - </informalexample> - - <sect2 id="keyword.function.arguments"> - <title>Arguments</title> - - <simpara> - Information may be passed to functions via the argument list, - which is a comma-delimited list of variables and/or constants. - - <para> - PHP supports passing arguments by value (the default), <link - linkend="keyword.function.arguments.reference">passing by - reference</link>, and <link - linkend="keyword.function.arguments.default">default argument - values</link>. Variable-length argument lists are not supported, - but a similar effect may be achieved by passing arrays. - - <informalexample> - <programlisting> - function takes_array($input) { - echo "$input[0] + $input[1] = ", $input[0]+$input[1]; - } - </programlisting> - </informalexample> - - <sect3 id="keyword.function.arguments.reference"> - <title>Passing by reference</title> - - <simpara> - By default, function arguments are passed by value. If you wish - to allow a function to modify its arguments, you may pass them - by reference. - - <para> - If you wish a function's argument to always be passed by - reference, you can prepend an ampersand (&amp;) to the argument - name in the function definition: - - <informalexample> - <programlisting> - function foo( &amp;$bar ) { - $bar .= 'and something extra.'; - } - $str = 'This is a string, '; - foo ($str); - echo $str; // outputs 'This is a string, and something extra.' - </programlisting> - </informalexample> - - <para> - If you wish to pass a variable by reference to a function which - does not do this by default, you may prepend an ampersand to the - argument name in the function call: - - <informalexample> - <programlisting> - function foo ($bar) { - $bar .= ' and something extra.'; - } - $str = 'This is a string, '; - foo ($str); - echo $str; // outputs 'This is a string, ' - foo (&amp;$str); - echo $str; // outputs 'This is a string, and something extra.' - </programlisting> - </informalexample> - - <sect3 id="keyword.function.arguments.default"> - <title>Default values</title> - - <para> - A function may define C++-style default values for scalar - arguments as follows: - - <informalexample> - <programlisting> - function makecoffee ($type = "cappucino") { - echo "Making a cup of $type.\n"; - } - echo makecoffee (); - echo makecoffee ("espresso"); - </programlisting> - </informalexample> - - <para> - The output from the above snippet is: - - <screen> - Making a cup of cappucino. - Making a cup of espresso. - </screen> - - <simpara> - The default value must be a constant expression, not (for - example) a variable or class member. - - <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> - function makeyogurt ($type = "acidophilus", $flavour) { - return "Making a bowl of $type $flavour.\n"; - } - - echo makeyogurt ("raspberry"); // won't work as expected - </programlisting> - </informalexample> - - <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> - Now, compare the above with this: - - <informalexample> - <programlisting> - function makeyogurt ($flavour, $type = "acidophilus") { - return "Making a bowl of $type $flavour.\n"; - } - - echo makeyogurt ("raspberry"); // works as expected - </programlisting> - </informalexample> - - <para> - The output of this example is: - - <screen> - Making a bowl of acidophilus raspberry. - </screen> - - <sect1 id="keyword.old-function"> - <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> - This is a deprecated feature, and should only be used by the - PHP/FI2->PHP3 convertor. - <simpara> - 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 PHP3 form) - to call the <literal>old_function</literal>. <sect1 id="keyword.class"> <title><literal>class</literal></title>