php/archived-doc-en
1
0
Fork 0
mirror of https://github.com/php/doc-en.git synced 2026-03-23 23:32:18 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update array sorting docs

Browse Source 
These always return true, even in PHP 7
Clarify sorting is unstable prior to PHP 8.0
Normalize the docs between the functions

Closes GH-686
This commit is contained in:
George Peter Banyard
2021-06-13 16:41:24 +01:00
committed by Peter Cowburn
parent ebb0c383f4
commit d1df62fe77
11 changed files with 178 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
language-snippets.ent
View File

@@ -137,7 +137,8 @@ from one file system to another.</para></note>'>
<!ENTITY note.sort-unstable '<note xmlns="http://docbook.org/ns/docbook">
<para>
If two members compare as equal, they retain their original order. Prior to PHP 8.0.0, their relative order in the sorted array was undefined.
If two members compare as equal, they retain their original order.
Prior to PHP 8.0.0, their relative order in the sorted array was undefined.
</para>
</note>
'>
@@ -651,6 +652,8 @@ searched for within the <link xmlns="http://docbook.org/ns/docbook" linkend="ini
<!ENTITY return.void 'No value is returned.'>
<!ENTITY return.true.always 'Always returns &true;.'>
<!ENTITY return.callbacksort 'The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.'>
<!ENTITY return.falseproblem '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function may

22
reference/array/functions/arsort.xml
View File

@@ -13,8 +13,9 @@
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>SORT_REGULAR</constant></initializer></methodparam>
</methodsynopsis>
<para>
This function sorts an array in descending order such that array indices maintain their
correlation with the array elements they are associated with.
Sorts <parameter>array</parameter> in place in descending order,
such that its keys maintain their correlation with the values they
are associated with.
</para>
<para>
This is used mainly when sorting associative arrays where the actual
@@ -38,12 +39,14 @@
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
&return.true.always;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
@@ -76,15 +79,16 @@ c = apple
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>asort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</para>
<simplelist>
<member><function>sort</function></member>
<member><function>asort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

29
reference/array/functions/asort.xml
View File

@@ -13,13 +13,17 @@
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>SORT_REGULAR</constant></initializer></methodparam>
</methodsynopsis>
<para>
This function sorts an array in ascending order such that array indices maintain
their correlation with the array elements they are associated
with. This is used mainly when sorting associative arrays where
the actual element order is significant.
Sorts <parameter>array</parameter> in place in ascending order,
such that its keys maintain their correlation with the values they
are associated with.
</para>
<para>
This is used mainly when sorting associative arrays where the actual
element order is significant.
</para>
&note.sort-unstable;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
@@ -36,12 +40,14 @@
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Always returns &true;.
&return.true.always;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
@@ -74,15 +80,16 @@ a = orange
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>arsort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</para>
<simplelist>
<member><function>sort</function></member>
<member><function>arsort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

24
reference/array/functions/krsort.xml
View File

@@ -13,10 +13,12 @@
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>SORT_REGULAR</constant></initializer></methodparam>
</methodsynopsis>
<para>
Sorts an array by key in descending order, maintaining key to data
correlations. This is useful mainly for associative arrays.
Sorts <parameter>array</parameter> in place by keys
in descending order.
</para>
&note.sort-unstable;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
@@ -33,12 +35,14 @@
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
&return.true.always;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
@@ -67,16 +71,16 @@ a = orange
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>arsort</function></member>
<member><function>ksort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</para>
<simplelist>
<member><function>sort</function></member>
<member><function>ksort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

62
reference/array/functions/ksort.xml
View File

