svn: /phpdoc/en/trunk/ appendices/migration70/new-features.xml language/generators.xml

From: 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 &lt;expr&gt;</literal>, where &lt;expr&gt; can be any - <literal>Traversable</literal> <type>object</type> or <type>array</type>. - This &lt;expr&gt; 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">

« previous php.doc.cvs (#13743) next »