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

stas Sun Aug 20 03:28:13 2000 EDT

  Modified files:
    /phpdoc/en/language references.xml
  Log:
  Add more explanations, small fixes
  
  
Index: phpdoc/en/language/references.xml
diff -u phpdoc/en/language/references.xml:1.2 phpdoc/en/language/references.xml:1.3
--- phpdoc/en/language/references.xml:1.2 Sat Aug 19 03:01:41 2000
+++ phpdoc/en/language/references.xml Sun Aug 20 03:28:13 2000
@@ -21,8 +21,7 @@
 
   <informalexample>
    <programlisting role="php">
-$a =&amp; $b
- </programlisting>
+ $a =&amp; $b </programlisting>
   </informalexample>
 
   it means that <varname>$a</varname> and <varname>$b</varname> point to
@@ -38,23 +37,27 @@
   </para>
 
   <para>
- The second thing references do is to pass variables by-references. This is
+ 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:
 
   <informalexample>
    <programlisting role="php">
-function foo(&amp;$var) {
- $var++;
-}
-
-$a=5;
-foo($a);
- </programlisting>
+ function foo(&amp;$var) {
+ $var++;
+ }
+
+ $a=5;
+ foo($a);</programlisting>
   </informalexample>
 
- will make <varname>$a</varname> to be 6.
+ 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>.
   </para>
+
+ <simpara>
+ The third thing reference can do is
+ <link linkend="language.references.return">return by-reference</link>.
+ </simpara>
  </sect1>
 
  <sect1 id="language.references.arent">
@@ -65,22 +68,22 @@
 
   <informalexample>
    <programlisting role="php">
-function foo(&amp;$var) {
- $var =&amp; $GLOBALS["baz"];
-}
-foo($bar);
- </programlisting>
+ function foo(&amp;$var) {
+ $var =&amp; $GLOBALS["baz"];
+ }
+ foo($bar); </programlisting>
   </informalexample>
   </para>
 
   <simpara>
   What will happen that <varname>$var</varname> in foo will be bound with
   <varname>$bar</varname> in caller, but then it will be re-bound with
- <varname>$GLOBALS["baz"]</varname>. There's no way to bind <varname>$bar</varname>
- in caller to something else using reference mechanism, since
- <varname>$bar</varname> is not available in the function foo (it is
- represented by <varname>$var</varname>, but <varname>$var</varname>
- has only variable contents and not name-to-value binding).
+ <varname>$GLOBALS["baz"]</varname>. There's no way to bind
+ <varname>$bar</varname> in the caller to something else using reference
+ mechanism, since <varname>$bar</varname> is not available in the function
+ foo (it is represented by <varname>$var</varname>, but
+ <varname>$var</varname> has only variable contents and not name-to-value
+ binding in the calling symbol table).
   </simpara>
  </sect1>
 
@@ -93,18 +96,25 @@
 
   <informalexample>
    <programlisting role="php">
-function &amp;find_var($param) {
- ...code...
- return $found_var;
-}
+ function &amp;find_var($param) {
+ ...code...
+ return $found_var;
+ }
 
-$foo =&amp; find_var($bar);
- </programlisting>
+ $foo =&amp; find_var($bar);
+ $foo->x = 2; </programlisting>
   </informalexample>
+
+ In this example, property of the object returned by the
+ <varname>find_var</varname> function would be set, not of the copy, as
+ it would be without using reference syntax.
   </para>
   <note>
     <simpara>
- Unlike parameter passing, here you use &amp; in both places.
+ Unlike parameter passing, here you have to use <literal>&amp;</literal>
+ in both places - to indicate that you return by-reference, not a copy
+ as usual, and to indicate than reference binding and not usual
+ assignment should be done for <varname>$foo</varname>.
     </simpara>
   </note>
  </sect1>
@@ -118,19 +128,17 @@
 
   <informalexample>
    <programlisting role="php">
-$a = 1;
-$b =&amp; $a;
-unset($a);
- </programlisting>
+ $a = 1;
+ $b =&amp; $a;
+ unset($a); </programlisting>
   </informalexample>
 
-
   won't unset <varname>$b</varname>, just <varname>$a</varname>.
   </para>
 
   <simpara>
- Again, it might be useful to think about this as analogous to Unix unlink
- call.
+ Again, it might be useful to think about this as analogous to Unix
+ <command>unlink</command> call.
   </simpara>
  </sect1>
 
@@ -154,7 +162,7 @@
 
   <informalexample>
    <programlisting role="php">
-$var =&amp; $GLOBALS["var"];</programlisting>
+ $var =&amp; $GLOBALS["var"];</programlisting>
   </informalexample>
   </para>