@@ -13,10 +13,12 @@
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>SORT_REGULAR</constant></initializer></methodparam>
</methodsynopsis>
<para>
Sorts an array by key in ascending order, maintaining key to data correlations. This is
useful mainly for associative arrays.
Sorts <parameter>array</parameter> in place by keys
in ascending order.
</para>
&note.sort-unstable;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
@@ -33,12 +35,14 @@
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Always returns &true;.
&return.true.always;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
@@ -66,16 +70,54 @@ d = lemon
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>asort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
<example>
<title><function>ksort</function> with <type>int</type> keys</title>
<programlisting role="php">
<![CDATA[
<?php
$a = [0 => 'First', 2 => 'Last', 1 => 'Middle'];
var_dump($a);
ksort($a);
var_dump($a);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(3) {
[0]=>
string(5) "First"
[2]=>
string(4) "Last"
[1]=>
string(6) "Middle"
}
array(3) {
[0]=>
string(5) "First"
[1]=>
string(6) "Middle"
[2]=>
string(4) "Last"
}
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>sort</function></member>
<member><function>krsort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

28
reference/array/functions/rsort.xml
View File

@@ -13,10 +13,13 @@
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>SORT_REGULAR</constant></initializer></methodparam>
</methodsynopsis>
<para>
This function sorts an array by value in descending order.
Sorts <parameter>array</parameter> in place by values
in descending order.
</para>
&note.sort-unstable;
&note.no-key-association;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
@@ -33,12 +36,14 @@
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
&return.true.always;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
@@ -70,20 +75,17 @@ foreach ($fruits as $key => $val) {
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
&note.no-key-association;
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>arsort</function></member>
<member><function>krsort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</para>
<simplelist>
<member><function>sort</function></member>
<member><function>arsort</function></member>
<member><function>krsort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

24
reference/array/functions/sort.xml
View File

@@ -13,10 +13,13 @@
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>SORT_REGULAR</constant></initializer></methodparam>
</methodsynopsis>
<para>
This function sorts an array by value in ascending order.
Sorts <parameter>array</parameter> in place by values
in ascending order.
</para>
&note.sort-unstable;
&note.no-key-association;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
@@ -33,12 +36,14 @@
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
&return.true.always;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
@@ -105,9 +110,9 @@ fruits[3] = orange20
The fruits have been sorted like <function>natcasesort</function>.
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
&note.no-key-association;
<note>
<simpara>
Like most PHP sorting functions, <function>sort</function> uses an
@@ -126,16 +131,15 @@ fruits[3] = orange20
</simpara>
</warning>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>asort</function></member>
<member><function>rsort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</para>
<simplelist>
<member><function>rsort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

24
reference/array/functions/uasort.xml
View File

@@ -14,9 +14,9 @@
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
This function sorts an array such that array indices maintain their
correlation with the array elements they are associated with, using a
user-defined comparison function.
Sorts <parameter>array</parameter> in place such that its keys
maintain their correlation with the values they are associated with,
using a user-defined comparison function.
</para>
<para>
This is used mainly when sorting associative arrays where the actual
@@ -41,9 +41,9 @@
<term><parameter>callback</parameter></term>
<listitem>
<para>
See <function>usort</function> and <function>uksort</function> for
examples of user-defined comparison functions.
&return.callbacksort;
</para>
&callback.cmp;
</listitem>
</varlistentry>
</variablelist>
@@ -53,7 +53,7 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
&return.true.always;
</para>
</refsect1>
@@ -116,13 +116,13 @@ Array
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>usort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</para>
<simplelist>
<member><function>usort</function></member>
<member><function>uksort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

24
reference/array/functions/uksort.xml
View File

@@ -13,13 +13,12 @@
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
<function>uksort</function> will sort the keys of an array using a
user-supplied comparison function. If the array you wish to sort
needs to be sorted by some non-trivial criteria, you should use
this function.
Sorts <parameter>array</parameter> in place by keys using a
user-supplied comparison function to determine the order.
</para>
&note.sort-unstable;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
@@ -44,12 +43,14 @@
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
&return.true.always;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
@@ -87,15 +88,16 @@ John: 1
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>usort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</para>
<simplelist>
<member><function>usort</function></member>
<member><function>uasort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

32
reference/array/functions/usort.xml
View File

@@ -13,13 +13,13 @@
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
This function will sort an array by its values using a user-supplied
comparison function. If the array you wish to sort needs to be sorted by
some non-trivial criteria, you should use this function.
Sorts <parameter>array</parameter> in place by values using a
user-supplied comparison function to determine the order.
</para>
&note.sort-unstable;
&note.no-key-association;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
@@ -39,26 +39,19 @@
&return.callbacksort;
</para>
&callback.cmp;
<caution>
<para>
Returning <emphasis>non-integer</emphasis> values from the comparison
function, such as <type>float</type>, will result in an internal cast to
<type>int</type> of the callback's return value. So values such as
0.99 and 0.1 will both be cast to an integer value of 0, which will
compare such values as equal.
</para>
</caution>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
&return.true.always;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
@@ -228,15 +221,16 @@ z, c
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>uasort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</para>
<simplelist>
<member><function>uasort</function></member>
<member><function>uksort</function></member>
<member>&seealso.array.sorting;</member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

20
reference/array/sorting.xml
View File

@@ -22,8 +22,8 @@
numerically (0,1,2 ...)
</member>
<member>
The order of the sort: alphabetical, low to high (ascending),
high to low (descending), numerical, natural, random, or user defined
The order of the sort: alphabetical, ascending (low to high),
descending (high to low), natural, random, or user defined
</member>
<member>
Note: All of these sort functions act directly on the array
@@ -53,7 +53,7 @@
<row>
<entry><function>array_multisort</function></entry>
<entry>value</entry>
<entry>associative yes, numeric no</entry>
<entry><type>string</type> keys yes, <type>int</type> keys no</entry>
<entry>first array or sort options</entry>
<entry><function>array_walk</function></entry>
</row>
@@ -61,29 +61,29 @@
<entry><function>asort</function></entry>
<entry>value</entry>
<entry>yes</entry>
<entry>low to high</entry>
<entry>ascending</entry>
<entry><function>arsort</function></entry>
</row>
<row>
<entry><function>arsort</function></entry>
<entry>value</entry>
<entry>yes</entry>
<entry>high to low</entry>
<entry>descending</entry>
<entry><function>asort</function></entry>
</row>
<row>
<entry><function>krsort</function></entry>
<entry>key</entry>
<entry>yes</entry>
<entry>high to low</entry>
<entry>descending</entry>
<entry><function>ksort</function></entry>
</row>
<row>
<entry><function>ksort</function></entry>
<entry>key</entry>
<entry>yes</entry>
<entry>low to high</entry>
<entry><function>asort</function></entry>
<entry>ascending</entry>
<entry><function>krsort</function></entry>
</row>
<row>
<entry><function>natcasesort</function></entry>
@@ -103,7 +103,7 @@
<entry><function>rsort</function></entry>
<entry>value</entry>
<entry>no</entry>
<entry>high to low</entry>
<entry>descending</entry>
<entry><function>sort</function></entry>
</row>
<row>
@@ -117,7 +117,7 @@
<entry><function>sort</function></entry>
<entry>value</entry>
<entry>no</entry>
<entry>low to high</entry>
<entry>ascending</entry>
<entry><function>rsort</function></entry>
</row>
<row>