added example for natcasesort

fix: natsort does in fact maintain key/value


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@152489 c90b9560-bf6c-de11-be94-00142212c4b1

reference/array/functions/natcasesort.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- splitted from ./en/functions/array.xml, last change in rev 1.25 -->
   <refentry id="function.natcasesort">
    <refnamediv>
@@ -16,19 +16,65 @@
      </methodsynopsis>
     <para>
      This function implements a sort algorithm that orders
-     alphanumeric strings in the way a human being would.  This is
-     described as a "natural ordering".
+     alphanumeric strings in the way a human being would while maintaining
+     key/value associations.  This is described as a "natural ordering".
     </para>
     <para>
      <function>natcasesort</function> is a case insensitive version of
-     <function>natsort</function>.  See <function>natsort</function>
-     for an example of the difference between this algorithm and the
-     regular computer string sorting algorithms.
+     <function>natsort</function>.
     </para>
     <para>
-     For more information see: Martin Pool's <ulink
-     url="&url.strnatcmp;">Natural Order String Comparison</ulink>
-     page.
+     <example>
+      <title><function>natcasesort</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$array1 = $array2 = array('IMG0.png', 'img12.png', 'img10.png', 'img2.png', 'img1.png', 'IMG3.png');
+
+sort($array1);
+echo "Standard sorting\n";
+print_r($array1);
+
+natcasesort($array2);
+echo "\nNatural order sorting (case-insensitive)\n";
+print_r($array2);
+?>
+]]>
+      </programlisting>
+      <para>
+       The code above will generate the following output:
+      </para>
+      <screen>
+<![CDATA[
+Standard sorting
+Array
+(
+    [0] => IMG0.png
+    [1] => IMG3.png
+    [2] => img1.png
+    [3] => img10.png
+    [4] => img12.png
+    [5] => img2.png
+)
+
+Natural order sorting (case-insensitive)
+Array
+(
+    [0] => IMG0.png
+    [4] => img1.png
+    [3] => img2.png
+    [5] => IMG3.png
+    [2] => img10.png
+    [1] => img12.png
+)
+]]>
+      </screen>
+      <para>
+       For more information see: Martin Pool's <ulink
+       url="&url.strnatcmp;">Natural Order String Comparison</ulink>
+       page.
+      </para>
+     </example>
     </para>
     <para>
      See also <function>sort</function>,

reference/array/functions/natsort.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <!-- splitted from ./en/functions/array.xml, last change in rev 1.25 -->
   <refentry id="function.natsort">
    <refnamediv>
@@ -16,10 +16,11 @@
      </methodsynopsis>
     <para>
      This function implements a sort algorithm that orders
-     alphanumeric strings in the way a human being would.  This is
-     described as a "natural ordering". An example of the difference
-     between this algorithm and the regular computer string sorting
-     algorithms (used in <function>sort</function>) can be seen below:
+     alphanumeric strings in the way a human being would while maintaining
+     key/value associations. This is described as a "natural ordering".  An
+     example of the difference between this algorithm and the regular computer
+     string sorting algorithms (used in <function>sort</function>) can be seen
+     below:
     </para>
     <para>
      <example>
@@ -70,12 +71,6 @@ Array
       </para>
      </example>
     </para>
-    <note>
-     <para>
-      If you're wanting to maintain index/value associations, consider 
-      using <literal>uasort($arr, 'strnatcmp')</literal>.
-     </para>
-    </note>
     <para>
      See also <function>natcasesort</function>,
      <function>strnatcmp</function>, and