[prev in list] [next in list] [prev in thread] [next in thread] 

List:       php-doc-cvs
Subject:    [DOC-CVS] =?utf-8?q?svn:_/phpdoc/en/trunk/language/predefined/generator/_send.xml_throw.xml?=
From:       Nikita_Popov <nikic () php ! net>
Date:       2013-11-30 14:08:57
Message-ID: svn-nikic-1385820537-332229-348381156 () svn ! php ! net
[Download RAW message or body]

nikic                                    Sat, 30 Nov 2013 14:08:57 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=332229

Log:
Add basic docs for Generator::throw()

Changed paths:
    U   phpdoc/en/trunk/language/predefined/generator/send.xml
    U   phpdoc/en/trunk/language/predefined/generator/throw.xml

Modified: phpdoc/en/trunk/language/predefined/generator/send.xml
===================================================================
--- phpdoc/en/trunk/language/predefined/generator/send.xml	2013-11-29 21:22:54 UTC (rev 332228)
+++ phpdoc/en/trunk/language/predefined/generator/send.xml	2013-11-30 14:08:57 UTC (rev 332229)
@@ -14,15 +14,14 @@
    <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Sends the given value to the generator as the result of the yield expression
-   and resumes execution of the generator.
+   Sends the given value to the generator as the result of the current &yield;
+   expression and resumes execution of the generator.
   </para>
-
   <para>
-   <methodname>Generator::send</methodname> allows values to be injected into
-   generator functions while iterating over them. The injected value will be
-   returned from the &yield; statement and can then be used like any other
-   variable within the generator function.
+   If the generator is not at a &yield; expression when this method is called, it
+   will first be let to advance to the first &yield; expression before sending the
+   value. As such it is not necessary to "prime" PHP generators with a
+   <methodname>Generator::next</methodname> call (like it is done in Python).
   </para>
  </refsect1>

@@ -33,7 +32,8 @@
     <term><parameter>value</parameter></term>
     <listitem>
      <para>
-
+      Value to send into the generator. This value will be the return value of the
+      &yield; expression the generator is currently at.
      </para>
     </listitem>
    </varlistentry>
@@ -57,6 +57,7 @@

 $printer = printer();
 $printer->send('Hello world!');
+$printer->send('Bye world!');
 ?>
 ]]>
     </programlisting>
@@ -64,6 +65,7 @@
     <screen>
 <![CDATA[
 Hello world!
+Bye world!
 ]]>
     </screen>
    </example>

Modified: phpdoc/en/trunk/language/predefined/generator/throw.xml
===================================================================
--- phpdoc/en/trunk/language/predefined/generator/throw.xml	2013-11-29 21:22:54 UTC (rev 332228)
+++ phpdoc/en/trunk/language/predefined/generator/throw.xml	2013-11-30 14:08:57 UTC (rev 332229)
@@ -10,9 +10,18 @@
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Generator::throw</methodname>
+   <modifier>public</modifier> <type>mixed</type><methodname>Generator::throw</methodname>
    <methodparam><type>Exception</type><parameter>exception</parameter></methodparam>
   </methodsynopsis>
+  <para>
+   Throws an exception into the generator and resumes execution of the generator.
+   The behavior will be the same as if the current &yield; expression was replaced with
+   a <literal>throw $exception</literal> statement.
+  </para>
+  <para>
+   If the generator is already closed when this method is invoked, the exception will
+   be thrown in the caller's context instead.
+  </para>
  </refsect1>

  <refsect1 role="parameters">
@@ -22,13 +31,50 @@
     <term><parameter>exception</parameter></term>
     <listitem>
      <para>
-
+      Exception to throw into the generator.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Throwing an exception into a generator</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+function gen() {
+    echo "Foo\n";
+    try {
+        yield;
+    } catch (Exception $e) {
+        echo "Exception: {$e->getMessage()}\n";
+    }
+    echo "Bar\n";
+}
+
+$gen = gen();
+$gen->rewind();
+$gen->throw(new Exception('Test'));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+Foo
+Exception: Test
+Bar
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>

+
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>



-- 
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[prev in list] [next in list] [prev in thread] [next in thread]