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 & in <literal>foo(&$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>&</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>
