1 files changed, 87 insertions, 0 deletions
diff --git a/docs/source/lang/comparison.rst b/docs/source/lang/comparison.rst
new file mode 100644
index 0000000..8873256
--- /dev/null
+++ b/docs/source/lang/comparison.rst
@@ -0,0 +1,87 @@
+.. highlight:: cpp
+
+.. _lang-comparison:
+
+Comparison Operators
+====================
+
+The comparison operators ``==``, ``!=``, ``<``, ``>``, ``<=``, and
+``>=`` are used to compare two numbers.  They are :ref:`true
+<lang-constants-true>` when the comparison is true, and :ref:`false
+<lang-constants-false>` otherwise.  They are based on the symbols
+=, ≠, <, >, ≤, and ≥ from mathematics.
+
+Here are some examples, with their meaning in comments::
+
+     // "eq" is true when x is equal to y
+     bool eq = (x == y);
+
+     // "neq" is true when x is different than y
+     bool neq = (x != y);
+
+     // "lt" is true when x is less than, but NOT equal to, y
+     bool lt = (x <  y);
+
+     // "gt" is true when x is greater than, but NOT equal to, y
+     bool gt = (x >  y);
+
+     // "lte" is true when x is less than or equal to y
+     bool lte = (x <= y);
+
+     // "gte" is true when x is greater than or equal to y
+     bool gte = (x >= y);
+
+The parentheses are optional; they are present only for clarity.  For
+example, the following two lines are the same::
+
+    bool eq = x == y;
+
+    bool eq = (x == y);
+
+Uses
+----
+
+Comparison operators, along with :ref:`boolean operators
+<lang-boolean>`, are useful inside the conditionals of :ref:`if
+<lang-if>` statements.  Here's one example::
+
+    if (x < 50) {
+       // only execute these lines if x is less than 50
+       SerialUSB.println("delaying:");
+       SerialUSB.println(x);
+       delay(x);
+    }
+
+.. warning::
+   Beware of accidentally using the single equal sign (``=``) when you
+   meant to test if two numbers are equal (``==``).  This is a common
+   mistake inside of ``if`` statement conditionals, e.g.::
+
+       // DON'T MAKE THIS MISTAKE
+       if (x = 10) {
+          // body
+       }
+
+   The single equal sign is the assignment operator, and sets x to 10
+   (puts the value 10 into the variable x).  Instead use the double equal
+   sign (e.g. ``if (x == 10)``), which is the comparison operator, and
+   tests *whether* x is equal to 10 or not. The latter statement is only
+   true if x equals 10, but the former statement will always be true.
+
+   This is because C evaluates the statement ``if (x=10)`` as follows: 10
+   is assigned to x (remember that the single equal sign is the
+   :ref:`assignment operator <lang-assignment>`), so x now
+   contains 10. Then the 'if' conditional evaluates 10, which evaluates
+   to :ref:`true <lang-constants-true>`, since any non-zero number
+   evaluates to ``true``.
+
+   Consequently, the conditional of an ``if`` statement like ``if (x =
+   10) {...}`` will always evaluate to ``true``, and the variable x
+   will be set to 10, which is probably not what you meant.
+
+   (This sometimes has uses, though, so just because an assignment
+   appears within a conditional doesn't mean it's automatically wrong.
+   Be careful to know what you mean.)
+
+
+.. include:: cc-attribution.txt