docs, now with style

1 files changed, 170 insertions, 0 deletions

diff --git a/source/lang/cpp/variables.rst b/source/lang/cpp/variables.rst
new file mode 100644
index 0000000..9094cd5
--- /dev/null
+++ b/source/lang/cpp/variables.rst
@@ -0,0 +1,170 @@
+.. highlight:: cpp
+
+.. _lang-variables:
+
+Variables
+=========
+
+A variable is a way of naming and storing a value for later use by
+the program, such as data from a sensor or an intermediate value
+used in a calculation.
+
+.. contents:: Contents
+   :local:
+
+.. _lang-variables-declaring:
+
+Declaring Variables
+-------------------
+
+Before they are used, all variables have to be *declared*. Declaring a
+variable means defining its type, giving it a name, and (optionally)
+giving it an initial value (this is often referred to as
+*initializing* the variable).  Variables do not have to be initialized
+(given a value) when they are declared, but it is good style to give
+them an initial value whenever possible.
+
+Here is an example of declaring a variable named ``inputVariable1``
+with type :ref:`int <lang-int>` (the ``int`` type is used to store
+integers, like -2, -1, 0, 1, etc.)::
+
+    int inputVariable1;
+
+In the above declaration, we did not give the variable an initial
+value.  Here is another example, where we declare an ``int`` variable
+named ``inputVariable2``, with an initial value of ``0``::
+
+    int inputVariable2 = 0;
+
+The Maple environment comes ready to use with many useful types of
+variables.  See the :ref:`built-in types <lang-numeric-types>` page
+for more information.
+
+Here are a few examples of declaring variables of different types::
+
+     int lightSensVal;
+     char currentLetter;
+     unsigned long speedOfLight = 186000UL;
+     char errorMessage = {"choose another option"}; // see string
+
+Naming Variables
+----------------
+
+The rules for naming a variable are simple.  Names for variables can
+contain letters, numbers, and underscores (the underscore is the
+:kbd:`_` character), and cannot begin with a number.  So
+``temperature_reading``, ``tempReading``, ``tempReading1``, and
+``tempReading2`` are all valid variable names, but ``4_temp_readings``
+is not, because it begins with a number.
+
+You cannot choose a name for a variable that is one of the C++
+:ref:`keywords <lang-keywords>`.
+
+Variable names are case-sensitive, so "tempreading" and "tempReading"
+are different variables.  However, it is very bad style to write code
+that chooses variables which are the same up to case.
+
+You should give your variables descriptive names, so as to make your
+code more readable. Variable names like ``tiltSensor`` or
+``pushButton`` help you (and anyone else reading your code) understand
+what the variable represents. Variable names like ``var`` or
+``value``, on the other hand, do little to make your code readable.
+
+.. _lang-variables-scope:
+
+Variable Scope
+--------------
+
+An important choice that programmers face is where (in the program
+text) to declare variables. The specific place that variables are
+declared influences how various functions in a program will "see" the
+variable.  This is called variable *scope*.  See the :ref:`scope
+reference <lang-scope>` for more information.
+
+.. _lang-variables-initializing:
+
+Initializing Variables
+----------------------
+
+Variables may be *initialized* (assigned a starting value) when they
+are declared or not. It is always good programming practice however to
+double check that a variable has valid data in it before it is used.
+Using a variable before you give it a value is a common source of
+bugs.
+
+.. _lang-variables-rollover:
+
+Variable Rollover
+-----------------
+
+Every (numeric) type has a valid *range*.  The range of a type is the
+smallest and largest value that a variable of that type can store.
+For example, the :ref:`int <lang-int>` type has a range of
+-2,147,483,648 to 2,147,483,647 [#frange]_.
+
+When variables are made to exceed their range's maximum value, they
+"roll over" back to their minimum value.  Note that this happens in
+both directions.  It's like in the game *Pac-Man* -- when Pac-Man goes
+past the right edge of the screen, he reappears on the left, and when
+he goes past the left side of the screen, he reappears on the right::
+
+       int x;
+       x = -2,147,483,648;
+       x = x - 1; // x now contains -2,147,483,647; rolled over "left to right"
+
+       x = 2,147,483,647;
+       x = x + 1; // x now contains -2,147,483,648; rolled over "right to left"
+
+Each numeric type's reference page includes its range.  See the
+:ref:`built-in types <lang-numeric-types>` reference for links to each
+type's reference page.
+
+Using Variables
+---------------
+
+Once variables have been declared, they are given values using the
+:ref:`assignment operator <lang-assignment>`, which is a single equals
+sign, ``=``. The assignment operator tells the program to store the
+value on the right side of the equals sign into the variable on the
+left side::
+
+    inputVariable1 = 7;             // sets variable named inputVariable1 to 7
+    inputVariable2 = analogRead(2); // sets variable named inputVariable2 to
+                                    // the (digitized) input voltage read from
+                                    //  analog pin #2
+
+Once a variable has been set (assigned a value), you can test its
+value to see if it meets certain conditions, or you can use its value
+directly. For instance, the following code tests whether the
+inputVariable2 is less than 100, then sets a delay based on
+inputVariable2 (which, at that point, is at least 100)::
+
+    if (inputVariable2 < 100) {
+      inputVariable2 = 100;
+    }
+
+    delay(inputVariable2);
+
+See Also
+--------
+
+- :ref:`lang-scope`
+- :ref:`lang-numeric-types`
+
+.. rubric:: Footnotes
+
+.. [#frange] This range might seem a little weird at first.  The
+   reasons for this range of values have to do with the fact that an
+   ``int`` occupies 32 bits of memory, and the facts ::
+
+     2^31 = -2,147,483,648
+     2^31 - 1 = 2,147,483,647
+
+
+   Why 2^31 instead of 2^32?  Well, that has to do with `how ints are
+   (usually) stored
+   <http://en.wikipedia.org/wiki/Two%27s_complement>`_ on computers.
+
+
+.. include:: cc-attribution.txt
+