File: round.xml

package info (click to toggle)
php-doc 20241205~git.dfcbb86%2Bdfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: trixie
  • size: 70,956 kB
  • sloc: xml: 968,269; php: 23,883; javascript: 671; sh: 177; makefile: 37
file content (341 lines) | stat: -rw-r--r-- 9,298 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.round" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>round</refname>
  <refpurpose>Rounds a float</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
   <methodsynopsis>
   <type>float</type><methodname>round</methodname>
   <methodparam><type class="union"><type>int</type><type>float</type></type><parameter>num</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>precision</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer><constant>PHP_ROUND_HALF_UP</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   Returns the rounded value of <parameter>num</parameter> to
   specified <parameter>precision</parameter>
   (number of digits after the decimal point).
   <parameter>precision</parameter> can also be negative or zero (default).
  </para>
  <!-- It's not true
  <para>
   <caution>
    <simpara>
     When rounding on exact halves <function>round</function> rounds down on
     evens and up on odds.  If you want to always force it in one direction
     on a .5 (or .05 in your case) add or subtract a tiny fuzz factor.  The
     reason behind rounding half the values down and the other half up is to
     avoid the classical banking problem where if you always rounded down
     you would be stealing money from your customers, or if you always
     rounded up you would end up over time losing money.  By averaging it
     out through evens and odds you statistically break even.
    </simpara>
   </caution>
  </para>
  -->
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>num</parameter></term>
     <listitem>
      <para>
       The value to round.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>precision</parameter></term>
     <listitem>
      <para>
       The optional number of decimal digits to round to.
      </para>
      <para>
       If the <parameter>precision</parameter> is positive, <parameter>num</parameter> is
       rounded to <parameter>precision</parameter> significant digits after the decimal point.
      </para>
      <para>
       If the <parameter>precision</parameter> is negative, <parameter>num</parameter> is
       rounded to <parameter>precision</parameter> significant digits before the decimal point,
       i.e. to the nearest multiple of <code>pow(10, -$precision)</code>, e.g. for a
       <parameter>precision</parameter> of -1 <parameter>num</parameter> is rounded to tens,
       for a <parameter>precision</parameter> of -2 to hundreds, etc.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       Use one of the following constants to specify the mode in which rounding occurs.
       <informaltable>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>&Constants;</entry>
           <entry>&Description;</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>PHP_ROUND_HALF_UP</constant></entry>
           <entry>
            Rounds <parameter>num</parameter> away from zero when it is half way there,
            making 1.5 into 2 and -1.5 into -2.
           </entry>
          </row>
          <row>
           <entry><constant>PHP_ROUND_HALF_DOWN</constant></entry>
           <entry>
            Rounds <parameter>num</parameter> towards zero when it is half way there,
            making 1.5 into 1 and -1.5 into -1.
           </entry>
          </row>
          <row>
           <entry><constant>PHP_ROUND_HALF_EVEN</constant></entry>
           <entry>
            Rounds <parameter>num</parameter> towards the nearest even value when it is half way
            there, making both 1.5 and 2.5 into 2.
           </entry>
          </row>
          <row>
           <entry><constant>PHP_ROUND_HALF_ODD</constant></entry>
           <entry>
            Rounds <parameter>num</parameter> towards the nearest odd value when it is half way
            there, making 1.5 into 1 and 2.5 into 3.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </informaltable>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   The value rounded to the given <parameter>precision</parameter> as a &float;.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>num</parameter> no longer accepts internal objects which support
       numeric conversion.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>round</function> examples</title>
    <programlisting role="php">
<![CDATA[
<?php
var_dump(round(3.4));
var_dump(round(3.5));
var_dump(round(3.6));
var_dump(round(3.6, 0));
var_dump(round(5.045, 2));
var_dump(round(5.055, 2));
var_dump(round(345, -2));
var_dump(round(345, -3));
var_dump(round(678, -2));
var_dump(round(678, -3));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
float(3)
float(4)
float(4)
float(4)
float(5.05)
float(5.06)
float(300)
float(0)
float(700)
float(1000)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>How <parameter>precision</parameter> affects a float</title>
    <programlisting role="php">
<![CDATA[
<?php
$number = 135.79;

var_dump(round($number, 3));
var_dump(round($number, 2));
var_dump(round($number, 1));
var_dump(round($number, 0));
var_dump(round($number, -1));
var_dump(round($number, -2));
var_dump(round($number, -3));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
float(135.79)
float(135.79)
float(135.8)
float(136)
float(140)
float(100)
float(0)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><parameter>mode</parameter> examples</title>
    <programlisting role="php">
<![CDATA[
<?php
echo 'Rounding modes with 9.5' . PHP_EOL;
var_dump(round(9.5, 0, PHP_ROUND_HALF_UP));
var_dump(round(9.5, 0, PHP_ROUND_HALF_DOWN));
var_dump(round(9.5, 0, PHP_ROUND_HALF_EVEN));
var_dump(round(9.5, 0, PHP_ROUND_HALF_ODD));

echo PHP_EOL;
echo 'Rounding modes with 8.5' . PHP_EOL;
var_dump(round(8.5, 0, PHP_ROUND_HALF_UP));
var_dump(round(8.5, 0, PHP_ROUND_HALF_DOWN));
var_dump(round(8.5, 0, PHP_ROUND_HALF_EVEN));
var_dump(round(8.5, 0, PHP_ROUND_HALF_ODD));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
Rounding modes with 9.5
float(10)
float(9)
float(10)
float(9)

Rounding modes with 8.5
float(9)
float(8)
float(8)
float(9)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><parameter>mode</parameter> with <parameter>precision</parameter> examples</title>
    <programlisting role="php">
<![CDATA[
<?php
echo 'Using PHP_ROUND_HALF_UP with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_UP));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_UP));

echo PHP_EOL;
echo 'Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_DOWN));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_DOWN));

echo PHP_EOL;
echo 'Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_EVEN));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_EVEN));

echo PHP_EOL;
echo 'Using PHP_ROUND_HALF_ODD with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_ODD));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_ODD));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
Using PHP_ROUND_HALF_UP with 1 decimal digit precision
float(1.6)
float(-1.6)

Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision
float(1.5)
float(-1.5)

Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision
float(1.6)
float(-1.6)

Using PHP_ROUND_HALF_ODD with 1 decimal digit precision
float(1.5)
float(-1.5)
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>ceil</function></member>
    <member><function>floor</function></member>
    <member><function>number_format</function></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->