language/types/iterable.xml
161dde4fe721309398dd324edbf02aec409f127b
161dde4fe721309398dd324edbf02aec409f127b
...
...
@@ -4,107 +4,30 @@
4
4
<title>Iterables</title>
5
5
6
6
<para>
7
-
<type>Iterable</type> is a pseudo-type introduced in PHP 7.1. It accepts any
8
-
&array; or object implementing the <classname>Traversable</classname>
9
-
interface. Both of these types are iterable using &foreach; and can be used
10
-
with <command>yield from</command> within a <link
11
-
linkend="language.generators">generator</link>.
7
+
<type>Iterable</type> is a built-in compile time type alias for
8
+
<!-- Need to improve rendering of free-standing type elements in PhD
9
+
<type class="union"><type>array</type><type>Traversable</type></type>.
10
+
-->
11
+
<literal>array|Traversable</literal>.
12
+
From its introduction in PHP 7.1.0 and prior to PHP 8.2.0,
13
+
<type>iterable</type> was a built-in pseudo-type that acted as the
14
+
aforementioned type alias and can be used as a type declaration.
15
+
An iterable type can be used in &foreach; and with
16
+
<command>yield from</command> within a
17
+
<link linkend="language.generators">generator</link>.
12
18
</para>
13
19
14
-
<sect2 xml:id="language.types.iterable.using">
15
-
<title>Using Iterables</title>
16
-
17
-
<para>
18
-
Iterable can be used as a parameter type to indicate that a function
19
-
requires a set of values, but does not care about the form of the value set
20
-
since it will be used with &foreach;. If a value is not an array or
21
-
instance of <classname>Traversable</classname>, a
22
-
<classname>TypeError</classname> will be thrown.
23
-
</para>
24
-
25
-
<para>
26
-
<example>
27
-
<title>
28
-
Iterable parameter type example
29
-
</title>
30
-
<programlisting role="php">
31
-
<![CDATA[
32
-
<?php
33
-
34
-
function foo(iterable $iterable) {
35
-
foreach ($iterable as $value) {
36
-
// ...
37
-
}
38
-
}
39
-
40
-
?>
41
-
]]>
42
-
</programlisting>
43
-
</example>
44
-
</para>
45
-
46
-
<para>
47
-
Parameters declared as iterable may use &null; or an array as a default
48
-
value.
49
-
</para>
50
-
51
-
<para>
52
-
<example>
53
-
<title>
54
-
Iterable parameter default value example
55
-
</title>
56
-
<programlisting role="php">
57
-
<![CDATA[
58
-
<?php
59
-
60
-
function foo(iterable $iterable = []) {
61
-
// ...
62
-
}
63
-
64
-
?>
65
-
]]>
66
-
</programlisting>
67
-
</example>
68
-
</para>
69
-
70
-
<para>
71
-
Iterable can also be used as a return type to indicate a function will
72
-
return an iterable value. If the returned value is not an array or instance
73
-
of <classname>Traversable</classname>, a <classname>TypeError</classname>
74
-
will be thrown.
75
-
</para>
76
-
77
-
<para>
78
-
<example>
79
-
<title>
80
-
Iterable return type example
81
-
</title>
82
-
<programlisting role="php">
83
-
<![CDATA[
84
-
<?php
85
-
86
-
function bar(): iterable {
87
-
return [1, 2, 3];
88
-
}
89
-
90
-
?>
91
-
]]>
92
-
</programlisting>
93
-
</example>
94
-
</para>
95
-
20
+
<note>
96
21
<para>
97
22
Functions declaring iterable as a return type may also be <link
98
23
linkend="language.generators">generators</link>.
99
-
</para>
100
24
101
-
<para>
102
25
<example>
103
26
<title>
104
27
Iterable generator return type example
105
28
</title>
106
29
<programlisting role="php">
107
-
<![CDATA[
30
+
<![CDATA[
108
31
<?php
109
32
110
33
function gen(): iterable {
...
...
@@ -118,10 +41,8 @@ function gen(): iterable {
118
41
</programlisting>
119
42
</example>
120
43
</para>
121
-
</sect2>
122
-
44
+
</note>
123
45
</sect1>
124
-
125
46
<!-- Keep this comment at the end of the file
126
47
Local variables:
127
48
mode: sgml
128
49