language/types/integer.xml
161dde4fe721309398dd324edbf02aec409f127b
...
...
@@ -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
&#8484; = {..., -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
32
<para>
44
-
Binary <type>integer</type> literals are available since PHP 5.4.0.
45
-
</para>
46
-

47
-
<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>
...
...
@@ -62,6 +48,7 @@
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,34 +85,25 @@ 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>
...
...
@@ -165,17 +145,12 @@ var_dump($large_number); // float(5.0E+19)
165
145
</example>
166
146

167
147
<para>
168
-
There is no <type>integer</type> division operator in PHP.
148
+
There is no <type>int</type> division operator in PHP, to achieve this
149
+
use the <function>intdiv</function> function.
169
150
<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
151
+
The value can be cast to an <type>int</type> to round it towards zero, or
171
152
the <function>round</function> function provides finer control over rounding.
172
153
</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
154

180
155
<informalexample>
181
156
<programlisting role="php">
...
...
@@ -194,16 +169,16 @@ var_dump(round(25/7)); // float(4)
194
169
<title>Converting to integer</title>
195
170

196
171
<simpara>
197
-
To explicitly convert a value to <type>integer</type>, use either the
172
+
To explicitly convert a value to <type>int</type>, use either the
198
173
<literal>(int)</literal> or <literal>(integer)</literal> casts. However, in
199
174
most cases the cast is not needed, since a value will be automatically
200
175
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.
176
+
<type>int</type> argument. A value can also be converted to
177
+
<type>int</type> with the <function>intval</function> function.
203
178
</simpara>
204
179

205
180
<simpara>
206
-
If a <type>resource</type> is converted to an <type>integer</type>, then
181
+
If a <type>resource</type> is converted to an <type>int</type>, then
207
182
the result will be the unique resource number assigned to the
208
183
<type>resource</type> by PHP at runtime.
209
184
</simpara>
...
...
@@ -227,29 +202,47 @@ var_dump(round(25/7)); // float(4)
227
202
</title>
228
203

229
204
<simpara>
230
-
When converting from <type>float</type> to <type>integer</type>, the number
205
+
When converting from <type>float</type> to <type>int</type>, the number
231
206
will be rounded <emphasis>towards zero</emphasis>.
207
+
As of PHP 8.1.0, a deprecation notice is emitted when implicitly converting a non-integral &float; to &integer; which loses precision.
232
208
</simpara>
233
209

210
+
<programlisting role="php">
211
+
<![CDATA[
212
+
<?php
213
+

214
+
function foo($value): int {
215
+
return $value;
216
+
}
217
+

218
+
var_dump(foo(8.1)); // "Deprecated: Implicit conversion from float 8.1 to int loses precision" as of PHP 8.1.0
219
+
var_dump(foo(8.1)); // 8 prior to PHP 8.1.0
220
+
var_dump(foo(8.0)); // 8 in both cases
221
+

222
+
var_dump((int)8.1); // 8 in both cases
223
+
var_dump(intval(8.1)); // 8 in both cases
224
+
?>
225
+
]]>
226
+
</programlisting>
227
+

234
228
<para>
235
-
If the float is beyond the boundaries of <type>integer</type> (usually
229
+
If the float is beyond the boundaries of <type>int</type> (usually
236
230
<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!
231
+
<literal>+/- 9.22e+18 = 2^63</literal> on 64-bit platforms),
232
+
the result is undefined, since the <type>float</type> doesn't
233
+
have enough precision to give an exact <type>int</type> result.
234
+
No warning, not even a notice will be issued when this happens!
241
235
</para>
242
236

243
237
<note>
244
238
<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>.
239
+
NaN and Infinity will always be zero when cast to <type>int</type>.
247
240
</para>
248
241
</note>
249
242

250
243
<warning>
251
244
<para>
252
-
Never cast an unknown fraction to <type>integer</type>, as this can
245
+
Never cast an unknown fraction to <type>int</type>, as this can
253
246
sometimes lead to unexpected results.
254
247
</para>
255
248

...
...
@@ -274,8 +267,11 @@ echo (int) ( (0.1+0.7) * 10 ); // echoes 7!
274
267
<title>From strings</title>
275
268

276
269
<simpara>
277
-
See <link linkend="language.types.string.conversion">String conversion to
278
-
numbers</link>
270
+
If the string is
271
+
<link linkend="language.types.numeric-strings">numeric</link>
272
+
or leading numeric then it will resolve to the
273
+
corresponding integer value, otherwise it is converted to zero
274
+
(<literal>0</literal>).
279
275
</simpara>
280
276
</sect3>
281
277

...
...
@@ -292,7 +288,7 @@ echo (int) ( (0.1+0.7) * 10 ); // echoes 7!
292
288

293
289
<caution>
294
290
<simpara>
295
-
The behaviour of converting to <type>integer</type> is undefined for other
291
+
The behaviour of converting to <type>int</type> is undefined for other
296
292
types. Do <emphasis>not</emphasis> rely on any observed behaviour, as it
297
293
can change without notice.
298
294
</simpara>
299
295