From 072b8f71aac51863e440bc483c9a299465442ebc Mon Sep 17 00:00:00 2001
From: Philip Olson <philip@php.net>
Date: Sat, 19 Jul 2003 01:03:46 +0000
Subject: [PATCH] A complete rewrite of min() and max() docs to reflect how
 they really work, including many examples.  See also count().  This also
 closes bug #22565

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@135408 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/math/functions/max.xml | 56 +++++++++++++++++++-----
 reference/math/functions/min.xml | 73 ++++++++++++++++----------------
 2 files changed, 81 insertions(+), 48 deletions(-)

diff --git a/reference/math/functions/max.xml b/reference/math/functions/max.xml
index 9df92c131e..9c4960ae6e 100644
--- a/reference/math/functions/max.xml
+++ b/reference/math/functions/max.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- splitted from ./en/functions/math.xml, last change in rev 1.2 -->
   <refentry id="function.max">
    <refnamediv>
@@ -9,30 +9,64 @@
    <refsect1>
     <title>Description</title>
     <methodsynopsis>
-     <type>number</type><methodname>max</methodname>
-     <methodparam><type>mixed</type><parameter>arg1</parameter></methodparam>
-     <methodparam><type>mixed</type><parameter>arg2</parameter></methodparam>
-     <methodparam><type>mixed</type><parameter>argn</parameter></methodparam>
+     <type>mixed</type><methodname>max</methodname>
+     <methodparam><type>number</type><parameter>arg1</parameter></methodparam>
+     <methodparam><type>number</type><parameter>arg2</parameter></methodparam>
+     <methodparam choice="opt"><type>number</type><parameter>...</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis>
+     <type>mixed</type><methodname>max</methodname>
+     <methodparam><type>array</type><parameter>numbers</parameter></methodparam>
+     <methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam>
     </methodsynopsis>
     <para>
      <function>max</function> returns the numerically highest of the
      parameter values.
     </para>
     <para>
-     If the first parameter is an array, <function>max</function>
+     If the first and only parameter is an array, <function>max</function>
      returns the highest value in that array.  If the first parameter
      is an integer, string or float, you need at least two parameters
      and <function>max</function> returns the biggest of these values.
      You can compare an unlimited number of values.
     </para>
+    <note>
+     <para>
+      PHP will evaluate a non-numeric <type>string</type> as 
+      <literal>0</literal>, but still return the string if it's seen as the
+      numerically highest value.  If multiple arguments evaluate to
+      <literal>0</literal>, <function>max</function> will use the first one
+      it sees (the leftmost value).
+     </para>
+    </note>
     <para>
-     If one or more of the values is a float, all the values will be
-     treated as floats, and a float is returned.  If none of the
-     values is a float, all of them will be treated as integers, and
-     an integer is returned.
+     <example>
+      <title>Example uses of <function>max</function></title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+echo max(1, 3, 5, 6, 7);  // 7
+echo max(array(2, 4, 5)); // 5
+
+echo max(0, 'hello');     // 0
+echo max('hello', 0);     // hello
+echo max(-1, 'hello');    // hello
+
+// With multiple arrays, max compares from left to right
+// 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
+// is always returned as it's seen as the largest
+$val = max('string', array(2, 5, 7), 42);   // array(2, 5, 7)
+?>
+]]>
+      </programlisting>
+     </example>
     </para>
     <para>
-     See also <function>min</function>.
+     See also <function>min</function> and
+     <function>count</function>.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/math/functions/min.xml b/reference/math/functions/min.xml
index cbac548e78..17852fa143 100644
--- a/reference/math/functions/min.xml
+++ b/reference/math/functions/min.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/math.xml, last change in rev 1.2 -->
   <refentry id="function.min">
    <refnamediv>
@@ -9,65 +9,64 @@
    <refsect1>
     <title>Description</title>
      <methodsynopsis>
-      <type>number</type><methodname>min</methodname>
+      <type>mixed</type><methodname>min</methodname>
       <methodparam><type>number</type><parameter>arg1</parameter></methodparam>
       <methodparam><type>number</type><parameter>arg2</parameter></methodparam>
-      <methodparam choice="opt"><parameter>...</parameter></methodparam>
+      <methodparam choice="opt"><type>number</type><parameter>...</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis>
-      <type>number</type><methodname>min</methodname>
+      <type>mixed</type><methodname>min</methodname>
       <methodparam><type>array</type><parameter>numbers</parameter></methodparam>
+      <methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam>
      </methodsynopsis>
     <para>
      <function>min</function> returns the numerically lowest of the
      parameter values.
     </para>
     <para>
-     In the first variant, you need at least two parameters
-     and <function>min</function> returns the lowest of these values.
-     You can compare an unlimited number of values.  If one of the 
-     variables is undefined, <function>min</function> will fail.
+     If the first and only parameter is an array, <function>min</function>
+     returns the lowest value in that array.  If the first parameter
+     is an integer, string or float, you need at least two parameters
+     and <function>min</function> returns the smallest of these values.
+     You can compare an unlimited number of values.
     </para>
+    <note>
+     <para>
+      PHP will evaluate a non-numeric <type>string</type> as 
+      <literal>0</literal>, but still return the string if it's seen as the
+      numerically lowest value.  If multiple arguments evaluate to
+      <literal>0</literal>, <function>min</function> will use the first one
+      it sees (the leftmost value).
+     </para>
+    </note>
     <para>
-     In the second variant, <function>min</function>
-     returns the lowest value in <parameter>numbers</parameter>.  
-    </para>
-    <para>
-     If one or more of the values is a <type>float</type>, all the values 
-     will be
-     treated as floats, and a float is returned.  If none of the
-     values is a float, all of them will be treated as <type>integer</type>s, 
-     and an integer is returned.  Upon failure, <function>min</function> 
-     returns <type>NULL</type> and an error of level <constant>E_WARNING</constant>
-     is generated.
-    </para>
-    <para>
-     <informalexample>
-      <programlisting>
+     <example>
+      <title>Example uses of <function>min</function></title>
+      <programlisting role="php">
 <![CDATA[
 <?php
-$a = 4; 
-$b = 9; 
-$c = 3;
-$arr = array(99, 34, 11);
+echo min(2, 3, 1, 6, 7);  // 1
+echo min(array(2, 4, 5)); // 2
 
-// You may want to implement your own error checking in 
-// case of failure (a variable may not be set)
-if (!$min_value = @min($a, $b, $c)) {
-    echo "Could not get min value, please try again.";
-} else {
-    echo "min value is $min_value";
-}
+echo min(0, 'hello');     // 0
+echo min('hello', 0);     // hello
+echo min('hello', -1);    // -1
 
-print min($arr);  // 11
+// With multiple arrays, min compares from left to right
+// so in our example: 2 == 2, but 4 < 5
+$val = min(array(2, 4, 8), array(2, 5, 1)); // array(2, 4, 8)
 
+// If both an array and non-array are given, the array
+// is never returned as it's considered the largest
+$val = min('string', array(2, 5, 7), 42);   // string
 ?>
 ]]>
       </programlisting>
-     </informalexample>
+     </example>
     </para>
     <para>
-     See also <function>max</function>.
+     See also <function>max</function> and
+     <function>count</function>.
     </para>
    </refsect1>
   </refentry>