reference/math/functions/round.xml
6406cc6c50f8f66f7d55f550dc1ec2759e2eca0f
...
...
@@ -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>int</type><parameter>mode</parameter><initializer><constant>PHP_ROUND_HALF_UP</constant></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).
...
...
@@ -35,25 +35,16 @@
35
35
</caution>
36
36
</para>
37
37
-->
38
-
<para>
39
-
<note>
40
-
<simpara>
41
-
PHP doesn't handle strings like <literal>"12,300.2"</literal> correctly
42
-
by default. See <link linkend="language.types.string.conversion"
43
-
>converting from strings</link>.
44
-
</simpara>
45
-
</note>
46
-
</para>
47
38
</refsect1>
48
39
<refsect1 role="parameters">
49
40
&reftitle.parameters;
50
41
<para>
51
42
<variablelist>
52
43
<varlistentry>
53
-
<term><parameter>val</parameter></term>
44
+
<term><parameter>num</parameter></term>
54
45
<listitem>
55
46
<para>
56
-
The value to round
47
+
The value to round.
57
48
</para>
58
49
</listitem>
59
50
</varlistentry>
...
...
@@ -63,6 +54,17 @@
63
54
<para>
64
55
The optional number of decimal digits to round to.
65
56
</para>
57
+
<para>
58
+
If the <parameter>precision</parameter> is positive, <parameter>num</parameter> is
59
+
rounded to <parameter>precision</parameter> significant digits after the decimal point.
60
+
</para>
61
+
<para>
62
+
If the <parameter>precision</parameter> is negative, <parameter>num</parameter> is
63
+
rounded to <parameter>precision</parameter> significant digits before the decimal point,
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
+
for a <parameter>precision</parameter> of -2 to hundreds, etc.
67
+
</para>
66
68
</listitem>
67
69
</varlistentry>
68
70
<varlistentry>
...
...
@@ -74,7 +76,7 @@
74
76
<tgroup cols="2">
75
77
<thead>
76
78
<row>
77
-
<entry>Constant</entry>
79
+
<entry>&Constants;</entry>
78
80
<entry>&Description;</entry>
79
81
</row>
80
82
</thead>
...
...
@@ -82,29 +84,29 @@
82
84
<row>
83
85
<entry><constant>PHP_ROUND_HALF_UP</constant></entry>
84
86
<entry>
85
-
Round <parameter>val</parameter> up to <parameter>precision</parameter> decimal places
86
-
away from zero, when it is half way there. Making 1.5 into 2 and -1.5 into -2.
87
+
Rounds <parameter>num</parameter> away from zero when it is half way there,
88
+
making 1.5 into 2 and -1.5 into -2.
87
89
</entry>
88
90
</row>
89
91
<row>
90
92
<entry><constant>PHP_ROUND_HALF_DOWN</constant></entry>
91
93
<entry>
92
-
Round <parameter>val</parameter> down to <parameter>precision</parameter> decimal places
93
-
towards zero, when it is half way there. Making 1.5 into 1 and -1.5 into -1.
94
+
Rounds <parameter>num</parameter> towards zero when it is half way there,
95
+
making 1.5 into 1 and -1.5 into -1.
94
96
</entry>
95
97
</row>
96
98
<row>
97
99
<entry><constant>PHP_ROUND_HALF_EVEN</constant></entry>
98
100
<entry>
99
-
Round <parameter>val</parameter> to <parameter>precision</parameter> decimal places
100
-
towards the next even value.
101
+
Rounds <parameter>num</parameter> towards the nearest even value when it is half way
102
+
there, making both 1.5 and 2.5 into 2.
101
103
</entry>
102
104
</row>
103
105
<row>
104
106
<entry><constant>PHP_ROUND_HALF_ODD</constant></entry>
105
107
<entry>
106
-
Round <parameter>val</parameter> to <parameter>precision</parameter> decimal places
107
-
towards the next odd value.
108
+
Rounds <parameter>num</parameter> towards the nearest odd value when it is half way
109
+
there, making 1.5 into 1 and 2.5 into 3.
108
110
</entry>
109
111
</row>
110
112
</tbody>
...
...
@@ -119,9 +121,33 @@
119
121
<refsect1 role="returnvalues">
120
122
&reftitle.returnvalues;
121
123
<para>
122
-
The rounded value
124
+
The value rounded to the given <parameter>precision</parameter> as a &float;.
123
125
</para>
124
126
</refsect1>
127
+

128
+
<refsect1 role="changelog">
129
+
&reftitle.changelog;
130
+
<informaltable>
131
+
<tgroup cols="2">
132
+
<thead>
133
+
<row>
134
+
<entry>&Version;</entry>
135
+
<entry>&Description;</entry>
136
+
</row>
137
+
</thead>
138
+
<tbody>
139
+
<row>
140
+
<entry>8.0.0</entry>
141
+
<entry>
142
+
<parameter>num</parameter> no longer accepts internal objects which support
143
+
numeric conversion.
144
+
</entry>
145
+
</row>
146
+
</tbody>
147
+
</tgroup>
148
+
</informaltable>
149
+
</refsect1>
150
+

