reference/math/functions/max.xml
9d044185431afc63026546899216053820ac5d64
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.max">
3
+
<refentry xml:id="function.max" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>max</refname>
6
6
<refpurpose>Find highest value</refpurpose>
...
...
@@ -9,13 +9,13 @@
9
9
&reftitle.description;
10
10
<methodsynopsis>
11
11
<type>mixed</type><methodname>max</methodname>
12
-
<methodparam><type>array</type><parameter>values</parameter></methodparam>
12
+
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
13
+
<methodparam rep="repeat"><type>mixed</type><parameter>values</parameter></methodparam>
13
14
</methodsynopsis>
15
+
<simpara>Alternative signature (not supported with named arguments):</simpara>
14
16
<methodsynopsis>
15
17
<type>mixed</type><methodname>max</methodname>
16
-
<methodparam><type>mixed</type><parameter>value1</parameter></methodparam>
17
-
<methodparam><type>mixed</type><parameter>value2</parameter></methodparam>
18
-
<methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
18
+
<methodparam><type>array</type><parameter>value_array</parameter></methodparam>
19
19
</methodsynopsis>
20
20
<para>
21
21
If the first and only parameter is an array, <function>max</function>
...
...
@@ -24,29 +24,26 @@
24
24
</para>
25
25
<note>
26
26
<para>
27
-
PHP will evaluate a non-numeric <type>string</type> as
28
-
<literal>0</literal> if compared to <type>integer</type>, but still return the string if it's seen as the
29
-
numerically highest value. If multiple arguments evaluate to
30
-
<literal>0</literal>, <function>max</function> will return a numeric
31
-
<literal>0</literal> if given, else the alphabetical highest string
32
-
value will be returned.
27
+
Values of different types will be compared using the <link linkend="language.operators.comparison">
28
+
standard comparison rules</link>. For instance, a non-numeric <type>string</type> will be
29
+
compared to an <type>int</type> as though it were <literal>0</literal>, but multiple non-numeric
30
+
<type>string</type> values will be compared alphanumerically. The actual value returned will be of the
31
+
original type with no conversion applied.
33
32
</para>
34
33
</note>
34
+
<caution>
35
+
<simpara>
36
+
Be careful when passing arguments of different types because
37
+
<function>max</function> can produce unpredictable results.
38
+
</simpara>
39
+
</caution>
35
40
</refsect1>
36
41
<refsect1 role="parameters">
37
42
&reftitle.parameters;
38
43
<para>
39
44
<variablelist>
40
45
<varlistentry>
41
-
<term><parameter>values</parameter></term>
42
-
<listitem>
43
-
<para>
44
-
An array containing the values.
45
-
</para>
46
-
</listitem>
47
-
</varlistentry>
48
-
<varlistentry>
49
-
<term><parameter>value1</parameter></term>
46
+
<term><parameter>value</parameter></term>
50
47
<listitem>
51
48
<para>
52
49
Any <link linkend="language.operators.comparison">comparable</link>
...
...
@@ -55,20 +52,19 @@
55
52
</listitem>
56
53
</varlistentry>
57
54
<varlistentry>
58
-
<term><parameter>value2</parameter></term>
55
+
<term><parameter>values</parameter></term>
59
56
<listitem>
60
57
<para>
61
58
Any <link linkend="language.operators.comparison">comparable</link>
62
-
value.
59
+
values.
63
60
</para>
64
61
</listitem>
65
62
</varlistentry>
66
63
<varlistentry>
67
-
<term><parameter>...</parameter></term>
64
+
<term><parameter>value_array</parameter></term>
68
65
<listitem>
69
66
<para>
70
-
Any <link linkend="language.operators.comparison">comparable</link>
71
-
value.
67
+
An array containing the values.
72
68
</para>
73
69
</listitem>
74
70
</varlistentry>
...
...
@@ -78,21 +74,51 @@
78
74
<refsect1 role="returnvalues">
79
75
&reftitle.returnvalues;
80
76
<para>
81
-
<function>max</function> returns the numerically highest of the
82
-
parameter values. If multiple values can be considered of the same size,
83
-
the one that is listed first will be returned.
84
-
</para>
85
-
<para>
86
-
When <function>max</function> is given multiple <type>array</type>s, the
87
-
longest array is returned. If all the arrays have the same length,
88
-
<function>max</function> will use lexicographic ordering to find the return
89
-
value.
77
+
<function>max</function> returns the parameter value considered "highest" according to standard
78
+
comparisons. If multiple values of different types evaluate as equal (e.g. <literal>0</literal>
79
+
and <literal>'abc'</literal>) the first provided to the function will be returned.
90
80
</para>
81
+
</refsect1>
82
+

