reference/math/functions/round.xml
15b93836d93f01ea6d90a68cacf04ce0d9fb8eff
...
...
@@ -8,13 +8,13 @@
8
8
<refsect1 role="description">
9
9
&reftitle.description;
10
10
<methodsynopsis>
11
-
<type>float</type><methodname>round</methodname>
12
-
<methodparam><type>float</type><parameter>val</parameter></methodparam>
13
-
<methodparam choice="opt"><type>int</type><parameter>precision</parameter><initializer>0</initializer></methodparam>
14
-
<methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer>PHP_ROUND_HALF_UP</initializer></methodparam>
15
-
</methodsynopsis>
11
+
<type>float</type><methodname>round</methodname>
12
+
<methodparam><type class="union"><type>int</type><type>float</type></type><parameter>num</parameter></methodparam>
13
+
<methodparam choice="opt"><type>int</type><parameter>precision</parameter><initializer>0</initializer></methodparam>
14
+
<methodparam choice="opt"><type class="union"><type>int</type><type>RoundingMode</type></type><parameter>mode</parameter><initializer>RoundingMode::HalfAwayFromZero</initializer></methodparam>
15
+
</methodsynopsis>
16
16
<para>
17
-
Returns the rounded value of <parameter>val</parameter> to
17
+
Returns the rounded value of <parameter>num</parameter> to
18
18
specified <parameter>precision</parameter>
19
19
(number of digits after the decimal point).
20
20
<parameter>precision</parameter> can also be negative or zero (default).
...
...
@@ -41,7 +41,7 @@
41
41
<para>
42
42
<variablelist>
43
43
<varlistentry>
44
-
<term><parameter>val</parameter></term>
44
+
<term><parameter>num</parameter></term>
45
45
<listitem>
46
46
<para>
47
47
The value to round.
...
...
@@ -55,14 +55,14 @@
55
55
The optional number of decimal digits to round to.
56
56
</para>
57
57
<para>
58
-
If the <parameter>precision</parameter> is positive, <parameter>val</parameter> is
58
+
If the <parameter>precision</parameter> is positive, <parameter>num</parameter> is
59
59
rounded to <parameter>precision</parameter> significant digits after the decimal point.
60
60
</para>
61
61
<para>
62
-
If the <parameter>precision</parameter> is negative, <parameter>val</parameter> is
62
+
If the <parameter>precision</parameter> is negative, <parameter>num</parameter> is
63
63
rounded to <parameter>precision</parameter> significant digits before the decimal point,
64
-
i.e. to the nearest multiple of <literal>pow(10, -precision)</literal>, e.g. for a
65
-
<parameter>precision</parameter> of -1 <parameter>val</parameter> is rounded to tens,
64
+
i.e. to the nearest multiple of <code>pow(10, -$precision)</code>, e.g. for a
65
+
<parameter>precision</parameter> of -1 <parameter>num</parameter> is rounded to tens,
66
66
for a <parameter>precision</parameter> of -2 to hundreds, etc.
67
67
</para>
68
68
</listitem>
...
...
@@ -71,7 +71,7 @@
71
71
<term><parameter>mode</parameter></term>
72
72
<listitem>
73
73
<para>
74
-
Use one of the following constants to specify the mode in which rounding occurs.
74
+
Use <enumname>RoundingMode</enumname> or one of the following constants to specify the mode in which rounding occurs.
75
75
<informaltable>
76
76
<tgroup cols="2">
77
77
<thead>
...
...
@@ -84,34 +84,35 @@
84
84
<row>
85
85
<entry><constant>PHP_ROUND_HALF_UP</constant></entry>
86
86
<entry>
87
-
Rounds <parameter>val</parameter> away from zero when it is half way there,
87
+
Rounds <parameter>num</parameter> away from zero when it is half way there,
88
88
making 1.5 into 2 and -1.5 into -2.
89
89
</entry>
90
90
</row>
91
91
<row>
92
92
<entry><constant>PHP_ROUND_HALF_DOWN</constant></entry>
93
93
<entry>
94
-
Rounds <parameter>val</parameter> towards zero when it is half way there,
94
+
Rounds <parameter>num</parameter> towards zero when it is half way there,
95
95
making 1.5 into 1 and -1.5 into -1.
96
96
</entry>
97
97
</row>
98
98
<row>
99
99
<entry><constant>PHP_ROUND_HALF_EVEN</constant></entry>
100
100
<entry>
101
-
Rounds <parameter>val</parameter> towards the nearest even value when it is half way
101
+
Rounds <parameter>num</parameter> towards the nearest even value when it is half way
102
102
there, making both 1.5 and 2.5 into 2.
103
103
</entry>
104
104
</row>
105
105
<row>
106
106
<entry><constant>PHP_ROUND_HALF_ODD</constant></entry>
107
107
<entry>
108
-
Rounds <parameter>val</parameter> towards the nearest odd value when it is half way
108
+
Rounds <parameter>num</parameter> towards the nearest odd value when it is half way
109
109
there, making 1.5 into 1 and 2.5 into 3.
110
110
</entry>
111
111
</row>
112
112
</tbody>
113
113
</tgroup>
114
114
</informaltable>
115
+
However, please note that some newly added modes only exist in <link linkend="enum.roundingmode">RoundingMode</link>.
115
116
</para>
116
117
</listitem>
117
118
</varlistentry>
...
...
@@ -124,6 +125,52 @@
124
125
The value rounded to the given <parameter>precision</parameter> as a &float;.
125
126
</para>
126
127
</refsect1>
128
+

