integer.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
  &#8484; = {..., -2, -1, 0, 1, 2, ...}.
 </simpara>

 <para>
  See also:
 </para>

 <itemizedlist>
  <listitem>
   <simpara>
    <link linkend="book.gmp">Arbitrary length integer / GMP</link>
   </simpara>
  </listitem>
  <listitem>
   <simpara>
    <link linkend="language.types.float">Floating point numbers</link>
   </simpara>
  </listitem>
  <listitem>
   <simpara>
    <link linkend="book.bc">Arbitrary precision / BCMath</link>
   </simpara>
  </listitem>
 </itemizedlist>

 <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 7.4.0
   (previously, underscores have not been 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
-->