language/generators.xml
08e58ace7e5b538c8ed75d784a54885d5f785d30
08e58ace7e5b538c8ed75d784a54885d5f785d30
...
...
@@ -15,16 +15,17 @@
15
15
</para>
16
16
17
17
<para>
18
-
A generator allows you to write code that uses &foreach; to iterate over a
19
-
set of data without needing to build an array in memory, which may cause
20
-
you to exceed a memory limit, or require a considerable amount of
21
-
processing time to generate. Instead, you can write a generator function,
18
+
A generator offers a convenient way to provide data to &foreach; loops without
19
+
having to build an array in memory ahead of time, which may cause the program
20
+
to exceed a memory limit or require a considerable amount of
21
+
processing time to generate. Instead, a generator function can be used,
22
22
which is the same as a normal
23
23
<link linkend="functions.user-defined">function</link>, except that instead
24
24
of
25
25
<link linkend="functions.returning-values">return</link>ing once, a
26
26
generator can &yield; as many times as it needs to in order to provide the
27
27
values to be iterated over.
28
+
Like with iterators, random data access is not possible.
28
29
</para>
29
30
30
31
<para>
...
...
@@ -127,7 +128,7 @@ Single digit odd numbers from xrange(): 1 3 5 7 9
127
128
128
129
<para>
129
130
Once there are no more values to be yielded, then the generator
130
-
can simply exit, and the calling code continues just as if an array has run
131
+
can simply return, and the calling code continues just as if an array has run
131
132
out of values.
132
133
</para>
133
134
...
...
@@ -185,14 +186,6 @@ foreach ($generator as $value) {
185
186
</para>
186
187
</note>
187
188
188
-
<caution>
189
-
<para>
190
-
The value that will be assigned to <varname>$data</varname> is the value
191
-
passed to <methodname>Generator::send</methodname>, or &null; if
192
-
<methodname>Generator::next</methodname> is called instead.
193
-
</para>
194
-
</caution>
195
-
196
189
<sect3 xml:id="control-structures.yield.associative">
197
190
<title>Yielding values with keys</title>
198
191
...
...
@@ -255,22 +248,6 @@ foreach (input_parser($input) as $id => $fields) {
255
248
]]>
256
249
</screen>
257
250
</example>
258
-
259
-
<caution>
260
-
<para>
261
-
As with the simple value yields shown earlier, yielding a key/value pair
262
-
in an expression context requires the yield statement to be
263
-
parenthesised:
264
-
</para>
265
-
266
-
<informalexample>
267
-
<programlisting role="php">
268
-
<![CDATA[
269
-
$data = (yield $key => $value);
270
-
]]>
271
-
</programlisting>
272
-
</informalexample>
273
-
</caution>
274
251
</sect3>
275
252
276
253
<sect3 xml:id="control-structures.yield.null">
...
...
@@ -388,7 +365,7 @@ foreach (gen_reference() as &$number) {
388
365
A common case where this matters is <function>iterator_to_array</function>
389
366
returning a keyed array by default, leading to possibly unexpected results.
390
367
<function>iterator_to_array</function> has a second parameter
391
-
<parameter>use_keys</parameter> which can be set to &false; to collect
368
+
<parameter>preserve_keys</parameter> which can be set to &false; to collect
392
369
all the values while ignoring the keys returned by the <classname>Generator</classname>.
393
370
</para>
394
371
...
...
@@ -593,6 +570,16 @@ class LineIterator implements Iterator {
593
570
means that the same generator can't be iterated over multiple times: the
594
571
generator will need to be rebuilt by calling the generator function again.
595
572
</para>
573
+
574
+
<simplesect role="seealso">
575
+
&reftitle.seealso;
576
+
<para>
577
+
<simplelist>
578
+
<member><link linkend="language.oop5.iterations">Object Iteration</link></member>
579
+
</simplelist>
580
+
</para>
581
+
</simplesect>
582
+
596
583
</sect1>
597
584
</chapter>
598
585
599
586