aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/lang/comparison.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/lang/comparison.rst')
-rw-r--r--docs/source/lang/comparison.rst87
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