[prev in list] [next in list] [prev in thread] [next in thread]
List: php-doc-cvs
Subject: [DOC-CVS] [doc-en] master: Update array sorting docs
From: George Peter Banyard via Peter Cowburn <noreply () php ! net>
Date: 2021-08-19 14:46:17
Message-ID: JiMrAW8GdcJjf1KVjBpk6MfhIupH66xP4PhIqssdQ () main ! php ! net
[Download RAW message or body]
Author: George Peter Banyard (Girgias)
Committer: Peter Cowburn (salathe)
Date: 2021-08-19T15:46:00+01:00
Commit: https://github.com/php/doc-en/commit/d1df62fe77b6cb0676d064e8e63ee2c3304d4260
Raw diff: https://github.com/php/doc-en/commit/d1df62fe77b6cb0676d064e8e63ee2c3304d4260.diff
Update array sorting docs
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
Changed paths:
M language-snippets.ent
M reference/array/functions/arsort.xml
M reference/array/functions/asort.xml
M reference/array/functions/krsort.xml
M reference/array/functions/ksort.xml
M reference/array/functions/rsort.xml
M reference/array/functions/sort.xml
M reference/array/functions/uasort.xml
M reference/array/functions/uksort.xml
M reference/array/functions/usort.xml
M reference/array/sorting.xml
Diff:
diff --git a/language-snippets.ent b/language-snippets.ent
index 35cce33da2..41f992f098 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -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
diff --git a/reference/array/functions/arsort.xml \
b/reference/array/functions/arsort.xml index edd9e4b60b..98a133bae2 100644
--- a/reference/array/functions/arsort.xml
+++ b/reference/array/functions/arsort.xml
@@ -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:
diff --git a/reference/array/functions/asort.xml \
b/reference/array/functions/asort.xml index ec595933e8..030de99feb 100644
--- a/reference/array/functions/asort.xml
+++ b/reference/array/functions/asort.xml
@@ -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>
¬e.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:
diff --git a/reference/array/functions/krsort.xml \
b/reference/array/functions/krsort.xml index 7c9460205f..81dc33a334 100644
--- a/reference/array/functions/krsort.xml
+++ b/reference/array/functions/krsort.xml
@@ -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>
+ ¬e.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:
diff --git a/reference/array/functions/ksort.xml \
b/reference/array/functions/ksort.xml index 1e2c3d729a..77ecffb6da 100644
--- a/reference/array/functions/ksort.xml
+++ b/reference/array/functions/ksort.xml
@@ -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>
+ ¬e.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>
@@ -62,20 +66,58 @@ a = orange
b = banana
c = apple
d = lemon
+]]>
+ </screen>
+ </example>
+ </para>
+
+ <para>
+ <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;
- <para>
- <simplelist>
- <member><function>asort</function></member>
- <member>&seealso.array.sorting;</member>
- </simplelist>
- </para>
+ <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:
diff --git a/reference/array/functions/rsort.xml \
b/reference/array/functions/rsort.xml index 8227957645..613cda1f38 100644
--- a/reference/array/functions/rsort.xml
+++ b/reference/array/functions/rsort.xml
@@ -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>
¬e.sort-unstable;
+ ¬e.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;
- ¬e.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:
diff --git a/reference/array/functions/sort.xml b/reference/array/functions/sort.xml
index 3dd45d10e2..a400135449 100644
--- a/reference/array/functions/sort.xml
+++ b/reference/array/functions/sort.xml
@@ -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>
¬e.sort-unstable;
+ ¬e.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;
- ¬e.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:
diff --git a/reference/array/functions/uasort.xml \
b/reference/array/functions/uasort.xml index abcebea784..f04c697282 100644
--- a/reference/array/functions/uasort.xml
+++ b/reference/array/functions/uasort.xml
@@ -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:
diff --git a/reference/array/functions/uksort.xml \
b/reference/array/functions/uksort.xml index 22733a9908..ef964532e8 100644
--- a/reference/array/functions/uksort.xml
+++ b/reference/array/functions/uksort.xml
@@ -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>
¬e.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:
diff --git a/reference/array/functions/usort.xml \
b/reference/array/functions/usort.xml index 808ba9459e..ce3d33a56f 100644
--- a/reference/array/functions/usort.xml
+++ b/reference/array/functions/usort.xml
@@ -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>
¬e.sort-unstable;
¬e.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:
diff --git a/reference/array/sorting.xml b/reference/array/sorting.xml
index 3eb402c39f..7090c681d9 100644
--- a/reference/array/sorting.xml
+++ b/reference/array/sorting.xml
@@ -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>
--
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic