arduino language reference nearing completion, properly CC-BY-SA 3.0 attributed

1 files changed, 150 insertions, 149 deletions

diff --git a/source/arduino/bitwisecompound.rst b/source/arduino/bitwisecompound.rst
index c3c808f..d460dc8 100644
--- a/source/arduino/bitwisecompound.rst
+++ b/source/arduino/bitwisecompound.rst
@@ -1,227 +1,228 @@
+.. highlight:: cpp
+
 .. _arduino-bitwisecompound:
 
-compound bitwise AND (&=), compound bitwise OR (\|=)
-====================================================
+Compound bitwise and (&=), or (\|=), XOR (^=)
+=============================================
 
 The compound bitwise operators perform their calculations at the
 bit level of variables. They are often used to clear and set
 specific bits of a variable.
 
+See the :ref:`bitwise math tutorial <arduino-bitwisemath>` for more
+information on bitwise operators.
 
+.. contents:: Contents
+   :local:
 
-See the
-`bitwise AND (&) <http://arduino.cc/en/Reference/BitwiseAnd>`_ and
-`bitwise OR (\|) <http://arduino.cc/en/Reference/BitwiseAnd>`_
-operators for the details of their operation, and also the
-`Bitmath Tutorial <http://www.arduino.cc/playground/Code/BitMath>`_
-for more information on bitwise operators.
-
-
-
-compound bitwise AND (&=)
-=========================
-
-Description
------------
-
-The compound bitwise AND operator (&=) is often used with a
-variable and a constant to force particular bits in a variable to
-the LOW state (to 0). This is often referred to in programming
-guides as "clearing" or "resetting" bits.
-
-
+.. _arduino-bitwisecompound-and:
 
-Syntax:
--------
+Compound bitwise AND (&=)
+-------------------------
 
-::
+The compound bitwise AND operator ``&=`` is often used with a variable
+and a constant to force particular bits in a variable to be zero. This
+is often referred to in programming guides as "clearing" or
+"resetting" bits.  In a program, writing the line ``x &= y;`` is
+equivalent to writing ``x = x & y;``.  That is, the value of ``x``
+after the line will be equal to its old value bitwise ANDed with the
+value of ``y``::
 
-    x &= y;   // equivalent to x = x & y; 
+    x &= y;   // equivalent to x = x & y;
 
+You can use any integer variable for ``x`` (i.e., any variable of type
+``int``, ``long``, ``char``, ``byte``, etc.).  You can use either an
+integer variable or any :ref:`integer value
+<arduino-constants-integers>` (like ``3`` or ``0x20``) for ``y``.
 
-
-Parameters
-----------
-
-x: a char, int or long variable
-y: an integer constant or char, int, or long
-
-
-
-Example:
---------
-
-First, a review of the Bitwise AND (&) operator
-
-::
+Before doing an example of ``&=``, let's first review the Bitwise AND
+(``&``) operator::
 
        0  0  1  1    operand1
        0  1  0  1    operand2
        ----------
-       0  0  0  1    (operand1 & operand2) - returned result
-
-
-
-Bits that are "bitwise ANDed" with 0 are cleared to 0 so, if myByte
-is a byte variable,
-``myByte & B00000000 = 0;``
-
-
-
-Bits that are "bitwise ANDed" with 1 are unchanged so,
-``myByte & B11111111 = myByte;``
+       0  0  0  1    (operand1 & operand2) = result
 
+As shown above, bits that are "bitwise ANDed" with 0 become 0, while
+bits that are "bitwise ANDed" with 1 are left unchanged.  So, if ``b``
+is a ``byte`` variable, then ``b & B00000000`` equals zero, and ``b &
+B11111111`` equals ``b``.
 
+.. _arduino-bitwisecompound-binconst:
 
-Note: because we are dealing with bits in a bitwise operator - it
-is convenient to use the binary formatter with
-`constants. <http://arduino.cc/en/Reference/IntegerConstants>`_ The
-numbers are still the same value in other representations, they are
-just not as easy to understand. Also, B00000000 is shown for
-clarity, but zero in any number format is zero (hmmm something
-philosophical there?)
+.. note:: The above uses :ref:`binary constants
+   <arduino-constants-integers-bin>`\ .  The numbers are still the same
+   value in other representations, they just might not be as easy to
+   understand.
 
+   Normally, in C and C++ code, :ref:`hexadecimal
+   <arduino-constants-integers-hex>` or :ref:`octal
+   <arduino-constants-integers-oct>` are used when we're interested in
+   an integer's bits, rather than its value as a number.
 
