mirror of
https://github.com/php/doc-en.git
synced 2026-03-27 09:12:15 +01:00
161dde4fe7
This commit rewrites the whole type section to (hopefully) be better structured and future proof for further additions to the type system. * Each type now gets their individual page instead of being shoved in the type declaration page. * A type system page is added which describes PHP's type system, regardless if it is possible to declare the type in userland or not. Therefore, the type declaration page only has information related to writing type declarations in userland. * The description of strict_type and the type coercion is moved into the type juggling page. * Remove outdated information in string implementation section * Add paragraph about using non string in string context can throw Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
321 lines
9.3 KiB
XML
321 lines
9.3 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<sect1 xml:id="language.types.integer">
|
|
<title>Integers</title>
|
|
|
|
<simpara>
|
|
An <type>int</type> is a number of the set
|
|
ℤ = {..., -2, -1, 0, 1, 2, ...}.
|
|
</simpara>
|
|
|
|
<sect2 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><link linkend="language.types.float">Floating point numbers</link></member>
|
|
<member><link linkend="book.bc">Arbitrary precision / BCMath</link></member>
|
|
<member><link linkend="book.gmp">Arbitrary length integer / GMP</link></member>
|
|
</simplelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="language.types.integer.syntax">
|
|
<title>Syntax</title>
|
|
|
|
<simpara>
|
|
<type>Int</type>s can be specified in decimal (base 10), hexadecimal
|
|
(base 16), octal (base 8) or binary (base 2) notation.
|
|
The <link linkend="language.operators.arithmetic">negation operator</link>
|
|
can be used to denote a negative <type>int</type>.
|
|
</simpara>
|
|
|
|
<para>
|
|
To use octal notation, precede the number with a <literal>0</literal> (zero).
|
|
As of PHP 8.1.0, octal notation can also be preceded with <literal>0o</literal> or <literal>0O</literal>.
|
|
To use hexadecimal notation precede the number with <literal>0x</literal>.
|
|
To use binary notation precede the number with <literal>0b</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
As of PHP 7.4.0, integer literals may contain underscores (<literal>_</literal>) between digits,
|
|
for better readability of literals. These underscores are removed by PHP's scanner.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Integer literals</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$a = 1234; // decimal number
|
|
$a = 0123; // octal number (equivalent to 83 decimal)
|
|
$a = 0o123; // octal number (as of PHP 8.1.0)
|
|
$a = 0x1A; // hexadecimal number (equivalent to 26 decimal)
|
|
$a = 0b11111111; // binary number (equivalent to 255 decimal)
|
|
$a = 1_234_567; // decimal number (as of PHP 7.4.0)
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
Formally, the structure for <type>int</type> literals is as of PHP 8.1.0
|
|
(previously, the <literal>0o</literal> or <literal>0O</literal> octal
|
|
prefixes were not allowed, and prior to PHP 7.4.0 the underscores were
|
|
not allowed):
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting>
|
|
<![CDATA[
|
|
decimal : [1-9][0-9]*(_[0-9]+)*
|
|
| 0
|
|
|
|
hexadecimal : 0[xX][0-9a-fA-F]+(_[0-9a-fA-F]+)*
|
|
|
|
octal : 0[oO]?[0-7]+(_[0-7]+)*
|
|
|
|
binary : 0[bB][01]+(_[01]+)*
|
|
|
|
integer : decimal
|
|
| hexadecimal
|
|
| octal
|
|
| binary
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
|
|
<para>
|
|
The size of an <type>int</type> is platform-dependent, although a maximum
|
|
value of about two billion is the usual value (that's 32 bits signed).
|
|
64-bit platforms usually have a maximum value of about 9E18.
|
|
PHP does not support unsigned <type>int</type>s.
|
|
<type>int</type> size can be determined
|
|
using the constant <constant>PHP_INT_SIZE</constant>, maximum value using
|
|
the constant <constant>PHP_INT_MAX</constant>,
|
|
and minimum value using the constant <constant>PHP_INT_MIN</constant>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="language.types.integer.overflow">
|
|
<title>Integer overflow</title>
|
|
|
|
<para>
|
|
If PHP encounters a number beyond the bounds of the <type>int</type>
|
|
type, it will be interpreted as a <type>float</type> instead. Also, an
|
|
operation which results in a number beyond the bounds of the
|
|
<type>int</type> type will return a <type>float</type> instead.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Integer overflow on a 32-bit system</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$large_number = 2147483647;
|
|
var_dump($large_number); // int(2147483647)
|
|
|
|
$large_number = 2147483648;
|
|
var_dump($large_number); // float(2147483648)
|
|
|
|
$million = 1000000;
|
|
$large_number = 50000 * $million;
|
|
var_dump($large_number); // float(50000000000)
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Integer overflow on a 64-bit system</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$large_number = 9223372036854775807;
|
|
var_dump($large_number); // int(9223372036854775807)
|
|
|
|
$large_number = 9223372036854775808;
|
|
var_dump($large_number); // float(9.2233720368548E+18)
|
|
|
|
$million = 1000000;
|
|
$large_number = 50000000000000 * $million;
|
|
var_dump($large_number); // float(5.0E+19)
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
There is no <type>int</type> division operator in PHP, to achieve this
|
|
use the <function>intdiv</function> function.
|
|
<literal>1/2</literal> yields the <type>float</type> <literal>0.5</literal>.
|
|
The value can be cast to an <type>int</type> to round it towards zero, or
|
|
the <function>round</function> function provides finer control over rounding.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
var_dump(25/7); // float(3.5714285714286)
|
|
var_dump((int) (25/7)); // int(3)
|
|
var_dump(round(25/7)); // float(4)
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="language.types.integer.casting">
|
|
<title>Converting to integer</title>
|
|
|
|
<simpara>
|
|
To explicitly convert a value to <type>int</type>, use either the
|
|
<literal>(int)</literal> or <literal>(integer)</literal> casts. However, in
|
|
most cases the cast is not needed, since a value will be automatically
|
|
converted if an operator, function or control structure requires an
|
|
<type>int</type> argument. A value can also be converted to
|
|
<type>int</type> with the <function>intval</function> function.
|
|
</simpara>
|
|
|
|
<simpara>
|
|
If a <type>resource</type> is converted to an <type>int</type>, then
|
|
the result will be the unique resource number assigned to the
|
|
<type>resource</type> by PHP at runtime.
|
|
</simpara>
|
|
|
|
<simpara>
|
|
See also <link linkend="language.types.type-juggling">Type Juggling</link>.
|
|
</simpara>
|
|
|
|
<sect3 xml:id="language.types.integer.casting.from-boolean">
|
|
<title>From <link linkend="language.types.boolean">booleans</link></title>
|
|
|
|
<simpara>
|
|
&false; will yield <literal>0</literal> (zero), and &true; will yield
|
|
<literal>1</literal> (one).
|
|
</simpara>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="language.types.integer.casting.from-float">
|
|
<title>
|
|
From <link linkend="language.types.float">floating point numbers</link>
|
|
</title>
|
|
|
|
<simpara>
|
|
When converting from <type>float</type> to <type>int</type>, the number
|
|
will be rounded <emphasis>towards zero</emphasis>.
|
|
As of PHP 8.1.0, a deprecation notice is emitted when implicitly converting a non-integral &float; to &integer; which loses precision.
|
|
</simpara>
|
|
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
function foo($value): int {
|
|
return $value;
|
|
}
|
|
|
|
var_dump(foo(8.1)); // "Deprecated: Implicit conversion from float 8.1 to int loses precision" as of PHP 8.1.0
|
|
var_dump(foo(8.1)); // 8 prior to PHP 8.1.0
|
|
var_dump(foo(8.0)); // 8 in both cases
|
|
|
|
var_dump((int)8.1); // 8 in both cases
|
|
var_dump(intval(8.1)); // 8 in both cases
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
|
|
<para>
|
|
If the float is beyond the boundaries of <type>int</type> (usually
|
|
<literal>+/- 2.15e+9 = 2^31</literal> on 32-bit platforms and
|
|
<literal>+/- 9.22e+18 = 2^63</literal> on 64-bit platforms),
|
|
the result is undefined, since the <type>float</type> doesn't
|
|
have enough precision to give an exact <type>int</type> result.
|
|
No warning, not even a notice will be issued when this happens!
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
NaN and Infinity will always be zero when cast to <type>int</type>.
|
|
</para>
|
|
</note>
|
|
|
|
<warning>
|
|
<para>
|
|
Never cast an unknown fraction to <type>int</type>, as this can
|
|
sometimes lead to unexpected results.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
echo (int) ( (0.1+0.7) * 10 ); // echoes 7!
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
|
|
<para>
|
|
See also the <link linkend="warn.float-precision">warning about float
|
|
precision</link>.
|
|
</para>
|
|
</warning>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="language.types.integer.casting.from-string">
|
|
<title>From strings</title>
|
|
|
|
<simpara>
|
|
If the string is
|
|
<link linkend="language.types.numeric-strings">numeric</link>
|
|
or leading numeric then it will resolve to the
|
|
corresponding integer value, otherwise it is converted to zero
|
|
(<literal>0</literal>).
|
|
</simpara>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="language.types.integer.casting-from-null">
|
|
<title>From <type>NULL</type></title>
|
|
|
|
<simpara>
|
|
&null; is always converted to zero (<literal>0</literal>).
|
|
</simpara>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="language.types.integer.casting.from-other">
|
|
<title>From other types</title>
|
|
|
|
<caution>
|
|
<simpara>
|
|
The behaviour of converting to <type>int</type> is undefined for other
|
|
types. Do <emphasis>not</emphasis> rely on any observed behaviour, as it
|
|
can change without notice.
|
|
</simpara>
|
|
</caution>
|
|
</sect3>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<!-- 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
|
|
-->
|