reference/array/functions/usort.xml
2226ad08fd93e3979efbba47c5ae3545eec97d25
...
...
@@ -8,18 +8,18 @@
8
8
<refsect1 role="description">
9
9
&reftitle.description;
10
10
<methodsynopsis>
11
-
<type>bool</type><methodname>usort</methodname>
11
+
<type>true</type><methodname>usort</methodname>
12
12
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
13
13
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
14
14
</methodsynopsis>
15
15
<para>
16
-
This function will sort an array by its values using a user-supplied
17
-
comparison function. If the array you wish to sort needs to be sorted by
18
-
some non-trivial criteria, you should use this function.
16
+
Sorts <parameter>array</parameter> in place by values using a
17
+
user-supplied comparison function to determine the order.
19
18
</para>
20
19
&note.sort-unstable;
21
20
&note.no-key-association;
22
21
</refsect1>
22
+

23
23
<refsect1 role="parameters">
24
24
&reftitle.parameters;
25
25
<para>
...
...
@@ -35,30 +35,38 @@
35
35
<varlistentry>
36
36
<term><parameter>callback</parameter></term>
37
37
<listitem>
38
-
<para>
39
-
&return.callbacksort;
40
-
</para>
41
-
&callback.cmp;
42
-
<caution>
43
-
<para>
44
-
Returning <emphasis>non-integer</emphasis> values from the comparison
45
-
function, such as <type>float</type>, will result in an internal cast to
46
-
<type>int</type> of the callback's return value. So values such as
47
-
0.99 and 0.1 will both be cast to an integer value of 0, which will
48
-
compare such values as equal.
49
-
</para>
50
-
</caution>
38
+
&sort.callback.description;
51
39
</listitem>
52
40
</varlistentry>
53
41
</variablelist>
54
42
</para>
55
43
</refsect1>
44
+

56
45
<refsect1 role="returnvalues">
57
46
&reftitle.returnvalues;
58
47
<para>
59
-
&return.success;
48
+
&return.true.always;
60
49
</para>
61
50
</refsect1>
51
+

52
+
<refsect1 role="changelog">
53
+
&reftitle.changelog;
54
+
<informaltable>
55
+
<tgroup cols="2">
56
+
<thead>
57
+
<row>
58
+
<entry>&Version;</entry>
59
+
<entry>&Description;</entry>
60
+
</row>
61
+
</thead>
62
+
<tbody>
63
+
&return.type.true;
64
+
&array.changelog.by-ref;
65
+
</tbody>
66
+
</tgroup>
67
+
</informaltable>
68
+
</refsect1>
69
+

62
70
<refsect1 role="examples">
63
71
&reftitle.examples;
64
72
<para>
...
...
@@ -95,6 +103,28 @@ foreach ($a as $key => $value) {
95
103
4: 6
96
104
]]>
97
105
</screen>
106
+
<para>
107
+
The spaceship operator may be used to
108
+
simplify the internal comparison even further.
109
+
</para>
110
+
<programlisting role="php">
111
+
<![CDATA[
112
+
<?php
113
+
function cmp($a, $b)
114
+
{
115
+
return $a <=> $b;
116
+
}
117
+

118
+
$a = array(3, 2, 5, 6, 1);
119
+

120
+
usort($a, "cmp");
121
+

122
+
foreach ($a as $key => $value) {
123
+
echo "$key: $value\n";
124
+
}
125
+
?>
126
+
]]>
127
+
</programlisting>
98
128
</example>
99
129
</para>
100
130
<note>
...
...
@@ -122,7 +152,7 @@ $fruits[2]["fruit"] = "grapes";
122
152

123
153
usort($fruits, "cmp");
124
154

125
-
while (list($key, $value) = each($fruits)) {
155
+
foreach ($fruits as $key => $value) {
126
156
echo "\$fruits[$key]: " . $value["fruit"] . "\n";
127
157
}
128
158
?>
...
...
@@ -151,9 +181,9 @@ $fruits[2]: lemons
151
181
<![CDATA[
152
182
<?php
153
183
class TestObj {
154
-
var $name;
184
+
private string $name;
155
185

156
-
function TestObj($name)
186
+
function __construct($name)
157
187
{
158
188
$this->name = $name;
159
189
}
...
...
@@ -161,12 +191,7 @@ class TestObj {
161
191
/* This is the static comparing function: */
162
192
static function cmp_obj($a, $b)
163
193
{
164
-
$al = strtolower($a->name);
165
-
$bl = strtolower($b->name);
166
-
if ($al == $bl) {
167
-
return 0;
168
-
}
169
-
return ($al > $bl) ? +1 : -1;
194
+
return strtolower($a->name) <=> strtolower($b->name);
170
195
}
171
196
}
172
197

...
...
@@ -174,7 +199,7 @@ $a[] = new TestObj("c");
174
199
$a[] = new TestObj("b");
175
200
$a[] = new TestObj("d");
176
201

177
-
usort($a, array("TestObj", "cmp_obj"));
202
+
usort($a, [TestObj::class, "cmp_obj"]);
178
203

179
204
foreach ($a as $item) {
180
205
echo $item->name . "\n";
...
...
@@ -226,17 +251,56 @@ z, c
226
251
]]>
227
252
</screen>
228
253
</example>
254
+
<example xml:id="function.usort.examples.multiple-axes">
255
+
<title>
256
+
<function>usort</function> example using the spaceship operator
257
+
</title>
258
+
<para>
259
+
The spaceship operator allows for straightforward comparison of
260
+
compound values across multiple axes. The following example will sort
261
+
<literal>$people</literal> by last name, then by first name if the
262
+
last name matches.
263
+
</para>
264
+
<programlisting role="php">
265
+
<![CDATA[
266
+
<?php
267
+
$people[0] = ['first' => 'Adam', 'last' => 'West'];
268
+
$people[1] = ['first' => 'Alec', 'last' => 'Baldwin'];
269
+
$people[2] = ['first' => 'Adam', 'last' => 'Baldwin'];
270
+

271
+
function sorter(array $a, array $b) {
272
+
return [$a['last'], $a['first']] <=> [$b['last'], $b['first']];
273
+
}
274
+

275
+
usort($people, 'sorter');
276
+

277
+
foreach ($people as $person) {
278
+
print $person['last'] . ', ' . $person['first'] . PHP_EOL;
279
+
}
280
+
?>
281
+
]]>
282
+
</programlisting>
283
+
&example.outputs;
284
+
<screen>
285
+
<![CDATA[
286
+
Baldwin, Adam
287
+
Baldwin, Alec
288
+
West, Adam
289
+
]]>
290
+
</screen>
291
+
</example>
229
292
</para>
230
293
</refsect1>
294
+

231
295
<refsect1 role="seealso">
232
296
&reftitle.seealso;
233
-
<para>
234
-
<simplelist>
235
-
<member><function>uasort</function></member>
236
-
<member>&seealso.array.sorting;</member>
237
-
</simplelist>
238
-
</para>
297
+
<simplelist>
298
+
<member><function>uasort</function></member>
299
+
<member><function>uksort</function></member>
300
+
<member>&seealso.array.sorting;</member>
301
+
</simplelist>
239
302
</refsect1>
303
+

240
304
</refentry>
241
305
<!-- Keep this comment at the end of the file
242
306
Local variables:
243
307



Tools (Chinese (Simplified) Manual)