<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 299538 $ -->
<sect1 xml:id="language.types.integer">
 <title>Integers</title>
 
 <simpara>
  An <type>integer</type> is a number of the set
  Z = {..., -2, -1, 0, 1, 2, ...}.
 </simpara>
  
 <para>
  See also:
 </para>

 <itemizedlist>
  <listitem>
   <simpara>
    <link linkend="ref.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="ref.bc">Arbitrary precision / BCMath</link>
   </simpara>
  </listitem>
 </itemizedlist>

 <sect2 xml:id="language.types.integer.syntax">
  <title>Syntax</title>

  <simpara>
   <type>Integer</type>s can be specified in decimal (base 10), hexadecimal
   (base 16), or octal (base 8) notation, optionally preceded by a sign
   (- or +).
  </simpara>

  <para>
   To use octal notation, precede the number with a <literal>0</literal> (zero).
   To use hexadecimal notation precede the number with <literal>0x</literal>.
  </para>

  <example>
   <title>Integer literals</title>
   <programlisting role="php">
<![CDATA[
<?php
$a = 1234; // decimal number
$a = -123; // a negative number
$a = 0123; // octal number (equivalent to 83 decimal)
$a = 0x1A; // hexadecimal number (equivalent to 26 decimal)
?>
]]>
   </programlisting>
  </example>

  <para>
   Formally, the structure for <type>integer</type> literals is:
  </para>
 
  <informalexample>
   <programlisting>
<![CDATA[
decimal     : [1-9][0-9]*
            | 0

hexadecimal : 0[xX][0-9a-fA-F]+

octal       : 0[0-7]+

integer     : [+-]?decimal
            | [+-]?hexadecimal
            | [+-]?octal
]]>
   </programlisting>
  </informalexample>

  <para>
   The size of an <type>integer</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>integer</type>s. <type>Integer</type> size
   can be determined using the constant <constant>PHP_INT_SIZE</constant>, and
   maximum value using the constant <constant>PHP_INT_MAX</constant> since
   PHP 4.4.0 and PHP 5.0.5.
  </para>

  <warning>
   <para>
    If an invalid digit is given in an octal <type>integer</type> (i.e. 8 or 9),
    the rest of the number is ignored.
   </para>

   <example>
    <title>Octal weirdness</title>
    <programlisting role="php">
<![CDATA[
<?php
var_dump(01090); // 010 octal = 8 decimal
?>
]]>
    </programlisting>
   </example>
  </warning>
 </sect2>

 <sect2 xml:id="language.types.integer.overflow">
  <title>Integer overflow</title>

  <para>
   If PHP encounters a number beyond the bounds of the <type>integer</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>integer</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>integer</type> division operator in PHP.
   <literal>1/2</literal> yields the <type>float</type> <literal>0.5</literal>.
   The value can be casted to an <type>integer</type> to round it downwards, 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>integer</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>integer</type> argument. A value can also be converted to
   <type>integer</type> with the <function>intval</function> function.
  </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>integer</type>, the number
    will be rounded <emphasis>towards zero</emphasis>.
   </simpara>
    
   <para>
    If the float is beyond the boundaries of <type>integer</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>integer</type> result. No warning, not even a notice
    will be issued when this happens!
   </para>
    
   <warning>
    <para>
     Never cast an unknown fraction to <type>integer</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>
    See <link linkend="language.types.string.conversion">String conversion to
    numbers</link>
   </simpara>
  </sect3>
   
  <sect3 xml:id="language.types.integer.casting.from-other">
   <title>From other types</title>

   <caution>
    <simpara>
     The behaviour of converting to <type>integer</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
-->