reference/array/functions/count.xml
2e60c5134e7a847c99f81eb3f7ecee1f5efeeace
...
...
@@ -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[
...
...
@@ -87,6 +111,28 @@ $a[1] = 3;
87
111
$a[2] = 5;
88
112
var_dump(count($a));
89
113

114
+
$b[0] = 7;
115
+
$b[5] = 9;
116
+
$b[10] = 11;
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" annotations="non-interactive">
134
+
<![CDATA[
135
+
<?php
90
136
$b[0] = 7;
91
137
$b[5] = 9;
92
138
$b[10] = 11;
...
...
@@ -102,19 +148,14 @@ var_dump(count(false));
102
148
<screen role="php">
103
149
<![CDATA[
104
150
int(3)
105
-
int(3)
106
-

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

110
-
Warning: count(): Parameter must be an array or an object that implements Countable in … on line 14 // as of PHP 7.2
111
-
int(1)
152
+
Fatal error: Uncaught TypeError: count(): Argument #1 ($var) must be of type Countable .. on line 12
112
153
]]>
113
154
</screen>
114
155
</example>
115
156
</para>
116
157
<para>
117
-
<example>
158
+
<example xml:id="count.example.recursive">
118
159
<title>Recursive <function>count</function> example</title>
119
160
<programlisting role="php">
120
161
<![CDATA[
...
...
@@ -123,39 +164,56 @@ $food = array('fruits' => array('orange', 'banana', 'apple'),
123
164
'veggie' => array('carrot', 'collard', 'pea'));
124
165

125
166
// recursive count
126
-
echo count($food, COUNT_RECURSIVE); // output 8
167
+
var_dump(count($food, COUNT_RECURSIVE));
127
168

128
169
// normal count
129
-
echo count($food); // output 2
170
+
var_dump(count($food));
130
171

131
172
?>
132
173
]]>
133
174
</programlisting>
175
+
&example.outputs;
176
+
<screen role="php">
177
+
<![CDATA[
178
+
int(8)
179
+
int(2)
180
+
]]>
181
+
</screen>
182
+
</example>
183
+
</para>
184
+
<para>
185
+
<example xml:id="count.example.countable">
186
+
<title><interfacename>Countable</interfacename> object</title>
187
+
<programlisting role="php">
188
+
<![CDATA[
189
+
<?php
190
+
class CountOfMethods implements Countable
191
+
{
192
+
private function someMethod()
193
+
{
194
+
}
195
+

196
+
public function count(): int
197
+
{
198
+
return count(get_class_methods($this));
199
+
}
200
+
}
201
+

202
+
$obj = new CountOfMethods();
203
+
var_dump(count($obj));
204
+
?>
205
+
]]>
206
+
</programlisting>
207
+
&example.outputs;
208
+
<screen role="php">
209
+
<![CDATA[
210
+
int(2)
211
+
]]>
212
+
</screen>
134
213
</example>
135
214
</para>
136
215
</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>
216
+

159
217
<refsect1 role="seealso">
160
218
&reftitle.seealso;
161
219
<para>
...
...
@@ -165,9 +223,11 @@ echo count($food); // output 2
165
223
<member><function>empty</function></member>
166
224
<member><function>strlen</function></member>
167
225
<member><function>is_countable</function></member>
226
+
<member><link linkend="language.types.array">Arrays</link></member>
168
227
</simplelist>
169
228
</para>
170
229
</refsect1>
230
+

171
231
</refentry>
172
232

173
233
<!-- Keep this comment at the end of the file
174
234



Translation status