[PHP-DOC] cvs: phpdoc /en/language references.xml From: Stanislav Malyshev (stas <email protected>)
Date: 12/10/00

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">