language/types/iterable.xml
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,46 +41,8 @@ function gen(): iterable {
118
41
</programlisting>
119
42
</example>
120
43
</para>
121
-
</sect2>
122
-

123
-
<sect2 xml:id="language.types.iterable.variance">
124
-
<title>Iterable Type Variance</title>
125
-

126
-
<para>
127
-
Classes extending/implementing may broaden methods using &array; or
128
-
<classname>Traversable</classname> as parameter types to
129
-
<type>iterable</type> or narrow return types from <type>iterable</type> to
130
-
&array; or <classname>Traversable</classname>.
131
-
</para>
132
-

133
-
<para>
134
-
<example>
135
-
<title>
136
-
Iterable type variance example
137
-
</title>
138
-
<programlisting role="php">
139
-
<![CDATA[
140
-
<?php
141
-

142
-
interface Example {
143
-
public function method(array $array): iterable;
144
-
}
145
-

146
-
class ExampleImplementation implements Example {
147
-
public function method(iterable $iterable): array {
148
-
// Parameter broadened and return type narrowed.
149
-
}
150
-
}
151
-

152
-
?>
153
-
]]>
154
-
</programlisting>
155
-
</example>
156
-
</para>
157
-
</sect2>
158
-

44
+
</note>
159
45
</sect1>
160
-

161
46
<!-- Keep this comment at the end of the file
162
47
Local variables:
163
48
mode: sgml
164
49