cvs: phpdoc /en/language references.xml

From: Date: Sun, 10 Dec 2000 09:46:16 +0000
Subject: cvs: phpdoc /en/language references.xml
Groups: php.doc 
Request: Send a blank email to phpdoc+get-969333191@lists.php.net to get a copy of this message
stas Sun Dec 10 01:46:16 2000 EDT Modified files: /phpdoc/en/language references.xml Log: Add description of new passing by reference rules Index: phpdoc/en/language/references.xml diff -u phpdoc/en/language/references.xml:1.6 phpdoc/en/language/references.xml:1.7 --- phpdoc/en/language/references.xml:1.6 Tue Oct 3 19:02:28 2000 +++ phpdoc/en/language/references.xml Sun Dec 10 01:46:15 2000 @@ -38,6 +38,26 @@ </note> </para> <para> + The same syntax can be used with functions, that return references, + and with <literal>new</literal> operator (in PHP 4.0.4 and later): + <informalexample> + <programlisting role="php"> +$bar =&amp; new fooclass(); +$foo =&amp; find_var ($bar); + </programlisting> + </informalexample> + </para> + <note> + <para> + Unless you use the syntax above, the result of + <literal>$bar = new fooclass()</literal> will not be the same + variable as <literal>$this</literal> in the constructor, meaning + that if you have used reference to <literal>$this</literal> in + the constructor, you should use reference assignment, or you get + two different objects. + </para> + </note> + <para> The second thing references do is to pass variables by-reference. This is done by making local function variable and caller variable to be reference to the same content. Example: @@ -54,11 +74,12 @@ will make <varname>$a</varname> to be 6. This happens because in the function <varname>foo</varname> the variable <varname>$var</varname> refers to the same content as - <varname>$a</varname>. + <varname>$a</varname>. See also more detailed explanations about <link + linkend="language.references.pass">passing by reference</link>. </para> <simpara> The third thing reference can do is <link - linkend="language.references.return">return by-reference</link>. + linkend="language.references.return">return by reference</link>. </simpara> </sect1> @@ -87,6 +108,79 @@ variable contents and not name-to-value binding in the calling symbol table). </simpara> + </sect1> + + <sect1 id="language.references.pass"> + <title>Passing by Reference</title> + <para> + You can pass variable to function by reference, so that function could modify + its arguments. The sytax is as follows: + <informalexample> + <programlisting role="php"> +function foo (&amp;$var) { + $var++; +} + +$a=5; +foo ($a); +// $a is 6 here + </programlisting> + </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. + </para> + <para> + Following things can be passed by reference: + <itemizedlist> + <listitem> + <simpara> + Variable, i.e. <literal>foo($a)</literal> + </simpara> + </listitem> + <listitem> + <simpara> + New statement, i.e. <literal>foo(new foobar())</literal> + </simpara> + </listitem> + <listitem> + <para> + Reference, returned from a function, i.e.: + <informalexample> + <programlisting role="php"> +function &amp;bar() +{ + $a = 5; + return $a; +} +foo(bar()); + </programlisting> + </informalexample> + See also explanations about <link + linkend="language.references.return">returning by reference</link>. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Any other expression should not be passed by reference, as the + result is undefined. For example, the following examples of passing + by reference are invalid: + <informalexample> + <programlisting role="php"> +function bar() // Note the missing &amp; +{ + $a = 5; + return $a; +} +foo(bar)); + +foo($a = 5) // Expression, not variable +foo(5) // Constant, not variable + </programlisting> + </informalexample> +These requirements are for PHP 4.0.4 and later. + </para> </sect1> <sect1 id="language.references.return">

« previous php.doc (#969333191) next »