aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/lang/cpp/scope.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/lang/cpp/scope.rst')
-rw-r--r--docs/source/lang/cpp/scope.rst120
1 files changed, 120 insertions, 0 deletions
diff --git a/docs/source/lang/cpp/scope.rst b/docs/source/lang/cpp/scope.rst
new file mode 100644
index 0000000..7b65bab
--- /dev/null
+++ b/docs/source/lang/cpp/scope.rst
@@ -0,0 +1,120 @@
+.. highlight:: cpp
+
+.. _lang-scope:
+
+Scope
+=====
+
+Variables in the C++ programming language, which Maple uses (all of
+your sketches are C++ programs in disguise), have a property called
+*scope*. Simply put, a variable's scope is made up of all of the
+lines where the variable can be used.
+
+Scope in C++ is a fairly complex topic, so we won't try to describe it
+in full here. Instead, we present a simplified view, describing two
+different kinds of scopes, *global* and *local*. For more detailed
+information, consult a C++ reference.
+
+Global and Local Variables
+--------------------------
+
+A global variable is one that can be "seen" by every function in a
+program. In the :ref:`Maple IDE <ide>`, any variable declared outside
+of a function (like :ref:`setup() <lang-setup>` and :ref:`loop()
+<lang-loop>`) is a global variable.
+
+A local variable can only be "seen" inside of a particular function.
+You can declare a variable to be local to a function by declaring it
+inside of the :ref:`curly braces <lang-curly-braces>` which enclose
+that function.
+
+When programs start to get larger and more complex, local variables
+are a useful way to ensure that a function has exclusive access to its
+own variables. This prevents programming errors when one function
+mistakenly modifies variables used by another function.
+
+It is also sometimes useful to declare and initialize a variable
+inside a :ref:`for <lang-for>` loop. This creates a variable that
+can only be accessed from inside the loop body.
+
+Example
+-------
+
+Here is an example sketch (which you can copy into the Maple IDE and
+run on your Maple) that illustrates the use of global and local
+variables, as well as declaring variables inside of a ``for`` loop.
+Be sure to open a :ref:`serial monitor <ide-serial-monitor>` after you
+:ref:`verify <ide-verify>` and :ref:`upload <ide-upload>` the sketch::
+
+ int globalVar; // any function will see this variable
+
+ void setup() {
+ // since "globalVar" is declared outside of any function,
+ // every function can "see" and use it:
+ globalVar = 50;
+
+ // the variables "i" and "d" declared inside the "loop" function
+ // can't be seen here. see what happens when you uncomment the
+ // following lines, and try to Verify (compile) the sketch:
+ //
+ // i = 16;
+ // SerialUSB.print("i = ");
+ // SerialUSB.println(i);
+ // d = 26.5;
+ // SerialUSB.print("d = ");
+ // SerialUSB.println(d);
+ }
+
+ void loop() {
+ // since "i" and "d" are declared inside of the "loop" function,
+ // they can only be seen and used from inside of it:
+ int i;
+ double d;
+
+ for (int j = 0; j < 5; j++) {
+ // variable i can be used anywhere inside the "loop" function;
+ // variable j can only be accessed inside the for-loop brackets:
+ i = j * j;
+ SerialUSB.print("i = ");
+ SerialUSB.println(i);
+ }
+
+ // globalVar can be accessed from anywhere. note how even
+ // though we set globalVar = 50 in the "setup" function, we can
+ // see that value here:
+ SerialUSB.print("globalVar = ");
+ SerialUSB.println(globalVar);
+
+ // d can be accessed from anywhere inside the "loop" function:
+ d = 26.5;
+ SerialUSB.print("d = ");
+ SerialUSB.print(d);
+ SerialUSB.println(" (before separateFunction())");
+
+ separateFunction();
+
+ // notice how even though separateFunction() has a variable
+ // named "d", it didn't touch our (local) variable which has
+ // the same name:
+ SerialUSB.print("d = ");
+ SerialUSB.print(d);
+ SerialUSB.println(" (after separateFunction())");
+ }
+
+ void separateFunction() {
+ // variable "d" here has the same name as variable "d" inside of
+ // the "loop" function, but since they're both _local_
+ // variables, they don't affect each other:
+ double d = 30.5;
+ SerialUSB.print("d = ");
+ SerialUSB.print(d);
+ SerialUSB.println(" (inside of separateFunction())");
+ }
+
+See Also
+--------
+
+- `C++ programming Wikibook <http://en.wikibooks.org/wiki/C%2B%2B_Programming/Programming_Languages/C%2B%2B/Code/Statements/Scope>`_.
+- Wikipedia article on `scope <http://en.wikipedia.org/wiki/Scope_%28programming%29>`_
+
+.. include:: cc-attribution.txt