<?xml version="1.0" encoding="utf-8"?>

<chapter xml:id="language.generators" xmlns="http://docbook.org/ns/docbook">

<title>Generators</title>

<sect1 xml:id="language.generators.overview">

<title>Generators overview</title>

<?phpdoc print-version-for="generators"?>

<para>

Generators provide an easy way to implement simple

<link linkend="language.oop5.iterations">iterators</link> without the

overhead or complexity of implementing a class that implements the

<classname>Iterator</classname> interface.

</para>

<para>

A generator offers a convenient way to provide data to &foreach; loops without

having to build an array in memory ahead of time, which may cause the program

to exceed a memory limit or require a considerable amount of

processing time to generate. Instead, a generator function can be used,

which is the same as a normal

<link linkend="functions.user-defined">function</link>, except that instead

of

<link linkend="functions.returning-values">return</link>ing once, a

generator can &yield; as many times as it needs to in order to provide the

values to be iterated over.

Like with iterators, random data access is not possible.

</para>

<para>

A simple example of this is to reimplement the <function>range</function>

function as a generator. The standard <function>range</function> function

has to generate an array with every value in it and return it, which can

result in large arrays: for example, calling

<command>range(0, 1000000)</command> will result in well over 100 MB of

memory being used.

</para>

<para>

As an alternative, we can implement an <literal>xrange()</literal>

generator, which will only ever need enough memory to create an

<classname>Iterator</classname> object and track the current state of the

generator internally, which turns out to be less than 1 kilobyte.

</para>

<example>

<title>Implementing <function>range</function> as a generator</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

<sect2 xml:id="language.generators.object">

<title><classname>Generator</classname> objects</title>

<para>

When a generator function is called, a new 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, and provides methods that can

be called to manipulate the state of the generator, including sending

values to and returning values from it.

</para>

</sect2>

</sect1>

<sect1 xml:id="language.generators.syntax">

<title>Generator syntax</title>

<para>

A generator function looks just like a normal function, except that instead

of returning a value, a generator &yield;s as many values as it needs to.

Any function containing &yield; is a generator function.

</para>

<para>

When a generator function is called, it returns an object that can be

iterated over. When you iterate over that object (for instance, via a

&foreach; loop), PHP will call the object's iteration methods each time it needs a

value, then saves the state of the generator when the generator yields a

value so that it can be resumed when the next value is required.

</para>

<para>

Once there are no more values to be yielded, then the generator

can simply return, and the calling code continues just as if an array has run

out of values.

</para>

<note>

<para>

A generator can return values, which can be retrieved using

<methodname>Generator::getReturn</methodname>.

</para>

</note>

<sect2 xml:id="control-structures.yield">

<title><command>yield</command> keyword</title>

<para>

The heart of a generator function is the <command>yield</command> keyword.

In its simplest form, a yield statement looks much like a return

statement, except that instead of stopping execution of the function and

returning, yield instead provides a value to the code looping over the

generator and pauses execution of the generator function.

</para>

<example>

<title>A simple example of yielding values</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

<note>

<para>

Internally, sequential integer keys will be paired with the yielded

values, just as with a non-associative array.

</para>

</note>

<sect3 xml:id="control-structures.yield.associative">

<title>Yielding values with keys</title>

<para>

PHP also supports associative arrays, and generators are no different. In

addition to yielding simple values, as shown above, you can also yield a

key at the same time.

</para>

<para>

The syntax for yielding a key/value pair is very similar to that used to

define an associative array, as shown below.

</para>

<example>

<title>Yielding a key/value pair</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

</sect3>

<sect3 xml:id="control-structures.yield.null">

<title>Yielding null values</title>

<para>

Yield can be called without an argument to yield a &null; value with an

automatic key.

</para>

<example>

<title>Yielding &null;s</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

</sect3>

<sect3 xml:id="control-structures.yield.references">

<title>Yielding by reference</title>

<para>

Generator functions are able to yield values by reference as well as by

value. This is done in the same way as

<link linkend="functions.returning-values">returning references from functions</link>:

by prepending an ampersand to the function name.

</para>

<example>

<title>Yielding values by reference</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

</sect3>

<sect3 xml:id="control-structures.yield.from">

<title>Generator delegation via <command>yield from</command></title>

<para>

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>

<caution>

<title>Storing into an array (e.g. with <function>iterator_to_array</function>)</title>

<para>

<command>yield from</command> does not reset the keys. It preserves

the keys returned by the <classname>Traversable</classname> object, or

<type>array</type>. Thus some values may share a common key with another

<command>yield</command> or <command>yield from</command>, which, upon

insertion into an array, will overwrite former values with that key.

</para>

<para>

A common case where this matters is <function>iterator_to_array</function>

returning a keyed array by default, leading to possibly unexpected results.

<function>iterator_to_array</function> has a second parameter

<parameter>preserve_keys</parameter> which can be set to &false; to collect

all the values while ignoring the keys returned by the <classname>Generator</classname>.

</para>

<example>

<title><command>yield from</command> with <function>iterator_to_array</function></title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

</caution>

<example>

<title>Basic use of <command>yield from</command></title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

<example>

<title><command>yield from</command> and return values</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

</sect3>

</sect2>

</sect1>

<sect1 xml:id="language.generators.comparison">

<title>Comparing generators with <classname>Iterator</classname> objects</title>

<para>

The primary advantage of generators is their simplicity. Much less

boilerplate code has to be written compared to implementing an

<classname>Iterator</classname> class, and the code is generally much more

readable. For example, the following function and class are equivalent:

</para>

<informalexample>

<programlisting role="php">

</programlisting>

</informalexample>

<para>

This flexibility does come at a cost, however: generators are forward-only

iterators, and cannot be rewound once iteration has started. This also

means that the same generator can't be iterated over multiple times: the

generator will need to be rebuilt by calling the generator function again.

</para>

<simplesect role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><link linkend="language.oop5.iterations">Object Iteration</link></member>

</simplelist>

</para>

</simplesect>

</sect1>

</chapter>