diff options
Diffstat (limited to 'docs/source/arduino/switchcase.rst')
| -rw-r--r-- | docs/source/arduino/switchcase.rst | 96 |
1 files changed, 66 insertions, 30 deletions
diff --git a/docs/source/arduino/switchcase.rst b/docs/source/arduino/switchcase.rst index 2ca2793..9f66d0a 100644 --- a/docs/source/arduino/switchcase.rst +++ b/docs/source/arduino/switchcase.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _arduino-switchcase: switch / case statements @@ -7,10 +9,7 @@ Like :ref:`if/else <arduino-else>` blocks, A ``switch`` statement controls program flow by allowing you to specify different code that should be executed under various cases. -Syntax ------- - -:: +The general syntax looks like this:: switch (var) { case val1: @@ -28,6 +27,7 @@ Where ``var`` is a variable whose value to investigate, and the ``val1``, ``val2`` after each ``case`` are constant values that ``var`` might be. + Description ----------- @@ -36,46 +36,82 @@ 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. -The ``break`` keyword exits the switch statement, and is typically -used at the end of each ``case``. 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. +Here's a more concrete example:: -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, as shown -above. + switch (var) { + case 1: + doThing1(); + break; + case 2: + doThing2(); + break; + } + afterTheSwitch(); -``switch`` statements are often used with an ``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. +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 +gets 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 gets exited, 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:: -Example -------- + 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. -:: +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: - //do something when var equals 1 + doThing1(); break; case 2: - //do something when var equals 2 + doThing2(); break; default: - // if nothing else matches, do the default - // default is optional + doSomethingElse(); } + afterTheSwitch(); -See also: ---------- - -`if...else <http://arduino.cc/en/Reference/Else>`_ +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 wasn't there. +``switch`` statements are often used with an ``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 <arduino-else>` -.. include:: cc-attribution.txt
\ No newline at end of file +.. include:: cc-attribution.txt |