increment.xml

<?xml version="1.0" encoding="utf-8"?>
<sect1 xml:id="language.operators.increment">
 <title>Incrementing/Decrementing Operators</title>
 <titleabbrev>Increment and Decrement</titleabbrev>
 <para>
  PHP supports pre- and post-increment and decrement operators.
  Those unary operators allow to increment or decrement the value by one.
 </para>
 <table>
  <title>Increment/decrement Operators</title>
  <tgroup cols="3">
   <thead>
    <row>
     <entry>Example</entry>
     <entry>Name</entry>
     <entry>Effect</entry>
    </row>
   </thead>
   <tbody>
    <row>
     <entry>++$a</entry>
     <entry>Pre-increment</entry>
     <entry>Increments <varname>$a</varname> by one, then returns <varname>$a</varname>.</entry>
    </row>
    <row>
     <entry>$a++</entry>
     <entry>Post-increment</entry>
     <entry>Returns <varname>$a</varname>, then increments <varname>$a</varname> by one.</entry>
    </row>
    <row>
     <entry>--$a</entry>
     <entry>Pre-decrement</entry>
     <entry>Decrements <varname>$a</varname> by one, then returns <varname>$a</varname>.</entry>
    </row>
    <row>
     <entry>$a--</entry>
     <entry>Post-decrement</entry>
     <entry>Returns <varname>$a</varname>, then decrements <varname>$a</varname> by one.</entry>
    </row>
   </tbody>
  </tgroup>
 </table>

 <para>
  Here's a simple example script:
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
echo 'Post-increment:', PHP_EOL;
$a = 5;
var_dump($a++);
var_dump($a);

echo 'Pre-increment:', PHP_EOL;
$a = 5;
var_dump(++$a);
var_dump($a);

echo 'Post-decrement:', PHP_EOL;
$a = 5;
var_dump($a--);
var_dump($a);

echo 'Pre-decrement:', PHP_EOL;
$a = 5;
var_dump(--$a);
var_dump($a);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Post-increment:
int(5)
int(6)
Pre-increment:
int(6)
int(6)
Post-decrement:
int(5)
int(4)
Pre-decrement:
int(4)
int(4)
]]>
   </screen>
  </informalexample>

  <warning>
   <para>
    The increment and decrement operators have no effect on values
    of type <type>bool</type>.
    A <constant>E_WARNING</constant> is emitted as of PHP 8.3.0,
    because this will implicitly cast the value to <type>int</type> in the future.
   </para>
   <para>
    The decrement operator has no effect on values
    of type <type>null</type>.
    A <constant>E_WARNING</constant> is emitted as of PHP 8.3.0,
    because this will implicitly cast the value to <type>int</type> in the future.
   </para>
   <para>
    The decrement operator has no effect on non-
    <link linkend="language.types.numeric-strings">numeric string</link>.
    A <constant>E_WARNING</constant> is emitted as of PHP 8.3.0,
    because a <classname>TypeError</classname> will be thrown in the future.
   </para>
  </warning>
  <note>
   <para>
    Internal objects that support overloading addition and/or subtraction
    can also be incremented and/or decremented.
    One such internal object is <classname>GMP</classname>.
   </para>
  </note>
 </para>

 <sect2 xml:id="language.operators.increment.string">
  <title>PERL string increment feature</title>
  <warning>
   <simpara>
    This feature is soft-deprecated as of PHP 8.3.0.
    The <function>str_increment</function> function should be used instead.
   </simpara>
  </warning>

  <para>
   It is possible to increment a non-
   <link linkend="language.types.numeric-strings">numeric string</link>
   in PHP. The string must be an alphanumerical ASCII string.
   Which increments letters up to the next letter, when reaching the letter
   <literal>Z</literal> the increment is carried to the value on the left.
   For example, <code>$a = 'Z'; $a++;</code> turns <varname>$a</varname>
   into <literal>'AA'</literal>.
  </para>

  <example>
   <title>PERL string increment example</title>
   <programlisting role="php">
<![CDATA[
<?php
echo '== Alphabetic strings ==' . PHP_EOL;
$s = 'W';
for ($n=0; $n<6; $n++) {
    echo ++$s . PHP_EOL;
}
// Alphanumeric strings behave differently
echo '== Alphanumeric strings ==' . PHP_EOL;
$d = 'A8';
for ($n=0; $n<6; $n++) {
    echo ++$d . PHP_EOL;
}
$d = 'A08';
for ($n=0; $n<6; $n++) {
    echo ++$d . PHP_EOL;
}
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
== Alphabetic strings ==
X
Y
Z
AA
AB
AC
== Alphanumeric strings ==
A9
B0
B1
B2
B3
B4
A09
A10
A11
A12
A13
A14
]]>
   </screen>
  </example>

  <warning>
   <para>
    If the alphanumerical string can be interpreted as a
    <link linkend="language.types.numeric-strings">numeric string</link>
    it will be cast to an <type>int</type> or <type>float</type>.
    This is particularly an issue with strings that look like a floating point
    numbers written in exponential notation.
    The <function>str_increment</function> function does not suffer from
    these implicit type cast.
   </para>
   <example>
    <title>Alphanumerical string converted to float</title>
    <programlisting role="php">
<![CDATA[
<?php
$s = "5d9";
var_dump(++$s);
var_dump(++$s);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
string(3) "5e0"
float(6)
]]>
    </screen>
    <para>
     This is because the value <literal>"5e0"</literal> is interpreted
     as a <type>float</type> and cast to the value <literal>5.0</literal>
     before being incremented.
    </para>
   </example>
  </warning>
 </sect2>
</sect1>