From 5fba3a90ddcae79a6951c2089d59b2eced0939cf Mon Sep 17 00:00:00 2001
From: Arpad Ray <arpad@php.net>
Date: Fri, 9 Mar 2012 13:47:14 +0000
Subject: [PATCH] Docs for #55158 (adding SORT_NATURAL and SORT_FLAG_CASE)

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@324055 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/array/constants.xml      | 27 +++++++++++++++++-
 reference/array/functions/sort.xml | 44 ++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+), 1 deletion(-)

diff --git a/reference/array/constants.xml b/reference/array/constants.xml
index c2a8a4d80b..4fc0998260 100644
--- a/reference/array/constants.xml
+++ b/reference/array/constants.xml
@@ -111,6 +111,32 @@
     </simpara>
    </listitem>
   </varlistentry>
+  <varlistentry xml:id="constant.sort-natural">
+   <term>
+    <constant>SORT_NATURAL</constant> 
+    (<type>integer</type>)
+   </term>
+   <listitem>
+    <simpara>
+    <constant>SORT_NATURAL</constant> is used to compare items as
+    strings using "natural ordering" like <function>natsort</function>. Added in PHP 5.4.0.
+    </simpara>
+   </listitem>
+  </varlistentry>
+  <varlistentry xml:id="constant.sort-flag-case">
+   <term>
+    <constant>SORT_FLAG_CASE</constant> 
+    (<type>integer</type>)
+   </term>
+   <listitem>
+    <simpara>
+    <constant>SORT_FLAG_CASE</constant> can be combined
+         (bitwise OR) with
+         <constant>SORT_STRING</constant> or
+         <constant>SORT_NATURAL</constant> to sort strings case-insensitively. Added in PHP 5.4.0.
+    </simpara>
+   </listitem>
+  </varlistentry>
  </variablelist>
  </para>
  <variablelist>
@@ -247,4 +273,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->
-
diff --git a/reference/array/functions/sort.xml b/reference/array/functions/sort.xml
index d73c47d53a..85e2e5d8c2 100644
--- a/reference/array/functions/sort.xml
+++ b/reference/array/functions/sort.xml
@@ -60,6 +60,17 @@
           -->
          </simpara>
         </listitem>
+        <listitem>
+         <simpara><constant>SORT_NATURAL</constant> - compare items as strings
+         using "natural ordering" like <function>natsort</function>. Added in
+         PHP 5.4.0.</simpara>
+        </listitem>
+        <listitem>
+         <simpara><constant>SORT_FLAG_CASE</constant> - can be combined
+         (bitwise OR) with
+         <constant>SORT_STRING</constant> or
+         <constant>SORT_NATURAL</constant> to sort strings case-insensitively. Added in PHP 5.4.0.</simpara>
+        </listitem>
        </itemizedlist>
       </para>
      </listitem>
@@ -105,6 +116,39 @@ fruits[3] = orange
   <para>
    The fruits have been sorted in alphabetical order.
   </para>
+  <para>
+   <example>
+    <title><function>sort</function> example using case-insensitive natural
+    ordering</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+$fruits = array(
+	"Orange1", "orange2", "Orange3", "orange20"
+);
+sort($fruits, SORT_NATURAL | SORT_FLAG_CASE);
+foreach ($fruits as $key => $val) {
+    echo "fruits[" . $key . "] = " . $val . "\n";
+}
+
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+fruits[0] = Orange1
+fruits[1] = orange2
+fruits[2] = Orange3
+fruits[3] = orange20
+]]>
+    </screen>
+   </example>
+  </para>
+  <para>
+   The fruits have been sorted like <function>natcasesort</function>.
+  </para>
  </refsect1>
  <refsect1 role="notes">
   &reftitle.notes;