reference/array/functions/count.xml
3ef3e56c80f7ae6b6a7291b7eb57dc6250b50801
...
...
@@ -1,43 +1,35 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
+

3
4
<refentry xml:id="function.count" xmlns="http://docbook.org/ns/docbook">
4
5
<refnamediv>
5
6
<refname>count</refname>
6
-
<refpurpose>Count all elements in an array, or something in an object</refpurpose>
7
+
<refpurpose>Counts all elements in an array or in a <interfacename>Countable</interfacename> object</refpurpose>
7
8
</refnamediv>
9
+

8
10
<refsect1 role="description">
9
11
&reftitle.description;
10
12
<methodsynopsis>
11
13
<type>int</type><methodname>count</methodname>
12
-
<methodparam><type>mixed</type><parameter>array_or_countable</parameter></methodparam>
13
-
<methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer>COUNT_NORMAL</initializer></methodparam>
14
+
<methodparam><type class="union"><type>Countable</type><type>array</type></type><parameter>value</parameter></methodparam>
15
+
<methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer><constant>COUNT_NORMAL</constant></initializer></methodparam>
14
16
</methodsynopsis>
15
17
<para>
16
-
Counts all elements in an array, or something in an object.
17
-
</para>
18
-
<para>
19
-
For objects, if you have
20
-
<link linkend="ref.spl">SPL</link> installed, you can hook into
21
-
<function>count</function> by implementing interface
22
-
<classname>Countable</classname>. The interface has exactly one method,
23
-
<methodname>Countable::count</methodname>, which returns the return value for the
24
-
<function>count</function> function.
25
-
</para>
26
-
<para>
27
-
Please see the <link linkend="language.types.array">Array</link>
28
-
section of the manual for a detailed explanation of how arrays
29
-
are implemented and used in PHP.
18
+
Counts all elements in an array when used with an array. When used with an
19
+
object that implements the <interfacename>Countable</interfacename> interface, it returns
20
+
the return value of the method <methodname>Countable::count</methodname>.
30
21
</para>
31
22
</refsect1>
23
+

32
24
<refsect1 role="parameters">
33
25
&reftitle.parameters;
34
26
<para>
35
27
<variablelist>
36
28
<varlistentry>
37
-
<term><parameter>array_or_countable</parameter></term>
29
+
<term><parameter>value</parameter></term>
38
30
<listitem>
39
31
<para>
40
-
An array or <classname>Countable</classname> object.
32
+
An array or <interfacename>Countable</interfacename> object.
41
33
</para>
42
34
</listitem>
43
35
</varlistentry>
...
...
@@ -63,21 +55,53 @@
63
55
</variablelist>
64
56
</para>
65
57
</refsect1>
58
+

66
59
<refsect1 role="returnvalues">
67
60
&reftitle.returnvalues;
68
61
<para>
69
-
Returns the number of elements in <parameter>array_or_countable</parameter>.
70
-
When the parameter is neither an array nor an object with
71
-
implemented <classname>Countable</classname> interface,
72
-
<literal>1</literal> will be returned.
73
-
There is one exception, if <parameter>array_or_countable</parameter> is &null;,
74
-
<literal>0</literal> will be returned.
62
+
Returns the number of elements in <parameter>value</parameter>.
63
+
Prior to PHP 8.0.0, if the parameter was neither an &array; nor an &object; that
64
+
implements the <interfacename>Countable</interfacename> interface,
65
+
<literal>1</literal> would be returned,
66
+
unless <parameter>value</parameter> was &null;, in which case
67
+
<literal>0</literal> would be returned.
75
68
</para>
76
69
</refsect1>
70
+

71
+
<refsect1 role="changelog">
72
+
&reftitle.changelog;
73
+
<informaltable>
74
+
<tgroup cols="2">
75
+
<thead>
76
+
<row>
77
+
<entry>&Version;</entry>
78
+
<entry>&Description;</entry>
79
+
</row>
80
+
</thead>
81
+
<tbody>
82
+
<row>
83
+
<entry>8.0.0</entry>
84
+
<entry>
85
+
<function>count</function> will now throw <classname>TypeError</classname> on
86
+
invalid countable types passed to the <parameter>value</parameter> parameter.
87
+
</entry>
88
+
</row>
89
+
<row>
90
+
<entry>7.2.0</entry>
91
+
<entry>
92
+
<function>count</function> will now yield a warning on invalid countable types
93
+
passed to the <parameter>value</parameter> parameter.
94
+
</entry>
95
+
</row>
96
+
</tbody>
97
+
</tgroup>
98
+
</informaltable>
99
+
</refsect1>
100
+

