cvs: phpdoc /en/language control-structures.xml operators.xml references.xml

derick Wed Jul 6 08:52:06 2005 EDT Modified files: /phpdoc/en/language control-structures.xml operators.xml references.xml Log: - Added some clarifications about references. http://cvs.php.net/diff.php/phpdoc/en/language/control-structures.xml?r1=1.119&r2=1.120&ty=u Index: phpdoc/en/language/control-structures.xml diff -u phpdoc/en/language/control-structures.xml:1.119 phpdoc/en/language/control-structures.xml:1.120 --- phpdoc/en/language/control-structures.xml:1.119 Mon Jun 6 11:26:19 2005 +++ phpdoc/en/language/control-structures.xml Wed Jul 6 08:52:03 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.119 $ --> +<!-- $Revision: 1.120 $ --> <chapter id="language.control-structures"> <title>Control Structures</title> @@ -1112,7 +1112,7 @@ if ($dump) { $temp = $profile; unset($profile); - return($temp); + return $temp; } $profile[] = microtime(); @@ -1190,9 +1190,21 @@ Note that since <function>return</function> is a language construct and not a function, the parentheses surrounding its arguments are <emphasis>only</emphasis> required if the argument - contains an expression. It is common to leave them out while returning a variable. + contains an expression. It is common to leave them out while returning a + variable, and you actually should as PHP has less work to do in this + case. </simpara> </note> + <note> + <simpara> + You should <emphasis>never</emphasis> use parentheses around your return + variable when returning by reference, as this will not work. You can + only return variables by reference, not the result of a statement. If + you use <literal>return ($a);</literal> then you're not returning a + variable, but the result of the expression <literal>($a)</literal> + (which is ofcourse the value of <varname>$a</varname>. + </simpara> + </note> </para> </sect1> http://cvs.php.net/diff.php/phpdoc/en/language/operators.xml?r1=1.89&r2=1.90&ty=u Index: phpdoc/en/language/operators.xml diff -u phpdoc/en/language/operators.xml:1.89 phpdoc/en/language/operators.xml:1.90 --- phpdoc/en/language/operators.xml:1.89 Wed Jun 22 04:20:40 2005 +++ phpdoc/en/language/operators.xml Wed Jul 6 08:52:03 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.89 $ --> +<!-- $Revision: 1.90 $ --> <chapter id="language.operators"> <title>Operators</title> <simpara> @@ -673,6 +673,16 @@ <replaceable>expr3</replaceable> if <replaceable>expr1</replaceable> evaluates to &false;. </para> + <note> + <simpara> + Please note that the ternary operator is a statement, and that it + doesn't evaluate to a variable, but to the result of a statement. This + is important to know if you want to return a variable by references. + The statement <literal>return $var == 42 ? $a : $b;</literal> in a + return-by-reference function will therefore not work and a warning is + issued in later PHP versions. + </simpara> + </note> </sect2> </sect1> http://cvs.php.net/diff.php/phpdoc/en/language/references.xml?r1=1.40&r2=1.41&ty=u Index: phpdoc/en/language/references.xml diff -u phpdoc/en/language/references.xml:1.40 phpdoc/en/language/references.xml:1.41 --- phpdoc/en/language/references.xml:1.40 Mon Jul 4 17:01:56 2005 +++ phpdoc/en/language/references.xml Wed Jul 6 08:52:04 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.40 $ --> +<!-- $Revision: 1.41 $ --> <chapter id="language.references"> <title>References Explained</title> @@ -254,7 +254,9 @@ </informalexample> Note that there's no reference sign on function call - only on function definition. Function definition alone is enough to - correctly pass the argument by reference. + correctly pass the argument by reference. In recent versions of PHP + you will get a warning saying that "Call-time pass-by-reference" is + deprecated when you use a &amp; in <literal>foo(&amp;$a);</literal>. </para> <para> Following things can be passed by reference: @@ -321,7 +323,10 @@ <title>Returning References</title> <para> Returning by-reference is useful when you want to use a function - to find which variable a reference should be bound to. When + to find which variable a reference should be bound to. Do + <emphasis>not</emphasis> use return-by-reference to increase performance, the + engine is smart enough to optimize this yourself. Only return references + when you have a valid technical reason to do it! When returning references, use this syntax: <informalexample> <programlisting role="php"> @@ -350,8 +355,15 @@ return by-reference, not a copy as usual, and to indicate that reference binding, rather than usual assignment, should be done for <varname>$foo</varname>. - <literal>&amp;</literal> by function definition is optional in - <link linkend="keyword.class">class</link> methods. + </simpara> + </note> + <note> + <simpara> + If you try to return a reference from a function with the syntax: + <literal>return ($found_var);</literal> this will <emphasis>not</emphasis> + work as you now try to return the result of an + <emphasis>expression</emphasis>, and not a variable, by reference. You can + only return variables by reference from a function - nothing else. </simpara> </note> </sect1> @@ -416,7 +428,7 @@ <sect2 id="references.this"> <title><literal>$this</literal></title> <simpara> - In an object method, <varname>$this</varname> is always reference + In an object method, <varname>$this</varname> is always a reference to the caller object. </simpara> </sect2>