reference/math/functions/min.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.min">
3
+
<refentry xml:id="function.min" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>min</refname>
6
6
<refpurpose>Find lowest value</refpurpose>
...
...
@@ -9,13 +9,13 @@
9
9
&reftitle.description;
10
10
<methodsynopsis>
11
11
<type>mixed</type><methodname>min</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>min</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>min</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 lowest value. If multiple arguments evaluate to
30
-
<literal>0</literal>, <function>min</function> will return the lowest
31
-
alphanumerical string value if any strings are given, else a numeric
32
-
<literal>0</literal> is 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>min</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,10 +74,51 @@
78
74
<refsect1 role="returnvalues">
79
75
&reftitle.returnvalues;
80
76
<para>
81
-
<function>min</function> returns the numerically lowest of the
82
-
parameter values.
77
+
<function>min</function> returns the parameter value considered "lowest" 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.
83
80
</para>
84
81
</refsect1>
82
+

83
+
<refsect1 role="errors">
84
+
&reftitle.errors;
85
+
<para>
86
+
If an empty array is passed, <function>min</function> throws a <classname>ValueError</classname>.
87
+
</para>
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>min</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>min</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
+

85
122
<refsect1 role="examples">
86
123
&reftitle.examples;
87
124
<para>
...
...
@@ -93,22 +130,35 @@
93
130
echo min(2, 3, 1, 6, 7); // 1
94
131
echo min(array(2, 4, 5)); // 2
95
132

96
-
echo min(0, 'hello'); // 0
97
-
echo min('hello', 0); // hello
133
+
// Here we are comparing -1 < 0, so -1 is the lowest value
98
134
echo min('hello', -1); // -1
99
135

100
-
// With multiple arrays, min compares from left to right
136
+
// With multiple arrays of different lengths, min returns the shortest
137
+
$val = min(array(2, 2, 2), array(1, 1, 1, 1)); // array(2, 2, 2)
138
+

139
+
// Multiple arrays of the same length are compared from left to right
101
140
// so in our example: 2 == 2, but 4 < 5
102
141
$val = min(array(2, 4, 8), array(2, 5, 1)); // array(2, 4, 8)
103
142

104
-
// If both an array and non-array are given, the array
105
-
// is never returned as it's considered the largest
143
+
// If both an array and non-array are given, the array is never returned
144
+
// as comparisons treat arrays as greater than any other value
106
145
$val = min('string', array(2, 5, 7), 42); // string
146
+

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

154
+
// 0, on the other hand, is treated as FALSE, so is "lower than" TRUE
155
+
$val = min(0, TRUE); // 0
107
156
?>
108
157
]]>
109
158
</programlisting>
110
159
</example>
111
160
</para>
161
+

112
162
</refsect1>
113
163
<refsect1 role="seealso">
114
164
&reftitle.seealso;
...
...
@@ -120,7 +170,6 @@ $val = min('string', array(2, 5, 7), 42); // string
120
170
</para>
121
171
</refsect1>
122
172
</refentry>
123
-

124
173
<!-- Keep this comment at the end of the file
125
174
Local variables:
126
175
mode: sgml
127
176