+   While hexadecimal and octal literals might be harder to understand
+   at first, you should really take the time to learn them.  They're
+   part of C, C++, and many other programming languages, while binary
+   constants are available only for compatibility with Arduino.
 
-Consequently - to clear (set to zero) bits 0 & 1 of a variable,
-while leaving the rest of the variable unchanged, use the compound
-bitwise AND operator (&=) with the constant B11111100
+   Also, ``B00000000`` is shown for clarity, but zero in any number
+   format is zero.
 
-::
+So, to clear (set to zero) bits 0 and 1 of a one-byte variable, while
+leaving the rest of the variable's bits unchanged, use the compound
+bitwise AND operator ``&=`` with the constant ``B11111100``
+(hexadecimal ``0xFC``\ )::
 
-       1  0  1  0  1  0  1  0    variable  
+       1  0  1  0  1  0  1  0    variable
        1  1  1  1  1  1  0  0    mask
        ----------------------
        1  0  1  0  1  0  0  0
-    
-     variable unchanged
-                         bits cleared
-      
-
-Here is the same representation with the variable's bits replaced
-with the symbol x
-
+       ^^^^^^^^^^^^^^^^  ^^^^
+          unchanged      cleared
 
 
-::
+Here is the same representation with the variable's bits replaced
+with the symbol ``x``\ ::
 
        x  x  x  x  x  x  x  x    variable
        1  1  1  1  1  1  0  0    mask
        ----------------------
        x  x  x  x  x  x  0  0
-    
-     variable unchanged
-                         bits cleared
-     
-
-So if:
+       ^^^^^^^^^^^^^^^^  ^^^^
+          unchanged       cleared
 
-::
 
-    myByte =  10101010;
-    
-    myByte &= B1111100 == B10101000;
+So, using a byte variable ``b``\ , if we say::
 
+    b =  B10101010; // B10101010 == 0xAA
+    b &= B11111100; // B11111100 == 0xFC
 
+then we will have ::
 
-compound bitwise OR (\|=)
-=========================
+    b == B10101000; // B10101000 == 0xA8
 
-Description
------------
+.. _arduino-bitwisecompound-or:
 
-The compound bitwise OR operator (\|=) is often used with a
-variable and a constant to "set" (set to 1) particular bits in a
-variable.
+Compound bitwise OR (\|=)
+-------------------------
 
+The compound bitwise OR operator ``|=`` is often used with a variable
+and a constant to "set" (set to 1) particular bits in a variable.  In
+a program, writing the line ``x |= y;`` is equivalent to writing ``x =
+x | y;``.  That is, the value of ``x`` after the line will be equal to
+its old value bitwise ORed with the value of ``y``::
 
+    x |= y;   // equivalent to x = x | y;
 
-Syntax:
--------
+You can use any integer variable for ``x`` (i.e., any variable of type
+``int``, ``long``, ``char``, ``byte``, etc.).  You can use either an
+integer variable or any integer value (like ``3`` or ``0x20``) for
+``y``.  (This works the same way as :ref:`compound bitwise AND
+<arduino-bitwisecompound-and>`\ , ``&=``).
 
-::
+Before doing an example of ``|=``, let's first review the Bitwise OR
+(``|``) operator::
 
-    x |= y;   // equivalent to x = x | y; 
+       0  0  1  1    operand1
+       0  1  0  1    operand2
+       ----------
+       0  1  1  1    (operand1 | operand2) = result
 
+Bits that are "bitwise ORed" with 0 are unchanged, while bits that are
+"bitwise ORed" with 1 are set to 1.  So if ``b`` is a ``byte``
+variable, then ``b | B00000000`` equals ``b``, and ``b & B11111111``
+equals ``B11111111`` (here we've used binary constants; see the
+:ref:`note <arduino-bitwisecompound-binconst>` above).
 
+So, to set bits 0 and 1 of a one-byte variable, while leaving the rest
+of the variable unchanged, use the compound bitwise OR operator
+(``|=``) with the constant ``B00000011`` (hexadecimal ``0x3``)::
 
-Parameters
-----------
+       1  0  1  0  1  0  1  0    variable
+       0  0  0  0  0  0  1  1    mask
+       ----------------------
+       1  0  1  0  1  0  1  1
+       ^^^^^^^^^^^^^^^^  ^^^^
+           unchanged      set
 
-x: a char, int or long variable
-y: an integer constant or char, int, or long
+Here is the same representation with the variable's bits replaced with
+the symbol ``x``::
 
+       x  x  x  x  x  x  x  x    variable
+       0  0  0  0  0  0  1  1    mask
+       ----------------------
+       x  x  x  x  x  x  1  1
+       ^^^^^^^^^^^^^^^^  ^^^^
+           unchanged      set
 