77
101
<refsect1 role="examples">
78
102
&reftitle.examples;
79
103
<para>
80
-
<example>
104
+
<example xml:id="count.example.basic">
81
105
<title><function>count</function> example</title>
82
106
<programlisting role="php">
83
107
<![CDATA[
...
...
@@ -91,6 +115,28 @@ $b[0] = 7;
91
115
$b[5] = 9;
92
116
$b[10] = 11;
93
117
var_dump(count($b));
118
+
?>
119
+
]]>
120
+
</programlisting>
121
+
&example.outputs;
122
+
<screen role="php">
123
+
<![CDATA[
124
+
int(3)
125
+
int(3)
126
+
]]>
127
+
</screen>
128
+
</example>
129
+
</para>
130
+
<para>
131
+
<example xml:id="count.example.badexample">
132
+
<title><function>count</function> non Countable|array example (bad example - don't do this)</title>
133
+
<programlisting role="php">
134
+
<![CDATA[
135
+
<?php
136
+
$b[0] = 7;
137
+
$b[5] = 9;
138
+
$b[10] = 11;
139
+
var_dump(count($b));
94
140

95
141
var_dump(count(null));
96
142

...
...
@@ -102,19 +148,34 @@ var_dump(count(false));
102
148
<screen role="php">
103
149
<![CDATA[
104
150
int(3)
151
+
int(0)
152
+
int(1)
153
+
]]>
154
+
</screen>
155
+
&example.outputs.72;
156
+
<screen role="php">
157
+
<![CDATA[
105
158
int(3)
106
159

107
-
Warning: count(): Parameter must be an array or an object that implements Countable in … on line 12 // as of PHP 7.2
160
+
Warning: count(): Parameter must be an array or an object that implements Countable in … on line 12
108
161
int(0)
109
162

110
-
Warning: count(): Parameter must be an array or an object that implements Countable in … on line 14 // as of PHP 7.2
163
+
Warning: count(): Parameter must be an array or an object that implements Countable in … on line 14
111
164
int(1)
112
165
]]>
113
166
</screen>
167
+
&example.outputs.8;
168
+
<screen role="php">
169
+
<![CDATA[
170
+
int(3)
171
+

172
+
Fatal error: Uncaught TypeError: count(): Argument #1 ($var) must be of type Countable .. on line 12
173
+
]]>
174
+
</screen>
114
175
</example>
115
176
</para>
116
177
<para>
117
-
<example>
178
+
<example xml:id="count.example.recursive">
118
179
<title>Recursive <function>count</function> example</title>
119
180
<programlisting role="php">
120
181
<![CDATA[
...
...
@@ -123,39 +184,56 @@ $food = array('fruits' => array('orange', 'banana', 'apple'),
123
184
'veggie' => array('carrot', 'collard', 'pea'));
124
185

125
186
// recursive count
126
-
echo count($food, COUNT_RECURSIVE); // output 8
187
+
var_dump(count($food, COUNT_RECURSIVE));
127
188

128
189
// normal count
129
-
echo count($food); // output 2
190
+
var_dump(count($food));
130
191

131
192
?>
132
193
]]>
133
194
</programlisting>
195
+
&example.outputs;
196
+
<screen role="php">
197
+
<![CDATA[
198
+
int(8)
199
+
int(2)
200
+
]]>
201
+
</screen>
202
+
</example>
203
+
</para>
204
+
<para>
205
+
<example xml:id="count.example.countable">
206
+
<title><interfacename>Countable</interfacename> object</title>
207
+
<programlisting role="php">
208
+
<![CDATA[
209
+
<?php
210
+
class CountOfMethods implements Countable
211
+
{
212
+
private function someMethod()
213
+
{
214
+
}
215
+

216
+
public function count(): int
217
+
{
218
+
return count(get_class_methods($this));
219
+
}
220
+
}
221
+

222
+
$obj = new CountOfMethods();
223
+
var_dump(count($obj));
224
+
?>
225
+
]]>
226
+
</programlisting>
227
+
&example.outputs;
228
+
<screen role="php">
229
+
<![CDATA[
230
+
int(2)
231
+
]]>
232
+
</screen>
134
233
</example>
135
234
</para>
136
235
</refsect1>
137
-
<refsect1 role="changelog">
138
-
&reftitle.changelog;
139
-
<informaltable>
140
-
<tgroup cols="2">
141
-
<thead>
142
-
<row>
143
-
<entry>&Version;</entry>
144
-
<entry>&Description;</entry>
145
-
</row>
146
-
</thead>
147
-
<tbody>
148
-
<row>
149
-
<entry>7.2.0</entry>
150
-
<entry>
151
-
<function>count</function> will now yield a warning on invalid countable types
152
-
passed to the <parameter>array_or_countable</parameter> parameter.
153
-
</entry>
154
-
</row>
155
-
</tbody>
156
-
</tgroup>
157
-
</informaltable>
158
-
</refsect1>
236
+

159
237
<refsect1 role="seealso">
160
238
&reftitle.seealso;
161
239
<para>
...
...
@@ -165,9 +243,11 @@ echo count($food); // output 2
165
243
<member><function>empty</function></member>
166
244
<member><function>strlen</function></member>
167
245
<member><function>is_countable</function></member>
246
+
<member><link linkend="language.types.array">Arrays</link></member>
168
247
</simplelist>
169
248
</para>
170
249
</refsect1>
250
+

171
251
</refentry>
172
252

173
253
<!-- Keep this comment at the end of the file
174
254