From 7fc85ba263105ddde601163ffdf6f2e297356867 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Sun, 13 Jun 2021 16:41:24 +0100
Subject: [PATCH] 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
---
 language-snippets.ent                |  5 ++-
 reference/array/functions/arsort.xml | 22 +++++-----
 reference/array/functions/asort.xml  | 29 +++++++++-----
 reference/array/functions/krsort.xml | 24 ++++++-----
 reference/array/functions/ksort.xml  | 60 +++++++++++++++++++++++-----
 reference/array/functions/rsort.xml  | 28 +++++++------
 reference/array/functions/sort.xml   | 24 ++++++-----
 reference/array/functions/uasort.xml | 24 +++++------
 reference/array/functions/uksort.xml | 24 ++++++-----
 reference/array/functions/usort.xml  | 32 ++++++---------
 reference/array/sorting.xml          | 25 ++++++------
 11 files changed, 180 insertions(+), 117 deletions(-)

diff --git a/language-snippets.ent b/language-snippets.ent
index 5240b8853844..305a7609f469 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, their relative order in the sorted array is undefined.
+  Prior to PHP 8.0.0, if two members compare as equal,
+  their relative order in the sorted array is undefined.
  </para>
 </note>
 '>
@@ -657,6 +658,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 edd9e4b60bdd..98a133bae2e2 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 4dc47b979dfb..030de99febd0 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>
   &note.sort-unstable;
  </refsect1>
+
  <refsect1 role="parameters">
   &reftitle.parameters;
   <para>
@@ -36,12 +40,14 @@
    </variablelist>
   </para>
  </refsect1>
+
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   &return.success;
+   &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 7c9460205f95..81dc33a33406 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>
+  &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:
diff --git a/reference/array/functions/ksort.xml b/reference/array/functions/ksort.xml
index 0ea17279338d..77ecffb6da88 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>
+  &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>
@@ -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 822795764521..613cda1f38cb 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>
   &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:
diff --git a/reference/array/functions/sort.xml b/reference/array/functions/sort.xml
index 43d25589cc1d..0b35b1153a2e 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>
   &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:
diff --git a/reference/array/functions/uasort.xml b/reference/array/functions/uasort.xml
index abcebea784af..f04c697282d5 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 22733a990842..ef964532e83c 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>
   &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:
diff --git a/reference/array/functions/usort.xml b/reference/array/functions/usort.xml
index 808ba9459ea8..ce3d33a56f72 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>
   &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:
diff --git a/reference/array/sorting.xml b/reference/array/sorting.xml
index 8fdaa0ae595e..bfdd1648bf60 100644
--- a/reference/array/sorting.xml
+++ b/reference/array/sorting.xml
@@ -22,16 +22,17 @@
     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
     variable itself, as opposed to returning a new sorted array
    </member>
    <member>
-    If any of these sort functions evaluates two members as equal then the
-    order is undefined (the sorting is not stable).
+    Prior to PHP 8.0.0,
+    if any of these sort functions evaluates two members as equal then the
+    order was undefined (the sorting was not stable).
    </member>
   </simplelist>
  </para>
@@ -52,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>
@@ -60,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>
@@ -102,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>
@@ -116,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>