svn: /phpdoc/en/trunk/ appendices/migration70/new-features.xml language/generators.xml
| From: | Adam Harvey | Date: | Mon, 21 Sep 2015 12:16:39 +0000 |
| Subject: | svn: /phpdoc/en/trunk/ appendices/migration70/new-features.xml language/generators.xml | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-13743@lists.php.net to get a copy of this message | ||
aharvey Mon, 21 Sep 2015 12:16:39 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=337864
Log:
Move most generator delegration doco to the generators section.
I've also simplified the example in the migration guide somewhat: the combined
"return yield from" construct is now documented only in the generators
documentation.
Changed paths:
U phpdoc/en/trunk/appendices/migration70/new-features.xml
U phpdoc/en/trunk/language/generators.xml
Modified: phpdoc/en/trunk/appendices/migration70/new-features.xml
===================================================================
--- phpdoc/en/trunk/appendices/migration70/new-features.xml 2015-09-21 12:16:34 UTC (rev 337863)
+++ phpdoc/en/trunk/appendices/migration70/new-features.xml 2015-09-21 12:16:39 UTC (rev 337864)
@@ -511,47 +511,37 @@
</para>
</sect2>
<sect2 xml:id="migration70.new-features.generator-delegation">
- <title>Generator Delegation</title>
+ <title>Generator delegation</title>
<para>
- Generator delegation builds upon the ability of being able to return
- expressions from generators. It does this by using an new syntax of
- <literal>yield from <expr></literal>, where <expr> can
be any
- <literal>Traversable</literal> <type>object</type> or
<type>array</type>.
- This <expr> will be advanced until no longer valid, and then execution
- will continue in the calling generator. This feature enables
- <literal>yield</literal> statements to be broken down into smaller
- operations, thereby promoting cleaner code that has greater reusability.
+ Generators can now delegate to another generator,
+ <classname>Traversable</classname> object or <type>array</type>
+ automatically, without needing to write boilerplate in the outermost
+ generator by using the &yield.from; construct.
</para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
-
function gen()
{
yield 1;
yield 2;
-
- return yield from gen2();
+ yield from gen2();
}
function gen2()
{
yield 3;
-
- return 4;
+ yield 4;
}
-$gen = gen();
-
-foreach ($gen as $val)
+foreach (gen() as $val)
{
echo $val, PHP_EOL;
}
-
-echo $gen->getReturn();
+?>
]]>
</programlisting>
&example.outputs;
Modified: phpdoc/en/trunk/language/generators.xml
===================================================================
--- phpdoc/en/trunk/language/generators.xml 2015-09-21 12:16:34 UTC (rev 337863)
+++ phpdoc/en/trunk/language/generators.xml 2015-09-21 12:16:39 UTC (rev 337864)
@@ -371,18 +371,108 @@
</screen>
</example>
</sect3>
- </sect2>
- <sect2 xml:id="language.generators.object">
- <title><classname>Generator</classname> objects</title>
- <para>
- When a generator function is called for the first time, an object of the
- internal <classname>Generator</classname> class is returned. This object
- implements the <classname>Iterator</classname> interface in much the same
- way as a forward-only iterator object would.
- </para>
+ <sect3 xml:id="control-structures.yield.from">
+ <title>Generator delegation via <command>yield from</command></title>
+
+ <para>
+ In PHP 7, generator delegation allows you to yield values from another
+ generator, <classname>Traversable</classname> object, or
+ <type>array</type> by using the <command>yield from</command> keyword.
+ The outer generator will then yield all values from the inner generator,
+ object, or array until that is no longer valid, after which execution
+ will continue in the outer generator.
+ </para>
+
+ <para>
+ If a generator is used with <command>yield from</command>, the
+ <command>yield from</command> expression will also return any value
+ returned by the inner generator.
+ </para>
+
+ <example>
+ <title>Basic use of <command>yield from</command></title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+function count_to_ten() {
+ yield 1;
+ yield 2;
+ yield from [3, 4];
+ yield from new ArrayIterator([5, 6]);
+ yield from seven_eight();
+ yield 9;
+ yield 10;
+}
+
+function seven_eight() {
+ yield 7;
+ yield from eight();
+}
+
+function eight() {
+ yield 8;
+}
+
+foreach (count_to_ten() as $num) {
+ echo "$num ";
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+1 2 3 4 5 6 7 8 9 10
+]]>
+ </screen>
+ </example>
+
+ <example>
+ <title><command>yield from</command> and return values</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+function count_to_ten() {
+ yield 1;
+ yield 2;
+ yield from [3, 4];
+ yield from new ArrayIterator([5, 6]);
+ yield from seven_eight();
+ return yield from nine_ten();
+}
+
+function seven_eight() {
+ yield 7;
+ yield from eight();
+}
+
+function eight() {
+ yield 8;
+}
+
+function nine_ten() {
+ yield 9;
+ return 10;
+}
+
+$gen = count_to_ten();
+foreach ($gen as $num) {
+ echo "$num ";
+}
+echo $gen->getReturn();
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+1 2 3 4 5 6 7 8 9 10
+]]>
+ </screen>
+ </example>
+ </sect3>
</sect2>
-
</sect1>
<sect1 xml:id="language.generators.comparison">