125
151
<refsect1 role="examples">
126
152
&reftitle.examples;
127
153
<para>
...
...
@@ -130,17 +156,66 @@
130
156
<programlisting role="php">
131
157
<![CDATA[
132
158
<?php
133
-
echo round(3.4); // 3
134
-
echo round(3.5); // 4
135
-
echo round(3.6); // 4
136
-
echo round(3.6, 0); // 4
137
-
echo round(1.95583, 2); // 1.96
138
-
echo round(1241757, -3); // 1242000
139
-
echo round(5.045, 2); // 5.05
140
-
echo round(5.055, 2); // 5.06
159
+
var_dump(round(3.4));
160
+
var_dump(round(3.5));
161
+
var_dump(round(3.6));
162
+
var_dump(round(3.6, 0));
163
+
var_dump(round(5.045, 2));
164
+
var_dump(round(5.055, 2));
165
+
var_dump(round(345, -2));
166
+
var_dump(round(345, -3));
167
+
var_dump(round(678, -2));
168
+
var_dump(round(678, -3));
169
+
?>
170
+
]]>
171
+
</programlisting>
172
+
&example.outputs;
173
+
<screen role="php">
174
+
<![CDATA[
175
+
float(3)
176
+
float(4)
177
+
float(4)
178
+
float(4)
179
+
float(5.05)
180
+
float(5.06)
181
+
float(300)
182
+
float(0)
183
+
float(700)
184
+
float(1000)
185
+
]]>
186
+
</screen>
187
+
</example>
188
+
</para>
189
+
<para>
190
+
<example>
191
+
<title>How <parameter>precision</parameter> affects a float</title>
192
+
<programlisting role="php">
193
+
<![CDATA[
194
+
<?php
195
+
$number = 135.79;
196
+

197
+
var_dump(round($number, 3));
198
+
var_dump(round($number, 2));
199
+
var_dump(round($number, 1));
200
+
var_dump(round($number, 0));
201
+
var_dump(round($number, -1));
202
+
var_dump(round($number, -2));
203
+
var_dump(round($number, -3));
141
204
?>
142
205
]]>
143
206
</programlisting>
207
+
&example.outputs;
208
+
<screen role="php">
209
+
<![CDATA[
210
+
float(135.79)
211
+
float(135.79)
212
+
float(135.8)
213
+
float(136)
214
+
float(140)
215
+
float(100)
216
+
float(0)
217
+
]]>
218
+
</screen>
144
219
</example>
145
220
</para>
146
221
<para>
...
...
@@ -149,83 +224,89 @@ echo round(5.055, 2); // 5.06
149
224
<programlisting role="php">
150
225
<![CDATA[
151
226
<?php
152
-
echo round(9.5, 0, PHP_ROUND_HALF_UP); // 10
153
-
echo round(9.5, 0, PHP_ROUND_HALF_DOWN); // 9
154
-
echo round(9.5, 0, PHP_ROUND_HALF_EVEN); // 10
155
-
echo round(9.5, 0, PHP_ROUND_HALF_ODD); // 9
227
+
echo 'Rounding modes with 9.5' . PHP_EOL;
228
+
var_dump(round(9.5, 0, PHP_ROUND_HALF_UP));
229
+
var_dump(round(9.5, 0, PHP_ROUND_HALF_DOWN));
230
+
var_dump(round(9.5, 0, PHP_ROUND_HALF_EVEN));
231
+
var_dump(round(9.5, 0, PHP_ROUND_HALF_ODD));
156
232

157
-
echo round(8.5, 0, PHP_ROUND_HALF_UP); // 9
158
-
echo round(8.5, 0, PHP_ROUND_HALF_DOWN); // 8
159
-
echo round(8.5, 0, PHP_ROUND_HALF_EVEN); // 8
160
-
echo round(8.5, 0, PHP_ROUND_HALF_ODD); // 9
233
+
echo PHP_EOL;
234
+
echo 'Rounding modes with 8.5' . PHP_EOL;
235
+
var_dump(round(8.5, 0, PHP_ROUND_HALF_UP));
236
+
var_dump(round(8.5, 0, PHP_ROUND_HALF_DOWN));
237
+
var_dump(round(8.5, 0, PHP_ROUND_HALF_EVEN));
238
+
var_dump(round(8.5, 0, PHP_ROUND_HALF_ODD));
161
239
?>
162
240
]]>
163
241
</programlisting>
242
+
&example.outputs;
243
+
<screen role="php">
244
+
<![CDATA[
245
+
Rounding modes with 9.5
246
+
float(10)
247
+
float(9)
248
+
float(10)
249
+
float(9)
250
+

251
+
Rounding modes with 8.5
252
+
float(9)
253
+
float(8)
254
+
float(8)
255
+
float(9)
256
+
]]>
257
+
</screen>
164
258
</example>
259
+
</para>
260
+
<para>
165
261
<example>
166
-
<title><parameter>mode</parameter> with precision examples</title>
262
+
<title><parameter>mode</parameter> with <parameter>precision</parameter> examples</title>
167
263
<programlisting role="php">
168
264
<![CDATA[
169
265
<?php
170
-
/* Using PHP_ROUND_HALF_UP with 1 decimal digit precision */
171
-
echo round( 1.55, 1, PHP_ROUND_HALF_UP); // 1.6
172
-
echo round( 1.54, 1, PHP_ROUND_HALF_UP); // 1.5
173
-
echo round(-1.55, 1, PHP_ROUND_HALF_UP); // -1.6
174
-
echo round(-1.54, 1, PHP_ROUND_HALF_UP); // -1.5
266
+
echo 'Using PHP_ROUND_HALF_UP with 1 decimal digit precision' . PHP_EOL;
267
+
var_dump(round( 1.55, 1, PHP_ROUND_HALF_UP));
268
+
var_dump(round(-1.55, 1, PHP_ROUND_HALF_UP));
175
269

176
-
/* Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision */
177
-
echo round( 1.55, 1, PHP_ROUND_HALF_DOWN); // 1.5
178
-
echo round( 1.54, 1, PHP_ROUND_HALF_DOWN); // 1.5
179
-
echo round(-1.55, 1, PHP_ROUND_HALF_DOWN); // -1.5
180
-
echo round(-1.54, 1, PHP_ROUND_HALF_DOWN); // -1.5
270
+
echo PHP_EOL;
271
+
echo 'Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision' . PHP_EOL;
272
+
var_dump(round( 1.55, 1, PHP_ROUND_HALF_DOWN));
273
+
var_dump(round(-1.55, 1, PHP_ROUND_HALF_DOWN));
181
274

182
-
/* Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision */
183
-
echo round( 1.55, 1, PHP_ROUND_HALF_EVEN); // 1.6
184
-
echo round( 1.54, 1, PHP_ROUND_HALF_EVEN); // 1.5
185
-
echo round(-1.55, 1, PHP_ROUND_HALF_EVEN); // -1.6
186
-
echo round(-1.54, 1, PHP_ROUND_HALF_EVEN); // -1.5
275
+
echo PHP_EOL;
276
+
echo 'Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision' . PHP_EOL;
277
+
var_dump(round( 1.55, 1, PHP_ROUND_HALF_EVEN));
278
+
var_dump(round(-1.55, 1, PHP_ROUND_HALF_EVEN));
187
279

188
-
/* Using PHP_ROUND_HALF_ODD with 1 decimal digit precision */
189
-
echo round( 1.55, 1, PHP_ROUND_HALF_ODD); // 1.5
190
-
echo round( 1.54, 1, PHP_ROUND_HALF_ODD); // 1.5
191
-
echo round(-1.55, 1, PHP_ROUND_HALF_ODD); // -1.5
192
-
echo round(-1.54, 1, PHP_ROUND_HALF_ODD); // -1.5
280
+
echo PHP_EOL;
281
+
echo 'Using PHP_ROUND_HALF_ODD with 1 decimal digit precision' . PHP_EOL;
282
+
var_dump(round( 1.55, 1, PHP_ROUND_HALF_ODD));
283
+
var_dump(round(-1.55, 1, PHP_ROUND_HALF_ODD));
193
284
?>
194
285
]]>
195
286
</programlisting>
287
+
&example.outputs;
288
+
<screen role="php">
289
+
<![CDATA[
290
+
Using PHP_ROUND_HALF_UP with 1 decimal digit precision
291
+
float(1.6)
292
+
float(-1.6)
293
+

294
+
Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision
295
+
float(1.5)
296
+
float(-1.5)
297
+

298
+
Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision
299
+
float(1.6)
300
+
float(-1.6)
301
+

302
+
Using PHP_ROUND_HALF_ODD with 1 decimal digit precision
303
+
float(1.5)
304
+
float(-1.5)
305
+
]]>
306
+
</screen>
196
307
</example>
197
308
</para>
198
309
</refsect1>
199
-
<refsect1 role="changelog">
200
-
&reftitle.changelog;
201
-
<para>
202
-
<informaltable>
203
-
<tgroup cols="2">
204
-
<thead>
205
-
<row>
206
-
<entry>&Version;</entry>
207
-
<entry>&Description;</entry>
208
-
</row>
209
-
</thead>
210
-
<tbody>
211
-
<row>
212
-
<entry>5.3.0</entry>
213
-
<entry>
214
-
The <parameter>mode</parameter> parameter was introduced.
215
-
</entry>
216
-
</row>
217
-
<row>
218
-
<entry>5.2.7</entry>
219
-
<entry>
220
-
The inner workings of <function>round</function> was changed
221
-
to conform to the C99 standard.
222
-
</entry>
223
-
</row>
224
-
</tbody>
225
-
</tgroup>
226
-
</informaltable>
227
-
</para>
228
-
</refsect1>
229
310

230
311
<refsect1 role="seealso">
231
312
&reftitle.seealso;
...
...
@@ -238,7 +319,6 @@ echo round(-1.54, 1, PHP_ROUND_HALF_ODD); // -1.5
238
319
</para>
239
320
</refsect1>
240
321
</refentry>
241
-

242
322
<!-- Keep this comment at the end of the file
243
323
Local variables:
244
324
mode: sgml
245
325



Tools (Spanish Manual)