From a0549b4a15a7093f990fffa4bc1d2d52ec1c16e2 Mon Sep 17 00:00:00 2001
From: Hanna Mendes Levitin <hanna@anomaly-3.local>
Date: Wed, 1 Dec 2010 03:37:07 -0600
Subject: docs, now with style

---
 docs/source/lang/cpp/switchcase.rst | 118 ++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)
 create mode 100644 docs/source/lang/cpp/switchcase.rst

(limited to 'docs/source/lang/cpp/switchcase.rst')

diff --git a/docs/source/lang/cpp/switchcase.rst b/docs/source/lang/cpp/switchcase.rst
new file mode 100644
index 0000000..b484bc5
--- /dev/null
+++ b/docs/source/lang/cpp/switchcase.rst
@@ -0,0 +1,118 @@
+.. highlight:: cpp
+
+.. _lang-switchcase:
+
+``switch``\ /\ ``case``
+=======================
+
+Like :ref:`if <lang-if>` statements, A ``switch`` statement controls
+program flow by allowing you to specify different code that should be
+executed under various cases.
+
+The general syntax looks like this::
+
+    switch (var) {
+    case val1:
+        // statements
+        break;
+    case val2:
+        // statements
+        break;
+    ...
+    default:
+        // statements
+    }
+
+Where ``var`` is a variable whose value to investigate, and the
+``val1``, ``val2`` after each ``case`` are constant values that
+``var`` might be.
+
+Description
+-----------
+
+A ``switch`` statement compares the value of a variable to the values
+specified in ``case`` statements. When a ``case`` statement is found
+whose value matches that of the variable, the code in that case
+statement is run.
+
+Here's a more concrete example::
+
+      switch (var) {
+      case 1:
+          doThing1();
+          break;
+      case 2:
+          doThing2();
+          break;
+      }
+      afterTheSwitch();
+
+In the above example, if ``var == 1``, then the code beginning on the
+line after ``case 1`` gets executed.  That is, if ``var`` is one,
+``doThing1()`` gets called first, and then the ``break`` statement is
+executed.
+
+The ``break`` keyword exits the ``switch`` statement, and is typically
+used at the end of each ``case``.  Since there is a ``break`` at the
+end of ``case 1``, the ``switch`` statement exits, and the next line
+to be run is the one which calls ``afterTheSwitch()``.
+
+Without a ``break``, the ``switch`` statement will continue executing
+the following ``case`` expressions ("falling-through") until a
+``break`` (or the end of the switch statement) is reached.  Let's
+pretend the ``switch`` looked like this instead::
+
+      switch (var) {
+      case 1:
+          doThing1();
+          // no break statement anymore
+      case 2:
+          doThing2();
+          break;
+      }
+      afterTheSwitch();
+
+Now, if ``var`` is one, ``doThing1()`` gets executed like before.
+However, without a ``break``, the code would continue to be executed
+line-by-line, so ``doThing2()`` would be called next.  At this point,
+a ``break`` has been reached, so the program continues by calling
+``afterTheSwitch()``.  This is usually not what you want, which is why
+each ``case`` usually has a ``break`` at the end.
+
+.. _lang-switchcase-default:
+
+Writing "``default:``" instead of a ``case`` statement allows you to
+specify what to do if none of the ``case`` statements matches.  Having
+a ``default`` is optional (you can leave it out), but if you have one,
+it must appear after all of the ``case`` statements.  Let's add a
+``default`` to the ``switch`` we've been discussing::
+
+      switch (var) {
+      case 1:
+          doThing1();
+          break;
+      case 2:
+          doThing2();
+          break;
+      default:
+          doSomethingElse();
+      }
+      afterTheSwitch();
+
+If ``var`` is one, then ``doThing1()`` gets called.  If ``var`` is
+two, ``doThing2()`` gets called.  If ``var`` is anything else,
+``doSomethingElse()`` gets called.  As stated above, a ``default`` is
+optional.  If you're missing one and none of the ``case`` statements
+match, the ``switch`` does nothing at all, as if it weren't there.
+
+``switch`` statements are often used with an :ref:`enum <lang-enum>`
+value as the variable to compare.  In this case, you can write down
+all of the values the ``enum`` takes as ``case`` statements, and be
+sure you've covered all the possibilities.
+
+See also:
+---------
+
+- :ref:`if/else <lang-if>`
+
+.. include:: cc-attribution.txt
-- 
cgit v1.2.3