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

<sect1 xml:id="control-structures.switch" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title><literal>switch</literal></title>
 <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 switch and acts similar to <literal>break</literal>.  If you
   have a switch 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 comparision</link>.
  </para>
 </note>
 <para>
  The following two examples are two different ways to write the
  same thing, one using a series of <literal>if</literal> and
  <literal>elseif</literal> statements, and the other using the
  <literal>switch</literal> statement:
  <example>
   <title><literal>switch</literal> structure</title>
   <programlisting role="php">
<![CDATA[
<?php
if ($i == 0) {
    echo "i equals 0";
} elseif ($i == 1) {
    echo "i equals 1";
} elseif ($i == 2) {
    echo "i equals 2";
}

switch ($i) {
    case 0:
        echo "i equals 0";
        break;
    case 1:
        echo "i equals 1";
        break;
    case 2:
        echo "i equals 2";
        break;
}
?>
]]>
   </programlisting>
  </example>
  <example>
   <title><literal>switch</literal> structure allows usage of strings</title>
   <programlisting role="php">
<![CDATA[
<?php
switch ($i) {
    case "apple":
        echo "i is apple";
        break;
    case "bar":
        echo "i is bar";
        break;
    case "cake":
        echo "i is cake";
        break;
}
?>
]]>
   </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
  with 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>
 </para>
 <para>
  The <literal>case</literal> expression may be any expression that
  evaluates to a simple type, that is, integer or floating-point
  numbers and strings.  Arrays or objects cannot be used here unless
  they are dereferenced to a simple type.
 </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>
  Its 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 'heineken';
        echo 'Good choice';
    break;
    default;
        echo 'Please make a new selection...';
    break;
}
?>
]]>
   </programlisting>
  </informalexample>
 </para>
</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
-->