reference/strings/functions/number-format.xml
45042fef652f1b4e904e809fcbfcf31f6c60670b
...
...
@@ -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.number-format" xmlns:xlink="http://www.w3.org/1999/xlink">
3
+
<refentry xml:id="function.number-format" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>number_format</refname>
6
6
<refpurpose>Format a number with grouped thousands</refpurpose>
...
...
@@ -10,36 +10,13 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>string</type><methodname>number_format</methodname>
13
-
<methodparam><type>float</type><parameter>number</parameter></methodparam>
13
+
<methodparam><type>float</type><parameter>num</parameter></methodparam>
14
14
<methodparam choice="opt"><type>int</type><parameter>decimals</parameter><initializer>0</initializer></methodparam>
15
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>decimal_separator</parameter><initializer>"."</initializer></methodparam>
16
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>thousands_separator</parameter><initializer>","</initializer></methodparam>
15
17
</methodsynopsis>
16
-
<methodsynopsis>
17
-
<type>string</type><methodname>number_format</methodname>
18
-
<methodparam><type>float</type><parameter>number</parameter></methodparam>
19
-
<methodparam><type>int</type><parameter>decimals</parameter><initializer>0</initializer></methodparam>
20
-
<methodparam><type>string</type><parameter>dec_point</parameter><initializer>"."</initializer></methodparam>
21
-
<methodparam><type>string</type><parameter>thousands_sep</parameter><initializer>","</initializer></methodparam>
22
-
</methodsynopsis>
23
-
<para>
24
-
This function accepts either one, two, or four parameters (not three):
25
-
</para>
26
-
<para>
27
-
If only one parameter is given,
28
-
<parameter>number</parameter> will be formatted without decimals,
29
-
but with a comma (",") between every group of thousands.
30
-
</para>
31
18
<para>
32
-
If two parameters are given, <parameter>number</parameter> will
33
-
be formatted with <parameter>decimals</parameter> decimals with a
34
-
dot (".") in front, and a comma (",") between every group of
35
-
thousands.
36
-
</para>
37
-
<para>
38
-
If all four parameters are given, <parameter>number</parameter>
39
-
will be formatted with <parameter>decimals</parameter> decimals,
40
-
<parameter>dec_point</parameter> instead of a dot (".") before
41
-
the decimals and <parameter>thousands_sep</parameter> instead of
42
-
a comma (",") between every group of thousands.
19
+
Formats a number with grouped thousands and optionally decimal digits using the rounding half up rule.
43
20
</para>
44
21
</refsect1>
45
22

...
...
@@ -48,7 +25,7 @@
48
25
<para>
49
26
<variablelist>
50
27
<varlistentry>
51
-
<term><parameter>number</parameter></term>
28
+
<term><parameter>num</parameter></term>
52
29
<listitem>
53
30
<para>
54
31
The number being formatted.
...
...
@@ -59,12 +36,19 @@
59
36
<term><parameter>decimals</parameter></term>
60
37
<listitem>
61
38
<para>
62
-
Sets the number of decimal points.
39
+
Sets the number of decimal digits.
40
+
If <literal>0</literal>, the <parameter>decimal_separator</parameter> is
41
+
omitted from the return value.
42
+
As of PHP 8.3.0, when the value is negative, <parameter>num</parameter>
43
+
is rounded to <parameter>decimals</parameter> significant digits before
44
+
the decimal point.
45
+
Prior to PHP 8.3.0, negative values were ignored and handled the
46
+
same as <literal>0</literal>.
63
47
</para>
64
48
</listitem>
65
49
</varlistentry>
66
50
<varlistentry>
67
-
<term><parameter>dec_point</parameter></term>
51
+
<term><parameter>decimal_separator</parameter></term>
68
52
<listitem>
69
53
<para>
70
54
Sets the separator for the decimal point.
...
...
@@ -72,7 +56,7 @@
72
56
</listitem>
73
57
</varlistentry>
74
58
<varlistentry>
75
-
<term><parameter>thousands_sep</parameter></term>
59
+
<term><parameter>thousands_separator</parameter></term>
76
60
<listitem>
77
61
<para>
78
62
Sets the thousands separator.
...
...
@@ -86,7 +70,7 @@
86
70
<refsect1 role="returnvalues">
87
71
&reftitle.returnvalues;
88
72
<para>
89
-
A formatted version of <parameter>number</parameter>.
73
+
A formatted version of <parameter>num</parameter>.
90
74
</para>
91
75
</refsect1>
92
76