+So, using a byte variable ``b``, if we say::
 
-Example:
---------
+    b  = B10101010; // B10101010 == 0xAA
+    b |= B00000011; // B00000011 == 0x3
 
-First, a review of the Bitwise OR (\|) operator
+then we will have ::
 
-::
+    b == B10101011; // B10101011 == 0xAB
 
-       0  0  1  1    operand1
-       0  1  0  1    operand2
-       ----------
-       0  1  1  1    (operand1 | operand2) - returned result
+.. _arduino-bitwisecompound-xor:
 
-Bits that are "bitwise ORed" with 0 are unchanged, so if myByte is
-a byte variable,
-myByte \| B00000000 = myByte;
+Compound bitwise XOR (\^=)
+--------------------------
 
+The compound bitwise XOR operator ``^=`` is used with a variable and a
+constant to "toggle" (change 0 to 1, and 1 to 0) particular bits in a
+variable.  In a program, writing the line ``x ^= y;`` is equivalent to
+writing ``x = x ^ y;``.  That is, the value of ``x`` after the line
+will be equal to its old value bitwise XORed with the value of ``y``::
 
+    x ^= y;   // equivalent to x = x ^ y;
 
-Bits that are "bitwise ORed" with 1 are set to 1 so:
-myByte & B11111111 = B11111111;
+You can use any integer variable for ``x`` (i.e., any variable of type
+``int``, ``long``, ``char``, ``byte``, etc.).  You can use either an
+integer variable or any integer value (like ``3`` or ``0x20``) for
+``y``.  (This works the same way as :ref:`&=
+<arduino-bitwisecompound-and>` and :ref:`\|=
+<arduino-bitwisecompound-or>`; in fact, these three operators all
+work the same in this way).
 
+Before doing an example of ``^=``, let's first review the Bitwise
+XOR operator, ``^``::
 
+        0  0  1  1    operand1
+        0  1  0  1    operand2
+        ----------
+        0  1  1  0    (operand1 ^ operand2) = result
 
-Consequently - to set bits 0 & 1 of a variable, while leaving the
-rest of the variable unchanged, use the compound bitwise AND
-operator (&=) with the constant B00000011
+One way to look at bitwise XOR is that each bit in the result is a 1
+if the input bits are different, or 0 if they are the same.  Another
+way to think about it is that the result bit will be 1 when *exactly*
+one (no more, no less) of the input bits is 1; otherwise, it will be
+zero.  This means that if you XOR a bit with 1, it will change (or
+toggle) its value, while if you XOR a bit with 0, it stays the same.
 
-::
+So, to toggle bits 0 and 1 of a one-byte variable, while leaving the
+rest of the variable unchanged, use the compound bitwise XOR operator
+``^=`` with the constant ``B00000011`` (hexadecimal ``0x3``\ ; see
+:ref:`note <arduino-bitwisecompound-binconst>` above)::
 
        1  0  1  0  1  0  1  0    variable
        0  0  0  0  0  0  1  1    mask
        ----------------------
        1  0  1  0  1  0  1  1
-    
-     variable unchanged
-                         bits set
-    
+       ^^^^^^^^^^^^^^^^  ^^^^
+           unchanged     toggled
 
-Here is the same representation with the variables bits replaced
-with the symbol x
+So, using a byte variable ``b``, if we say::
 
+    b  = B10101010; // B10101010 == 0xAA
+    b ^= B00000011; // B00000011 == 0x3
 
+then we will have ::
 
-::
-
-       x  x  x  x  x  x  x  x    variable
-       0  0  0  0  0  0  1  1    mask
-       ----------------------
-       x  x  x  x  x  x  1  1
-    
-     variable unchanged
-                         bits set
-
-So if:
-
-::
-
-    myByte =  B10101010;
-    
-    myByte |= B00000011 == B10101011;
-
-
+    b == B10101001; // B10101001 == 0xA9
 
 See Also
+--------
 
-
--  `& <http://arduino.cc/en/Reference/BitwiseAnd>`_ (bitwise AND)
--  `\| <http://arduino.cc/en/Reference/BitwiseAnd>`_ (bitwise OR)
--  `&& <http://arduino.cc/en/Reference/Boolean>`_ (Boolean AND)
--  `\|\| <http://arduino.cc/en/Reference/Boolean>`_ (Boolean OR)
-
-
+- :ref:`Boolean operations <arduino-boolean>` (``&&``, ``||``)
+- :ref:`Bitwise operators <arduino-bitwisemath>` (``&``, ``|``, ``^``, ``~``)