Re: [RFC] Comparison and conversion inconsistency - need more info

On 11/11/2013 19:03, Sanford Whiteman wrote: >> You don't have to think the current documentation is awful to find ways >> of improving it. > Sure, go for it! > > -- S. I've had a busy week, but have now submitted a patch via edit.php.net (copy attached) which tidies up both min() and max() documentation to refer to the standard comparisons rather than the misleading mentions of "numeric comparison" etc. I've also made them use the same examples wherever it makes sense, since they really are exact counter-parts to one another. Any feedback is of course welcome. :) -- Rowan Collins [IMSoP]

Index: en/reference/math/functions/min.xml --- en/reference/math/functions/min.xml +++ en/reference/math/functions/min.xml @@ -24,12 +24,11 @@ </para> <note> <para> - PHP will evaluate a non-numeric <type>string</type> as - <literal>0</literal> if compared to <type>integer</type>, 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 return the lowest - alphanumerical string value if any strings are given, else a numeric - <literal>0</literal> is returned. + Values of different types will be compared using the <link linkend="language.operators.comparison"> + standard comparison rules</link>. For instance, a non-numeric <type>string</type> will be + compared to an <type>integer</type> as though it were <literal>0</literal>, but multiple + <type>string</type> values will be compared alphanumerically. The actual value returned will be of the + original type with no conversion applied. </para> </note> </refsect1> @@ -78,8 +77,9 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - <function>min</function> returns the numerically lowest of the - parameter values. + <function>min</function> returns the parameter value considered "lowest" according to standard + comparisons. If multiple values of different types evaluate as equal (e.g. <literal>0</literal> + and <literal>'abc'</literal>) the first provided to the function will be returned. </para> </refsect1> <refsect1 role="examples"> @@ -93,32 +93,33 @@ echo min(2, 3, 1, 6, 7); // 1 echo min(array(2, 4, 5)); // 2 +// The string 'hello' when compared to an int is treated as 0 +// Since the two values are equal, the order they are provided determines the result echo min(0, 'hello'); // 0 echo min('hello', 0); // hello + +// Here we are comparing -1 < 0, so -1 is the lowest value echo min('hello', -1); // -1 -// With multiple arrays, min compares from left to right +// With multiple arrays of different lengths, min returns the shortest +$val = min(array(2, 2, 2), array(1, 1, 1, 1)); // array(2, 2, 2) + +// Multiple arrays of the same length are compared 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 +// If both an array and non-array are given, the array is never returned +// as comparisons treat arrays as greater than any other value $val = min('string', array(2, 5, 7), 42); // string -?> -]]> - </programlisting> - </example> - </para> - <para> - <example> - <title>Example of NULL/FALSE value with <function>min</function></title> - <programlisting role="php"> -<![CDATA[ -<?php -// PHP compares variable as boolean when one of operand is boolean. -var_dump(min(-100,-10, NULL, 10, 100); // NULL - (bool)NULL < (bool)-100 is FALSE < TRUE -var_dump(min(-100,-10, FALSE, 10, 100); // FALSE - (bool)FALSE < (bool)-100 is FALSE < TRUE +// If one argument is NULL or a boolean, it will be compared against +// other values using the rule FALSE < TRUE regardless of the other types involved +// In the below examples, both -10 and 10 are treated as TRUE in the comparison +$val = min(-10, FALSE, 10); // FALSE +$val = min(-10, NULL, 10); // NULL + +// 0, on the other hand, is treated as FALSE, so is "lower than" TRUE +$val = min(0, TRUE); // 0 ?> ]]> </programlisting> Index: en/reference/math/functions/max.xml --- en/reference/math/functions/max.xml +++ en/reference/math/functions/max.xml @@ -24,12 +24,11 @@ </para> <note> <para> - PHP will evaluate a non-numeric <type>string</type> as - <literal>0</literal> if compared to <type>integer</type>, 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 return a numeric - <literal>0</literal> if given, else the alphabetical highest string - value will be returned. + Values of different types will be compared using the <link linkend="language.operators.comparison"> + standard comparison rules</link>. For instance, a non-numeric <type>string</type> will be + compared to an <type>integer</type> as though it were <literal>0</literal>, but multiple + <type>string</type> values will be compared alphanumerically. The actual value returned will be of the + original type with no conversion applied. </para> </note> </refsect1> @@ -78,19 +77,9 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - <function>max</function> returns the numerically highest of the - 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. + <function>max</function> returns the parameter value considered "highest" according to standard + comparisons. If multiple values of different types evaluate as equal (e.g. <literal>0</literal> + and <literal>'abc'</literal>) the first provided to the function will be returned. </para> </refsect1> <refsect1 role="examples"> @@ -101,29 +90,36 @@ <programlisting role="php"> <![CDATA[ <?php -echo max(1, 3, 5, 6, 7); // 7 +echo max(2, 3, 1, 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 +// The string 'hello' when compared to an int is treated as 0 +// Since the two values are equal, the order they are provided 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 +// Here we are comparing -1 < 0, so 'hello' is the highest value +echo max('hello', -1); // hello // 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) +// Multiple arrays of the same length are compared from left to right +// so in our example: 2 == 2, but 5 > 4 +$val = max(array(2, 4, 8), array(2, 5, 1)); // array(2, 5, 1) -// If both an array and non-array are given, the array -// is always returned as it's seen as the largest +// If both an array and non-array are given, the array will be returned +// as comparisons treat arrays as greater than any other value $val = max('string', array(2, 5, 7), 42); // array(2, 5, 7) + +// If one argument is NULL or a boolean, it will be compared against +// other values using the rule FALSE < TRUE regardless of the other types involved +// In the below examples, -10 is treated as TRUE in the comparison +$val = max(-10, FALSE); // -10 +$val = max(-10, FALSE); // -10 + +// 0, on the other hand, is treated as FALSE, so is "lower than" TRUE +$val = max(0, TRUE); // TRUE ?> ]]> </programlisting>