Clarified comparison rules for max(). Closes PHP bug #50607 (max() should say more about multi-dimensional arrays)

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

reference/math/functions/max.xml

@@ -52,7 +52,18 @@
   &reftitle.returnvalues;
   <para>
    <function>max</function> returns the numerically highest of the
-   parameter values.
+   parameter values. If multiple values can be considered of the same size,
+   the one that is listed first will be returned.
+  </para>
+  <para>
+   When <function>max</function> is given multiple <type>array</type>s, the
+   longest array is returned. If all the arrays have the same length,
+   <function>max</function> will use lexicographic ordering to find the return
+   value.
+  </para>
+  <para>
+   When given a <type>string</type> it will be cast as an <type>integer</type>
+   when comparing.
   </para>
  </refsect1>
  <refsect1 role="examples">
@@ -66,12 +77,21 @@
 echo max(1, 3, 5, 6, 7);  // 7
 echo max(array(2, 4, 5)); // 5
 
+// When 'hello' is cast as integer it will be 0. Both the parameters are equally
+// long, so the order they are given in determines the result
 echo max(0, 'hello');     // 0
 echo max('hello', 0);     // hello
+
+echo max('42', 3); // '42'
+
+// Here 0 > -1, so 'hello' is the return value.
 echo max(-1, 'hello');    // hello
 
-// With multiple arrays, max compares from left to right
-// so in our example: 2 == 2, but 4 < 5
+// With multiple arrays of different lengths, max returns the longest
+$val = max(array(2, 2, 2), array(1, 1, 1, 1)); // array(1, 1, 1, 1)
+
+// With multiple arrays of the same length, max compares from left to right
+// using lexicographic order, so in our example: 2 == 2, but 4 < 5
 $val = max(array(2, 4, 8), array(2, 5, 7)); // array(2, 5, 7)
 
 // If both an array and non-array are given, the array