Add basic docs for Generator::throw()

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@332229 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Nikita Popov 2013-11-30 14:08:57 +00:00
parent 35787490f2
commit 7101312585
2 changed files with 58 additions and 10 deletions

View file

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

View file

@ -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,12 +31,49 @@
<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;