...
...
@@ -103,12 +87,24 @@
103
87
</thead>
104
88
<tbody>
105
89
<row>
106
-
<entry>5.4.0</entry>
90
+
<entry>8.3.0</entry>
91
+
<entry>
92
+
Added handling of negative values for <parameter>decimals</parameter>.
93
+
</entry>
94
+
</row>
95
+
<row>
96
+
<entry>8.0.0</entry>
107
97
<entry>
108
-
This function now supports multiple bytes in
109
-
<parameter>dec_point</parameter> and
110
-
<parameter>thousands_sep</parameter>. Only the first byte of each
111
-
separator was used in older versions.
98
+
Prior to this version, <function>number_format</function> accepted
99
+
one, two, or four parameters (but not three).
100
+
</entry>
101
+
</row>
102
+
<row>
103
+
<entry>7.2.0</entry>
104
+
<entry>
105
+
<function>number_format</function> was changed to not being able to return
106
+
<literal>-0</literal>, previously <literal>-0</literal> could be returned
107
+
for cases like where <parameter>num</parameter> would be <literal>-0.01</literal>.
112
108
</entry>
113
109
</row>
114
110
</tbody>
...
...
@@ -125,7 +121,7 @@
125
121
<para>
126
122
For instance, French notation usually use two decimals,
127
123
comma (',') as decimal separator, and space (' ') as
128
-
thousand separator. The following example demonstrates various way to format a number:
124
+
thousand separator. The following example demonstrates various ways to format a number:
129
125
</para>
130
126
<programlisting role="php">
131
127
<![CDATA[
...
...
@@ -134,17 +130,17 @@
134
130
$number = 1234.56;
135
131

136
132
// english notation (default)
137
-
$english_format_number = number_format($number);
133
+
echo number_format($number), PHP_EOL;
138
134
// 1,235
139
135

140
136
// French notation
141
-
$nombre_format_francais = number_format($number, 2, ',', ' ');
137
+
echo number_format($number, 2, ',', ' '), PHP_EOL;
142
138
// 1 234,56
143
139

144
140
$number = 1234.5678;
145
141

146
142
// english notation without thousands separator
147
-
$english_format_number = number_format($number, 2, '.', '');
143
+
echo number_format($number, 2, '.', ''), PHP_EOL;
148
144
// 1234.57
149
145

150
146
?>
...
...
@@ -152,32 +148,32 @@ $english_format_number = number_format($number, 2, '.', '');
152
148
</programlisting>
153
149
</example>
154
150
</para>
155
-
</refsect1>
156
-
157
-
<refsect1 role="changelog">
158
-
&reftitle.changelog;
159
-
<para>
160
-
<informaltable>
161
-
<tgroup cols="2">
162
-
<thead>
163
-
<row>
164
-
<entry>&Version;</entry>
165
-
<entry>&Description;</entry>
166
-
</row>
167
-
</thead>
168
-
<tbody>
169
-
<row>
170
-
<entry>7.2.0</entry>
171
-
<entry>
172
-
<function>number_format</function> was changed to not being able to return
173
-
<literal>-0</literal>, previously <literal>-0</literal> could be returned
174
-
for cases like where <parameter>number</parameter> would be <literal>-0.01</literal>.
175
-
</entry>
176
-
</row>
177
-
</tbody>
178
-
</tgroup>
179
-
</informaltable>
180
-
</para>
151
+
<example>
152
+
<title>A negative value for <parameter>decimals</parameter></title>
153
+
<simpara>
154
+
As of PHP 8.3.0, a negative value for <parameter>decimals</parameter>
155
+
is used to round the number of significant digits before the decimal
156
+
point.
157
+
</simpara>
158
+
<programlisting role="php">
159
+
<![CDATA[
160
+
<?php
161
+
$number = "1234.5678";
162
+
var_dump(number_format($number, -1));
163
+
var_dump(number_format($number, -2));
164
+
var_dump(number_format($number, -3));
165
+
?>
166
+
]]>
167
+
</programlisting>
168
+
&example.outputs;
169
+
<screen>
170
+
<![CDATA[
171
+
string(5) "1,230"
172
+
string(5) "1,200"
173
+
string(5) "1,000"
174
+
]]>
175
+
</screen>
176
+
</example>
181
177
</refsect1>
182
178
183
179
<refsect1 role="seealso">
184
180



Translation status