language/generators.xml
5f2da51e3cc91d9459ecd064203afb8cac3ac5cc
...
...
@@ -49,9 +49,9 @@
49
49
<![CDATA[
50
50
<?php
51
51
function xrange($start, $limit, $step = 1) {
52
-
if ($start < $limit) {
52
+
if ($start <= $limit) {
53
53
if ($step <= 0) {
54
-
throw new LogicException('Step must be +ve');
54
+
throw new LogicException('Step must be positive');
55
55
}
56
56

57
57
for ($i = $start; $i <= $limit; $i += $step) {
...
...
@@ -59,7 +59,7 @@ function xrange($start, $limit, $step = 1) {
59
59
}
60
60
} else {
61
61
if ($step >= 0) {
62
-
throw new LogicException('Step must be -ve');
62
+
throw new LogicException('Step must be negative');
63
63
}
64
64

65
65
for ($i = $start; $i >= $limit; $i += $step) {
...
...
@@ -98,7 +98,7 @@ Single digit odd numbers from xrange(): 1 3 5 7 9
98
98
<sect2 xml:id="language.generators.object">
99
99
<title><classname>Generator</classname> objects</title>
100
100
<para>
101
-
When a generator function is called for the first time, an object of the
101
+
When a generator function is called, a new object of the
102
102
internal <classname>Generator</classname> class is returned. This object
103
103
implements the <classname>Iterator</classname> interface in much the same
104
104
way as a forward-only iterator object would, and provides methods that can
...
...
@@ -114,27 +114,27 @@ Single digit odd numbers from xrange(): 1 3 5 7 9
114
114
<para>
115
115
A generator function looks just like a normal function, except that instead
116
116
of returning a value, a generator &yield;s as many values as it needs to.
117
+
Any function containing &yield; is a generator function.
117
118
</para>
118
119

119
120
<para>
120
121
When a generator function is called, it returns an object that can be
121
122
iterated over. When you iterate over that object (for instance, via a
122
-
&foreach; loop), PHP will call the generator function each time it needs a
123
+
&foreach; loop), PHP will call the object's iteration methods each time it needs a
123
124
value, then saves the state of the generator when the generator yields a
124
125
value so that it can be resumed when the next value is required.
125
126
</para>
126
127

127
128
<para>
128
-
Once there are no more values to be yielded, then the generator function
129
+
Once there are no more values to be yielded, then the generator
129
130
can simply exit, and the calling code continues just as if an array has run
130
131
out of values.
131
132
</para>
132
133

133
134
<note>
134
135
<para>
135
-
A generator cannot return a value: doing so will result in a compile
136
-
error. An empty <command>return</command> statement is valid syntax within
137
-
a generator and it will terminate the generator.
136
+
A generator can return values, which can be retrieved using
137
+
<methodname>Generator::getReturn</methodname>.
138
138
</para>
139
139
</note>
140
140

...
...
@@ -185,43 +185,6 @@ foreach ($generator as $value) {
185
185
</para>
186
186
</note>
187
187

188
-
<caution>
189
-
<para>
190
-
If you use yield in an expression context (for example, on the right hand
191
-
side of an assignment), you must surround the yield statement with
192
-
parentheses in PHP 5. For example, this is valid:
193
-
</para>
194
-

195
-
<informalexample>
196
-
<programlisting role="php">
197
-
<![CDATA[
198
-
$data = (yield $value);
199
-
]]>
200
-
</programlisting>
201
-
</informalexample>
202
-

203
-
<para>
204
-
But this is not, and will result in a parse error in PHP 5:
205
-
</para>
206
-

207
-
<informalexample>
208
-
<programlisting role="php">
209
-
<![CDATA[
210
-
$data = yield $value;
211
-
]]>
212
-
</programlisting>
213
-
</informalexample>
214
-

215
-
<para>
216
-
The parenthetical restrictions do not apply in PHP 7.
217
-
</para>
218
-

219
-
<para>
220
-
This syntax may be used in conjunction with the
221
-
<methodname>Generator::send</methodname> method.
222
-
</para>
223
-
</caution>
224
-

225
188
<sect3 xml:id="control-structures.yield.associative">
226
189
<title>Yielding values with keys</title>
227
190

...
...
@@ -284,22 +247,6 @@ foreach (input_parser($input) as $id => $fields) {
284
247
]]>
285
248
</screen>
286
249
</example>
287
-

288
-
<caution>
289
-
<para>
290
-
As with the simple value yields shown earlier, yielding a key/value pair
291
-
in an expression context requires the yield statement to be
292
-
parenthesised:
293
-
</para>
294
-

295
-
<informalexample>
296
-
<programlisting role="php">
297
-
<![CDATA[
298
-
$data = (yield $key => $value);
299
-
]]>
300
-
</programlisting>
301
-
</informalexample>
302
-
</caution>
303
250
</sect3>
304
251

305
252
<sect3 xml:id="control-structures.yield.null">
...
...
@@ -388,7 +335,7 @@ foreach (gen_reference() as &$number) {
388
335
<title>Generator delegation via <command>yield from</command></title>
389
336

390
337
<para>
391
-
In PHP 7, generator delegation allows you to yield values from another
338
+
Generator delegation allows you to yield values from another
392
339
generator, <classname>Traversable</classname> object, or
393
340
<type>array</type> by using the <command>yield from</command> keyword.
394
341
The outer generator will then yield all values from the inner generator,
...
...
@@ -417,7 +364,7 @@ foreach (gen_reference() as &$number) {
417
364
A common case where this matters is <function>iterator_to_array</function>
418
365
returning a keyed array by default, leading to possibly unexpected results.
419
366
<function>iterator_to_array</function> has a second parameter
420
-
<parameter>use_keys</parameter> which can be set to &false; to collect
367
+
<parameter>preserve_keys</parameter> which can be set to &false; to collect
421
368
all the values while ignoring the keys returned by the <classname>Generator</classname>.
422
369
</para>
423
370

...
...
@@ -426,14 +373,14 @@ foreach (gen_reference() as &$number) {
426
373
<programlisting role="php">
427
374
<![CDATA[
428
375
<?php
429
-
function from() {
376
+
function inner() {
430
377
yield 1; // key 0
431
378
yield 2; // key 1
432
379
yield 3; // key 2
433
380
}
434
381
function gen() {
435
382
yield 0; // key 0
436
-
yield from from(); // keys 0-2
383
+
yield from inner(); // keys 0-2
437
384
yield 4; // key 1
438
385
}
439
386
// pass false as second parameter to get an array [0, 1, 2, 3, 4]
...
...
@@ -622,6 +569,16 @@ class LineIterator implements Iterator {
622
569
means that the same generator can't be iterated over multiple times: the
623
570
generator will need to be rebuilt by calling the generator function again.
624
571
</para>
572
+

573
+
<simplesect role="seealso">
574
+
&reftitle.seealso;
575
+
<para>
576
+
<simplelist>
577
+
<member><link linkend="language.oop5.iterations">Object Iteration</link></member>
578
+
</simplelist>
579
+
</para>
580
+
</simplesect>
581
+

625
582
</sect1>
626
583
</chapter>
627
584

628
585