83
+
<refsect1 role="errors">
84
+
&reftitle.errors;
91
85
<para>
92
-
When given a <type>string</type> it will be cast as an <type>integer</type>
93
-
when comparing.
86
+
If an empty array is passed, <function>max</function> throws a <classname>ValueError</classname>.
94
87
</para>
95
88
</refsect1>
89
+

90
+
<refsect1 role="changelog">
91
+
&reftitle.changelog;
92
+
<informaltable>
93
+
<tgroup cols="2">
94
+
<thead>
95
+
<row>
96
+
<entry>&Version;</entry>
97
+
<entry>&Description;</entry>
98
+
</row>
99
+
</thead>
100
+
<tbody>
101
+
<row>
102
+
<entry>8.0.0</entry>
103
+
<entry>
104
+
<function>max</function> throws a <classname>ValueError</classname> on failure now;
105
+
previously, &false; was returned and an <constant>E_WARNING</constant> error was emitted.
106
+
</entry>
107
+
</row>
108
+
<row>
109
+
<entry>8.0.0</entry>
110
+
<entry>
111
+
As <link linkend="migration80.incompatible.core.string-number-comparision">
112
+
string to number comparisons</link> were changed,
113
+
<function>max</function> no longer returns a
114
+
different value based on the argument order in those cases.
115
+
</entry>
116
+
</row>
117
+
</tbody>
118
+
</tgroup>
119
+
</informaltable>
120
+
</refsect1>
121
+

96
122
<refsect1 role="examples">
97
123
&reftitle.examples;
98
124
<para>
...
...
@@ -101,29 +127,30 @@
101
127
<programlisting role="php">
102
128
<![CDATA[
103
129
<?php
104
-
echo max(1, 3, 5, 6, 7); // 7
130
+
echo max(2, 3, 1, 6, 7); // 7
105
131
echo max(array(2, 4, 5)); // 5
106
132

107
-
// When 'hello' is cast as integer it will be 0. Both the parameters are equally
108
-
// long, so the order they are given in determines the result
109
-
echo max(0, 'hello'); // 0
110
-
echo max('hello', 0); // hello
111
-

112
-
echo max('42', 3); // '42'
113
-

114
-
// Here 0 > -1, so 'hello' is the return value.
115
-
echo max(-1, 'hello'); // hello
133
+
// Here we are comparing -1 < 0, so 'hello' is the highest value
134
+
echo max('hello', -1); // hello
116
135

117
136
// With multiple arrays of different lengths, max returns the longest
118
137
$val = max(array(2, 2, 2), array(1, 1, 1, 1)); // array(1, 1, 1, 1)
119
138

120
-
// With multiple arrays of the same length, max compares from left to right
121
-
// using lexicographic order, so in our example: 2 == 2, but 4 < 5
122
-
$val = max(array(2, 4, 8), array(2, 5, 7)); // array(2, 5, 7)
139
+
// Multiple arrays of the same length are compared from left to right
140
+
// so in our example: 2 == 2, but 5 > 4
141
+
$val = max(array(2, 4, 8), array(2, 5, 1)); // array(2, 5, 1)
123
142

124
-
// If both an array and non-array are given, the array
125
-
// is always returned as it's seen as the largest
143
+
// If both an array and non-array are given, the array will be returned
144
+
// as comparisons treat arrays as greater than any other value
126
145
$val = max('string', array(2, 5, 7), 42); // array(2, 5, 7)
146
+

147
+
// If one argument is NULL or a boolean, it will be compared against
148
+
// other values using the rule FALSE < TRUE regardless of the other types involved
149
+
// In the below example, -10 is treated as TRUE in the comparison
150
+
$val = max(-10, FALSE); // -10
151
+

152
+
// 0, on the other hand, is treated as FALSE, so is "lower than" TRUE
153
+
$val = max(0, TRUE); // TRUE
127
154
?>
128
155
]]>
129
156
</programlisting>
...
...
@@ -140,7 +167,6 @@ $val = max('string', array(2, 5, 7), 42); // array(2, 5, 7)
140
167
</para>
141
168
</refsect1>
142
169
</refentry>
143
-

144
170
<!-- Keep this comment at the end of the file
145
171
Local variables:
146
172
mode: sgml
147
173