language/types/integer.xml
e587d0655e426f97b3fcb431453da5030e743b23
e587d0655e426f97b3fcb431453da5030e743b23
...
...
@@ -4,48 +4,34 @@
4
4
<title>Integers</title>
5
5
6
6
<simpara>
7
-
An <type>integer</type> is a number of the set
7
+
An <type>int</type> is a number of the set
8
8
ℤ = {..., -2, -1, 0, 1, 2, ...}.
9
9
</simpara>
10
10
11
-
<para>
12
-
See also:
13
-
</para>
14
-
15
-
<itemizedlist>
16
-
<listitem>
17
-
<simpara>
18
-
<link linkend="book.gmp">Arbitrary length integer / GMP</link>
19
-
</simpara>
20
-
</listitem>
21
-
<listitem>
22
-
<simpara>
23
-
<link linkend="language.types.float">Floating point numbers</link>
24
-
</simpara>
25
-
</listitem>
26
-
<listitem>
27
-
<simpara>
28
-
<link linkend="book.bc">Arbitrary precision / BCMath</link>
29
-
</simpara>
30
-
</listitem>
31
-
</itemizedlist>
11
+
<sect2 role="seealso">
12
+
&reftitle.seealso;
13
+
<para>
14
+
<simplelist>
15
+
<member><link linkend="language.types.float">Floating point numbers</link></member>
16
+
<member><link linkend="book.bc">Arbitrary precision / BCMath</link></member>
17
+
<member><link linkend="book.gmp">Arbitrary length integer / GMP</link></member>
18
+
</simplelist>
19
+
</para>
20
+
</sect2>
32
21
33
22
<sect2 xml:id="language.types.integer.syntax">
34
23
<title>Syntax</title>
35
24
36
25
<simpara>
37
-
<type>Integer</type>s can be specified in decimal (base 10), hexadecimal
26
+
<type>Int</type>s can be specified in decimal (base 10), hexadecimal
38
27
(base 16), octal (base 8) or binary (base 2) notation.
39
28
The <link linkend="language.operators.arithmetic">negation operator</link>
40
-
can be used to denote a negative <type>integer</type>.
29
+
can be used to denote a negative <type>int</type>.
41
30
</simpara>
42
31
43
-
<para>
44
-
Binary <type>integer</type> literals are available since PHP 5.4.0.
45
-
</para>
46
-
47
32
<para>
48
33
To use octal notation, precede the number with a <literal>0</literal> (zero).
34
+
As of PHP 8.1.0, octal notation can also be preceded with <literal>0o</literal> or <literal>0O</literal>.
49
35
To use hexadecimal notation precede the number with <literal>0x</literal>.
50
36
To use binary notation precede the number with <literal>0b</literal>.
51
37
</para>
...
...
@@ -57,11 +43,12 @@
57
43
58
44
<example>
59
45
<title>Integer literals</title>
60
-
<programlisting role="php">
46
+
<programlisting role="php" annotations="non-interactive">
61
47
<![CDATA[
62
48
<?php
63
49
$a = 1234; // decimal number
64
50
$a = 0123; // octal number (equivalent to 83 decimal)
51
+
$a = 0o123; // octal number (as of PHP 8.1.0)
65
52
$a = 0x1A; // hexadecimal number (equivalent to 26 decimal)
66
53
$a = 0b11111111; // binary number (equivalent to 255 decimal)
67
54
$a = 1_234_567; // decimal number (as of PHP 7.4.0)
...
...
@@ -71,8 +58,10 @@ $a = 1_234_567; // decimal number (as of PHP 7.4.0)
71
58
</example>
72
59
73
60
<para>
74
-
Formally, the structure for <type>integer</type> literals is as of PHP 7.4.0
75
-
(previously, underscores have not been allowed):
61
+
Formally, the structure for <type>int</type> literals is as of PHP 8.1.0
62
+
(previously, the <literal>0o</literal> or <literal>0O</literal> octal
63
+
prefixes were not allowed, and prior to PHP 7.4.0 the underscores were
64
+
not allowed):
76
65
</para>
77
66
78
67
<informalexample>
...
...
@@ -83,7 +72,7 @@ decimal : [1-9][0-9]*(_[0-9]+)*
83
72
84
73
hexadecimal : 0[xX][0-9a-fA-F]+(_[0-9a-fA-F]+)*
85
74
86
-
octal : 0[0-7]+(_[0-7]+)*
75
+
octal : 0[oO]?[0-7]+(_[0-7]+)*
87
76
88
77
binary : 0[bB][01]+(_[01]+)*
89
78
...
...
@@ -96,88 +85,56 @@ integer : decimal
96
85
</informalexample>
97
86
98
87
<para>
99
-
The size of an <type>integer</type> is platform-dependent, although a maximum
88
+
The size of an <type>int</type> is platform-dependent, although a maximum
100
89
value of about two billion is the usual value (that's 32 bits signed).
101
-
64-bit platforms usually have a maximum value of about 9E18, except on
102
-
Windows prior to PHP 7, where it was always 32 bit. PHP does not support
103
-
unsigned <type>integer</type>s. <type>Integer</type> size can be determined
90
+
64-bit platforms usually have a maximum value of about 9E18.
91
+
PHP does not support unsigned <type>int</type>s.
92
+
<type>int</type> size can be determined
104
93
using the constant <constant>PHP_INT_SIZE</constant>, maximum value using
105
-
the constant <constant>PHP_INT_MAX</constant> since PHP 5.0.5,
106
-
and minimum value using the constant <constant>PHP_INT_MIN</constant> since
107
-
PHP 7.0.0.
94
+
the constant <constant>PHP_INT_MAX</constant>,
95
+
and minimum value using the constant <constant>PHP_INT_MIN</constant>.
108
96
</para>
109
-
110
-
<warning>
111
-
<para>
112
-
Prior to PHP 7, if an invalid digit was given in an octal <type>integer</type>
113
-
(i.e. 8 or 9), the rest of the number was ignored. Since PHP 7, a parse error
114
-
is emitted.
115
-
</para>
116
-
</warning>
117
97
</sect2>
118
98
119
99
<sect2 xml:id="language.types.integer.overflow">
120
100
<title>Integer overflow</title>
121
101
122
102
<para>
123
-
If PHP encounters a number beyond the bounds of the <type>integer</type>
103
+
If PHP encounters a number beyond the bounds of the <type>int</type>
124
104
type, it will be interpreted as a <type>float</type> instead. Also, an
125
105
operation which results in a number beyond the bounds of the
126
-
<type>integer</type> type will return a <type>float</type> instead.
106
+
<type>int</type> type will return a <type>float</type> instead.
127
107
</para>
128
108
129
109
<example>
130
-
<title>Integer overflow on a 32-bit system</title>
110
+
<title>Integer overflow</title>
131
111
<programlisting role="php">
132
112
<![CDATA[
133
113
<?php
134
-
$large_number = 2147483647;
135
-
var_dump($large_number); // int(2147483647)
114
+
$large_number = 50000000000000000000;
115
+
var_dump($large_number); // float(5.0E+19)
136
116
137
-
$large_number = 2147483648;
138
-
var_dump($large_number); // float(2147483648)
139
-
140
-
$million = 1000000;
141
-
$large_number = 50000 * $million;
142
-
var_dump($large_number); // float(50000000000)
117
+
var_dump(PHP_INT_MAX + 1); // 32-bit system: float(2147483648)
118
+
// 64-bit system: float(9.2233720368548E+18)
143
119
?>
144
120
]]>
145
121
</programlisting>
146
122
</example>
123
+
</sect2>
147
124
148
-
<example>
149
-
<title>Integer overflow on a 64-bit system</title>
150
-
<programlisting role="php">
151
-
<![CDATA[
152
-
<?php
153
-
$large_number = 9223372036854775807;
154
-
var_dump($large_number); // int(9223372036854775807)
155
-
156
-
$large_number = 9223372036854775808;
157
-
var_dump($large_number); // float(9.2233720368548E+18)
158
-
159
-
$million = 1000000;
160
-
$large_number = 50000000000000 * $million;
161
-
var_dump($large_number); // float(5.0E+19)
162
-
?>
163
-
]]>
164
-
</programlisting>
165
-
</example>
125
+
<sect2 xml:id="language.types.integer.division">
126
+
<title>Integer division</title>
166
127
167
128
<para>
168
-
There is no <type>integer</type> division operator in PHP.
129
+
There is no <type>int</type> division operator in PHP, to achieve this
130
+
use the <function>intdiv</function> function.
169
131
<literal>1/2</literal> yields the <type>float</type> <literal>0.5</literal>.
170
-
The value can be cast to an <type>integer</type> to round it towards zero, or
132
+
The value can be cast to an <type>int</type> to round it towards zero, or
171
133
the <function>round</function> function provides finer control over rounding.
172
134
</para>
173
-
<note>
174
-
<simpara>
175
-
As of PHP 7.0.0, the function <function>intdiv</function> is available for
176
-
integer division.
177
-
</simpara>
178
-
</note>
179
135
180
-
<informalexample>
136
+
<example>
137
+
<title>Divisions</title>
181
138
<programlisting role="php">
182
139
<![CDATA[
183
140
<?php
...
...
@@ -187,23 +144,23 @@ var_dump(round(25/7)); // float(4)
187
144
?>
188
145
]]>
189
146
</programlisting>
190
-
</informalexample>
147
+
</example>
191
148
</sect2>
192
149
193
150
<sect2 xml:id="language.types.integer.casting">
194
151
<title>Converting to integer</title>
195
152
196
153
<simpara>
197
-
To explicitly convert a value to <type>integer</type>, use either the
154
+
To explicitly convert a value to <type>int</type>, use either the
198
155
<literal>(int)</literal> or <literal>(integer)</literal> casts. However, in
199
156
most cases the cast is not needed, since a value will be automatically
200
157
converted if an operator, function or control structure requires an
201
-
<type>integer</type> argument. A value can also be converted to
202
-
<type>integer</type> with the <function>intval</function> function.
158
+
<type>int</type> argument. A value can also be converted to
159
+
<type>int</type> with the <function>intval</function> function.
203
160
</simpara>
204
161
205
162
<simpara>
206
-
If a <type>resource</type> is converted to an <type>integer</type>, then
163
+
If a <type>resource</type> is converted to an <type>int</type>, then
207
164
the result will be the unique resource number assigned to the
208
165
<type>resource</type> by PHP at runtime.
209
166
</simpara>
...
...
@@ -227,29 +184,50 @@ var_dump(round(25/7)); // float(4)
227
184
</title>
228
185
229
186
<simpara>
230
-
When converting from <type>float</type> to <type>integer</type>, the number
187
+
When converting from <type>float</type> to <type>int</type>, the number
231
188
will be rounded <emphasis>towards zero</emphasis>.
189
+
As of PHP 8.1.0, a deprecation notice is emitted when implicitly converting a non-integral &float; to &integer; which loses precision.
232
190
</simpara>
233
191
192
+
<example>
193
+
<title>Casting from Float</title>
194
+
<programlisting role="php">
195
+
<![CDATA[
196
+
<?php
197
+
198
+
function foo($value): int {
199
+
return $value;
200
+
}
201
+
202
+
var_dump(foo(8.1)); // "Deprecated: Implicit conversion from float 8.1 to int loses precision" as of PHP 8.1.0
203
+
var_dump(foo(8.1)); // 8 prior to PHP 8.1.0
204
+
var_dump(foo(8.0)); // 8 in both cases
205
+
206
+
var_dump((int) 8.1); // 8 in both cases
207
+
var_dump(intval(8.1)); // 8 in both cases
208
+
?>
209
+
]]>
210
+
</programlisting>
211
+
</example>
212
+
234
213
<para>
235
-
If the float is beyond the boundaries of <type>integer</type> (usually
214
+
If the float is beyond the boundaries of <type>int</type> (usually
236
215
<literal>+/- 2.15e+9 = 2^31</literal> on 32-bit platforms and
237
-
<literal>+/- 9.22e+18 = 2^63</literal> on 64-bit platforms other than
238
-
Windows), the result is undefined, since the <type>float</type> doesn't
239
-
have enough precision to give an exact <type>integer</type> result. No
240
-
warning, not even a notice will be issued when this happens!
216
+
<literal>+/- 9.22e+18 = 2^63</literal> on 64-bit platforms),
217
+
the result is undefined, since the <type>float</type> doesn't
218
+
have enough precision to give an exact <type>int</type> result.
219
+
No warning, not even a notice will be issued when this happens!
241
220
</para>
242
221
243
222
<note>
244
223
<para>
245
-
As of PHP 7.0.0, instead of being undefined and platform-dependent, NaN and Infinity will
246
-
always be zero when cast to <type>integer</type>.
224
+
<literal>NaN</literal>, <literal>Inf</literal> and <literal>-Inf</literal> will always be zero when cast to <type>int</type>.
247
225
</para>
248
226
</note>
249
227
250
228
<warning>
251
229
<para>
252
-
Never cast an unknown fraction to <type>integer</type>, as this can
230
+
Never cast an unknown fraction to <type>int</type>, as this can
253
231
sometimes lead to unexpected results.
254
232
</para>
255
233
...
...
@@ -274,8 +252,11 @@ echo (int) ( (0.1+0.7) * 10 ); // echoes 7!
274
252
<title>From strings</title>
275
253
276
254
<simpara>
277
-
See <link linkend="language.types.string.conversion">String conversion to
278
-
numbers</link>
255
+
If the string is
256
+
<link linkend="language.types.numeric-strings">numeric</link>
257
+
or leading numeric then it will resolve to the
258
+
corresponding integer value, otherwise it is converted to zero
259
+
(<literal>0</literal>).
279
260
</simpara>
280
261
</sect3>
281
262
...
...
@@ -292,7 +273,7 @@ echo (int) ( (0.1+0.7) * 10 ); // echoes 7!
292
273
293
274
<caution>
294
275
<simpara>
295
-
The behaviour of converting to <type>integer</type> is undefined for other
276
+
The behaviour of converting to <type>int</type> is undefined for other
296
277
types. Do <emphasis>not</emphasis> rely on any observed behaviour, as it
297
278
can change without notice.
298
279
</simpara>
299
280