merge libmaple docs ("leaflabs-docs") into ./docs

In the past, libample documentation was forked out of this repository
because the documentation had increased in scope. For the librambutan,
and the rambutan project in general, we will try to keep documentation
closer to the source code, so the librambutan-specific documentation
should live here. Other sections of leaflabs-docs will be culled in a
following commit.

This merge attempts to maintain history by using a subtree strategy.
Followed directions at:

    http://nuclearsquid.com/writings/subtree-merging-and-you/

Full history for files should be accessible using the "--follow" flag to
git log, eg:

    git log --follow docs/source/adc.rst

It should be possible to pull patches from leaflabs-docs with:

    git pull -s subtree leaflabs-docs master

... at least until the docs in this repository diverge significantly.

1 files changed, 118 insertions, 0 deletions

diff --git a/docs/source/lang/cpp/switchcase.rst b/docs/source/lang/cpp/switchcase.rst
new file mode 100644
index 0000000..e31ccf3
--- /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:: /arduino-cc-attribution.txt