Update array sorting docs

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

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:

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:

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:

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:

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: