switch.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<sect1 xml:id="control-structures.switch" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>switch</title>
 <?phpdoc print-version-for="switch"?>
 <simpara>
  The <literal>switch</literal> statement is similar to a series of
  IF statements on the same expression.  In many occasions, you may
  want to compare the same variable (or expression) with many
  different values, and execute a different piece of code depending
  on which value it equals to.  This is exactly what the
  <literal>switch</literal> statement is for.
 </simpara>
 <note>
  <simpara>
   Note that unlike some other languages, the
   <link linkend="control-structures.continue">continue</link> statement
   applies to <literal>switch</literal> and acts similar to <literal>break</literal>.  If you
   have a <literal>switch</literal> inside a loop and wish to continue to the next iteration of
   the outer loop, use <literal>continue 2</literal>.
  </simpara>
 </note>
 <note>
  <para>
   Note that switch/case does
   <link linkend="types.comparisions-loose">loose comparison</link>.
  </para>
 </note>

 <para>
  In the following example, each code block is equivalent.
  One uses a series of <literal>if</literal> and
  <literal>elseif</literal> statements, and the other a
  <literal>switch</literal> statement.  In each case, the output is the same.
  <example>
   <title><literal>switch</literal> structure</title>
   <programlisting role="php">
<![CDATA[
<?php
// This switch statement:

switch ($i) {
    case 0:
        echo "i equals 0";
        break;
    case 1:
        echo "i equals 1";
        break;
    case 2:
        echo "i equals 2";
        break;
}

// Is equivalent to:

if ($i == 0) {
    echo "i equals 0";
} elseif ($i == 1) {
    echo "i equals 1";
} elseif ($i == 2) {
    echo "i equals 2";
}
?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  It is important to understand how the <literal>switch</literal>
  statement is executed in order to avoid mistakes.  The
  <literal>switch</literal> statement executes line by line
  (actually, statement by statement).  In the beginning, no code is
  executed.  Only when a <literal>case</literal> statement is found
  whose expression evaluates to a value that matches the value of the
  <literal>switch</literal> expression does PHP begin to execute the
  statements.  PHP continues to execute the statements until the end
  of the <literal>switch</literal> block, or the first time it sees
  a <literal>break</literal> statement.  If you don't write a
  <literal>break</literal> statement at the end of a case's
  statement list, PHP will go on executing the statements of the
  following case.  For example:
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
switch ($i) {
    case 0:
        echo "i equals 0";
    case 1:
        echo "i equals 1";
    case 2:
        echo "i equals 2";
}
?>
]]>
   </programlisting>
  </informalexample>
 </para>
 <simpara>
  Here, if <varname>$i</varname> is equal to 0, PHP would execute all of the echo
  statements!  If <varname>$i</varname> is equal to 1, PHP would execute the last two
  echo statements. You would get the expected behavior ('i equals 2'
  would be displayed) only if <varname>$i</varname> is equal to 2.  Thus,
  it is important not to forget <literal>break</literal> statements
  (even though you may want to avoid supplying them on purpose under
  certain circumstances).
 </simpara>
 <simpara>
  In a <literal>switch</literal> statement, the condition is
  evaluated only once and the result is compared to each
  <literal>case</literal> statement. In an <literal>elseif</literal>
  statement, the condition is evaluated again. If your condition is
  more complicated than a simple compare and/or is in a tight loop,
  a <literal>switch</literal> may be faster.
 </simpara>
 <para>
  The statement list for a case can also be empty, which simply
  passes control into the statement list for the next case.
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
switch ($i) {
    case 0:
    case 1:
    case 2:
        echo "i is less than 3 but not negative";
        break;
    case 3:
        echo "i is 3";
}
?>
]]>
   </programlisting>
  </informalexample>
 </para>
 <para>
  A special case is the <literal>default</literal> case.  This case matches
  anything that wasn't matched by the other cases.  For example:
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
switch ($i) {
    case 0:
        echo "i equals 0";
        break;
    case 1:
        echo "i equals 1";
        break;
    case 2:
        echo "i equals 2";
        break;
    default:
       echo "i is not equal to 0, 1 or 2";
}
?>
]]>
   </programlisting>
  </informalexample>
  <note>
   <simpara>
    Multiple default cases will raise a
    <constant>E_COMPILE_ERROR</constant> error.
   </simpara>
  </note>
  <note>
   <simpara>
    Technically the <literal>default</literal> case may be listed
    in any order. It will only be used if no other case matches.
    However, by convention it is best to place it at the end as the
    last branch.
   </simpara>
  </note>
 </para>
 <para>
  If no <literal>case</literal> branch matches, and there is no <literal>default</literal>
  branch, then no code will be executed, just as if no <literal>if</literal> statement was true.
 </para>
 <para>
  A case value may be given as an expression. However, that expression will be
  evaluated on its own and then loosely compared with the switch value. That means
  it cannot be used for complex evaluations of the switch value.  For example:
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$target = 1;
$start = 3;

switch ($target) {
    case $start - 1:
        print "A";
        break;
    case $start - 2:
        print "B";
        break;
    case $start - 3:
        print "C";
        break;
    case $start - 4:
        print "D";
        break;
}

// Prints "B"
?>
]]>
   </programlisting>
  </informalexample>
 </para>
 <para>
  For more complex comparisons, the value &true; may be used as the switch value.
  Or, alternatively, <literal>if</literal>-<literal>else</literal> blocks instead of <literal>switch</literal>.
  <informalexample>
   <programlisting role="php">
    <![CDATA[
<?php
$offset = 1;
$start = 3;

switch (true) {
    case $start - $offset === 1:
        print "A";
        break;
    case $start - $offset === 2:
        print "B";
        break;
    case $start - $offset === 3:
        print "C";
        break;
    case $start - $offset === 4:
        print "D";
        break;
}

// Prints "B"
?>
]]>
   </programlisting>
  </informalexample>
 </para>
 <para>
  The alternative syntax for control structures is supported with
  switches. For more information, see <link
  linkend="control-structures.alternative-syntax">Alternative syntax
  for control structures</link>.
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
switch ($i):
    case 0:
        echo "i equals 0";
        break;
    case 1:
        echo "i equals 1";
        break;
    case 2:
        echo "i equals 2";
        break;
    default:
        echo "i is not equal to 0, 1 or 2";
endswitch;
?>
]]>
   </programlisting>
  </informalexample>
 </para>
 <para>
  It's possible to use a semicolon instead of a colon after a case like:
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
switch($beer)
{
    case 'tuborg';
    case 'carlsberg';
    case 'stella';
    case 'heineken';
        echo 'Good choice';
        break;
    default;
        echo 'Please make a new selection...';
        break;
}
?>
]]>
   </programlisting>
  </informalexample>
 </para>

 <sect2 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member>&match;</member>
   </simplelist>
  </para>
 </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
-->