129
+
<refsect1 role="errors">
130
+
&reftitle.errors;
131
+
<simpara>
132
+
The function throws a <exceptionname>ValueError</exceptionname> if <parameter>mode</parameter> is
133
+
invalid.
134
+
Prior to PHP 8.4.0, an invalid mode would silently default to <constant>PHP_ROUND_HALF_UP</constant>.
135
+
</simpara>
136
+
</refsect1>
137
+

138
+
<refsect1 role="changelog">
139
+
&reftitle.changelog;
140
+
<informaltable>
141
+
<tgroup cols="2">
142
+
<thead>
143
+
<row>
144
+
<entry>&Version;</entry>
145
+
<entry>&Description;</entry>
146
+
</row>
147
+
</thead>
148
+
<tbody>
149
+
<row>
150
+
<entry>8.4.0</entry>
151
+
<entry>
152
+
Four new rounding modes have been added.
153
+
</entry>
154
+
</row>
155
+
<row>
156
+
<entry>8.4.0</entry>
157
+
<entry>
158
+
Now throws a <exceptionname>ValueError</exceptionname> if
159
+
<parameter>mode</parameter> is invalid.
160
+
</entry>
161
+
</row>
162
+
<row>
163
+
<entry>8.0.0</entry>
164
+
<entry>
165
+
<parameter>num</parameter> no longer accepts internal objects which support
166
+
numeric conversion.
167
+
</entry>
168
+
</row>
169
+
</tbody>
170
+
</tgroup>
171
+
</informaltable>
172
+
</refsect1>
173
+

127
174
<refsect1 role="examples">
128
175
&reftitle.examples;
129
176
<para>
...
...
@@ -281,6 +328,61 @@ float(-1.5)
281
328
]]>
282
329
</screen>
283
330
</example>
331
+
<example>
332
+
<title>Example of using <enumname>RoundingMode</enumname></title>
333
+
<programlisting role="php">
334
+
<![CDATA[
335
+
<?php
336
+
foreach (RoundingMode::cases() as $mode) {
337
+
foreach ([
338
+
8.5,
339
+
9.5,
340
+
-3.5,
341
+
] as $number) {
342
+
printf("%-17s: %+.17g -> %+.17g\n", $mode->name, $number, round($number, 0, $mode));
343
+
}
344
+
echo "\n";
345
+
}
346
+
?>
347
+
]]>
348
+
</programlisting>
349
+
&example.outputs;
350
+
<screen role="php">
351
+
<![CDATA[
352
+
HalfAwayFromZero : +8.5 -> +9
353
+
HalfAwayFromZero : +9.5 -> +10
354
+
HalfAwayFromZero : -3.5 -> -4
355
+

356
+
HalfTowardsZero : +8.5 -> +8
357
+
HalfTowardsZero : +9.5 -> +9
358
+
HalfTowardsZero : -3.5 -> -3
359
+

360
+
HalfEven : +8.5 -> +8
361
+
HalfEven : +9.5 -> +10
362
+
HalfEven : -3.5 -> -4
363
+

364
+
HalfOdd : +8.5 -> +9
365
+
HalfOdd : +9.5 -> +9
366
+
HalfOdd : -3.5 -> -3
367
+

368
+
TowardsZero : +8.5 -> +8
369
+
TowardsZero : +9.5 -> +9
370
+
TowardsZero : -3.5 -> -3
371
+

372
+
AwayFromZero : +8.5 -> +9
373
+
AwayFromZero : +9.5 -> +10
374
+
AwayFromZero : -3.5 -> -4
375
+

376
+
NegativeInfinity : +8.5 -> +8
377
+
NegativeInfinity : +9.5 -> +9
378
+
NegativeInfinity : -3.5 -> -4
379
+

380
+
PositiveInfinity : +8.5 -> +9
381
+
PositiveInfinity : +9.5 -> +10
382
+
PositiveInfinity : -3.5 -> -3
383
+
]]>
384
+
</screen>
385
+
</example>
284
386
</para>
285
387
</refsect1>
286
388

...
...
@@ -295,7 +397,6 @@ float(-1.5)
295
397
</para>
296
398
</refsect1>
297
399
</refentry>
298
-

299
400
<!-- Keep this comment at the end of the file
300
401
Local variables:
301
402
mode: sgml
302
403



Translation status