diff --git a/Language/Functions/Communication/serial.adoc b/Language/Functions/Communication/serial.adoc index 2c1561746..fa1a708b7 100644 --- a/Language/Functions/Communication/serial.adoc +++ b/Language/Functions/Communication/serial.adoc @@ -32,24 +32,24 @@ The *Arduino Leonardo* board uses `Serial1` to communicate via TTL (5V) serial o [float] === Functions -http://arduino.cc[if] (Serial) + -http://arduino.cc[available()] + -http://arduino.cc[begin()] + -http://arduino.cc[end()] + -http://arduino.cc[find()] + -http://arduino.cc[findUntil()] + -http://arduino.cc[flush()] + -http://arduino.cc[parseFloat()] + -http://arduino.cc[parseInt()] + -http://arduino.cc[peek()] + -http://arduino.cc[print()] + -http://arduino.cc[println()] + -http://arduino.cc[read()] + -http://arduino.cc[readBytes()] + -http://arduino.cc[readBytesUntil()] + -http://arduino.cc[setTimeout()] + -http://arduino.cc[write()] + -http://arduino.cc[serialEvent()] +link:IfSerial{ext-relative}[If] (Serial) + +link:Available{ext-relative}[available()] + +link:Begin{ext-relative}[begin()] + +link:End{ext-relative}[end()] + +link:Find{ext-relative}[find()] + +link:FindUntil{ext-relative}[findUntil()] + +link:Flush{ext-relative}[flush()] + +link:ParseFloat{ext-relative}[parseFloat()] + +link:ParseInt{ext-relative}[parseInt()] + +link:Peek{ext-relative}[peek()] + +link:Print{ext-relative}[print()] + +link:PrintLn{ext-relative}[println()] + +link:Read{ext-relative}[read()] + +link:ReadBytes{ext-relative}[readBytes()] + +link:ReadBytesUntil{ext-relative}[readBytesUntil()] + +link:SetTimeout{ext-relative}[setTimeout()] + +link:Write{ext-relative}[write()] + +link:SerialEvent{ext-relative}[serialEvent()] ''' @@ -75,4 +75,4 @@ http://arduino.cc[serialEvent()] -- -// SEEALSO SECTION ENDS \ No newline at end of file +// SEEALSO SECTION ENDS diff --git a/Language/Structure/Arithmetic Operators/addition.adoc b/Language/Structure/Arithmetic Operators/addition.adoc new file mode 100644 index 000000000..1340088aa --- /dev/null +++ b/Language/Structure/Arithmetic Operators/addition.adoc @@ -0,0 +1,76 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += + Addition + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Addition* is one of the four primary arithmetic operations. The operator `+` (plus) operates on two operands to produce the sum. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +sum = operand1 + operand2; +---- + +[float] +=== Parameters +`sum` : variable. *Allowed data types:* int, float, double, byte, short, long + +`operand1` : variable or constant. *Allowed data types:* int, float, double, byte, short, long + +`operand2` : variable or constant. *Allowed data types:* int, float, double, byte, short, long +[%hardbreaks] +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 5, b = 10, c = 0; +c = a + b; // the variable 'c' gets a value of 15 after this statement is executed +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +1. The addition operation can overflow if the result is larger than that which can be stored in the data type (e.g. adding 1 to an integer with the value 32,767 gives -32,768). + +2. If one of the numbers (operands) are of the type float or of type double, floating point math will be used for the calculation. + +3. If the operands are of float / double data type and the variable that stores the sum is an integer, then only the integral part is stored and the fractional part of the number is lost. + +[source,arduino] +---- +float a = 5.5, b = 6.6; +int c = 0; +c = a + b; // the variable 'c' stores a value of 12 only as opposed to the expected sum of 12.1 +---- +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:subtraction{ext-relative}[Subtraction] +* #LANGUAGE# link:multiplication{ext-relative}[Multiplication] +* #LANGUAGE# link:division{ext-relative}[Division] +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Arithmetic Operators/assignment.adoc b/Language/Structure/Arithmetic Operators/assignment.adoc new file mode 100644 index 000000000..600dc5b9c --- /dev/null +++ b/Language/Structure/Arithmetic Operators/assignment.adoc @@ -0,0 +1,57 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += = Assignment (single equal sign) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The single equal sign `=` in the C programming language is called the assignment operator. It has a different meaning than in algebra class where it indicated an equation or equality. The assignment operator tells the microcontroller to evaluate whatever value or expression is on the right side of the equal sign, and store it in the variable to the left of the equal sign. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + + + +[source,arduino] +---- +int sensVal; // declare an integer variable named sensVal +sensVal = analogRead(0); // store the (digitized) input voltage at analog pin 0 in SensVal +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +1. The variable on the left side of the assignment operator ( = sign ) needs to be able to hold the value stored in it. If it is not large enough to hold a value, the value stored in the variable will be incorrect. + +2. Don't confuse the assignment operator [ = ] (single equal sign) with the comparison operator [ == ] (double equal signs), which evaluates whether two expressions are equal. +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../Control%20Structures/if{ext-relative}[if (conditional operators)] +* #LANGUAGE# link:../../Variables/Data%20Types/char[char] +* #LANGUAGE# link:../../Variables/Data%20Types/int[int] +* #LANGUAGE# link:../../Variables/Data%20Types/long[long] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Arithmetic Operators/division.adoc b/Language/Structure/Arithmetic Operators/division.adoc new file mode 100644 index 000000000..4a6eb49a8 --- /dev/null +++ b/Language/Structure/Arithmetic Operators/division.adoc @@ -0,0 +1,76 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += / Division + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Division* is one of the four primary arithmetic operations. The operator `/` (slash) operates on two operands to produce the result. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +result = numerator / denominator; +---- + +[float] +=== Parameters +`result` : variable. *Allowed data types:* int, float, double, byte, short, long + +`numerator` : variable or constant. *Allowed data types:* int, float, double, byte, short, long + +`denominator` : *non zero* variable or constant. *Allowed data types:* int, float, double, byte, short, long +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 50, b = 10, c = 0; +c = a / b; // the variable 'c' gets a value of 5 after this statement is executed +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +1. If one of the numbers (operands) are of the type float or of type double, floating point math will be used for the calculation. + +2. If the operands are of float / double data type and the variable that stores the sum is an integer, then only the integral part is stored and the fractional part of the number is lost. + +[source,arduino] +---- +float a = 55.5, b = 6.6; +int c = 0; +c = a / b; // the variable 'c' stores a value of 8 only as opposed to the expected result of 8.409 +---- +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:addition{ext-relative}[addition] +* #LANGUAGE# link:subtraction{ext-relative}[subtraction] +* #LANGUAGE# link:multiplication{ext-relative}[multiplication] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Arithmetic Operators/modulo.adoc b/Language/Structure/Arithmetic Operators/modulo.adoc new file mode 100644 index 000000000..4dc6e4750 --- /dev/null +++ b/Language/Structure/Arithmetic Operators/modulo.adoc @@ -0,0 +1,82 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += % Modulo + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Modulo* operation calculates the remainder when one integer is divided by another. It is useful for keeping a variable within a particular range (e.g. the size of an array). The `%` (percent) symbol is used to carry out modulo operation. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +remainder = dividend % divisor; +---- + +[float] +=== Parameters +`remainder` : variable. *Allowed data types:* int, float, double + +`dividend` : variable or constant. *Allowed data types:* int + +`divisor` : *non zero* variable or constant. *Allowed data types:* int +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int x = 0; +x = 7 % 5; // x now contains 2 +x = 9 % 5; // x now contains 4 +x = 5 % 5; // x now contains 0 +x = 4 % 5; // x now contains 4 +---- + +[source,arduino] +---- +/* update one value in an array each time through a loop */ + +int values[10]; +int i = 0; + +void setup() {} + +void loop() +{ + values[i] = analogRead(0); + i = (i + 1) % 10; // modulo operator rolls over variable +} +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +The modulo operator does not work on floats. +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:division{ext-relative}[Division] +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Arithmetic Operators/multiplication.adoc b/Language/Structure/Arithmetic Operators/multiplication.adoc new file mode 100644 index 000000000..b8c95b248 --- /dev/null +++ b/Language/Structure/Arithmetic Operators/multiplication.adoc @@ -0,0 +1,78 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += * Multiplication + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Multiplication* is one of the four primary arithmetic operations. The operator `*` (asterisk) operates on two operands to produce the product. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +product = operand1 * operand2; +---- + +[float] +=== Parameters +`product` : variable. *Allowed data types:* int, float, double, byte, short, long + +`operand1` : variable or constant. *Allowed data types:* int, float, double, byte, short, long + +`operand2` : variable or constant. *Allowed data types:* int, float, double, byte, short, long +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 5, b = 10, c = 0; +c = a * b; // the variable 'c' gets a value of 50 after this statement is executed +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +1. The multiplication operation can overflow if the result is bigger than that which can be stored in the data type. + +2. If one of the numbers (operands) are of the type float or of type double, floating point math will be used for the calculation. + +3. If the operands are of float / double data type and the variable that stores the product is an integer, then only the integral part is stored and the fractional part of the number is lost. + +[source,arduino] +---- +float a = 5.5, b = 6.6; +int c = 0; +c = a * b; // the variable 'c' stores a value of 36 only as opposed to the expected product of 36.3 +---- +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:addition{ext-relative}[Addition] +* #LANGUAGE# link:subtraction{ext-relative}[subtraction] +* #LANGUAGE# link:division{ext-relative}[Division] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Arithmetic Operators/subtraction.adoc b/Language/Structure/Arithmetic Operators/subtraction.adoc new file mode 100644 index 000000000..db209654f --- /dev/null +++ b/Language/Structure/Arithmetic Operators/subtraction.adoc @@ -0,0 +1,78 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += - Subtraction + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Subtraction* is one of the four primary arithmetic operations. The operator `-` (minus) operates on two operands to produce the difference of the second from the first. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +difference = operand1 - operand2; +---- + +[float] +=== Parameters +`difference` : variable. *Allowed data types:* int, float, double, byte, short, long + +`operand1` : variable or constant. *Allowed data types:* int, float, double, byte, short, long + +`operand2` : variable or constant. *Allowed data types:* int, float, double, byte, short, long +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 5, b = 10, c = 0; +c = a - b; // the variable 'c' gets a value of -5 after this statement is executed +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +1. The subtraction operation can overflow if the result is smaller than that which can be stored in the data type (e.g. subtracting 1 from an integer with the value -32,768 gives 32,767). + +2. If one of the numbers (operands) are of the type float or of type double, floating point math will be used for the calculation. + +3. If the operands are of float / double data type and the variable that stores the difference is an integer, then only the integral part is stored and the fractional part of the number is lost. + +[source,arduino] +---- +float a = 5.5, b = 6.6; +int c = 0; +c = a - b; // the variable 'c' stores a value of -1 only as opposed to the expected difference of -1.1 +---- +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:addition{ext-relative}[Addition] +* #LANGUAGE# link:multiplication{ext-relative}[Multiplication] +* #LANGUAGE# link:division{ext-relative}[division] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Bitwise Operators/bitshiftLeft.adoc b/Language/Structure/Bitwise Operators/bitshiftLeft.adoc new file mode 100644 index 000000000..cbc006836 --- /dev/null +++ b/Language/Structure/Bitwise Operators/bitshiftLeft.adoc @@ -0,0 +1,89 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += << Bitshift Left + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The left shift operator `<<` causes the bits of the left operand to be shifted *left* by the number of positions specified by the right operand. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +variable << number_of_bits; +---- + +[float] +=== Parameters +`variable`: *Allowed data types:* byte, int, long + +`number_of_bits`: a number that is < = 32. *Allowed data types:* int + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 5; // binary: 0000000000000101 +int b = a << 3; // binary: 0000000000101000, or 40 in decimal +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +When you shift a value x by y bits (x << y), the leftmost y bits in x are lost, literally shifted out of existence: + +[source,arduino] +---- +int x = 5; // binary: 0000000000000101 +int y = 14; +int result = x << y; // binary: 0100000000000000 - the first 1 in 101 was discarded +---- + +If you are certain that none of the ones in a value are being shifted into oblivion, a simple way to think of the left-shift operator is that it multiplies the left operand by 2 raised to the right operand power. For example, to generate powers of 2, the following expressions can be employed: + +[source,arduino] +---- + Operation Result + --------- ------ + 1 << 0 1 + 1 << 1 2 + 1 << 2 4 + 1 << 3 8 + ... + 1 << 8 256 + 1 << 9 512 + 1 << 10 1024 + ... +---- +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:bitshiftRight{ext-relative}[>> Bitshift Right] + +[role="example"] +* #EXAMPLE# http://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Bitwise Operators/bitshiftRight.adoc b/Language/Structure/Bitwise Operators/bitshiftRight.adoc new file mode 100644 index 000000000..e2e7e60d6 --- /dev/null +++ b/Language/Structure/Bitwise Operators/bitshiftRight.adoc @@ -0,0 +1,88 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += >> Bitshift Right + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The right shift operator `>>` causes the bits of the left operand to be shifted *right* by the number of positions specified by the right operand. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +variable >> number_of_bits; +---- + +[float] +=== Parameters +`variable`: *Allowed data types:* byte, int, long + +`number_of_bits`: a number that is < = 32. *Allowed data types:* int + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 40; // binary: 0000000000101000 +int b = a >> 3; // binary: 0000000000000101, or 5 in decimal +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +When you shift x right by y bits (x >> y), and the highest bit in x is a 1, the behavior depends on the exact data type of x. If x is of type int, the highest bit is the sign bit, determining whether x is negative or not, as we have discussed above. In that case, the sign bit is copied into lower bits, for esoteric historical reasons: + +[source,arduino] +---- +int x = -16; // binary: 1111111111110000 +int y = 3; +int result = x >> y; // binary: 1111111111111110 +---- +This behavior, called sign extension, is often not the behavior you want. Instead, you may wish zeros to be shifted in from the left. It turns out that the right shift rules are different for unsigned int expressions, so you can use a typecast to suppress ones being copied from the left: + +[source,arduino] +---- +int x = -16; // binary: 1111111111110000 +int y = 3; +int result = (unsigned int)x >> y; // binary: 0001111111111110 +---- +If you are careful to avoid sign extension, you can use the right-shift operator `>>` as a way to divide by powers of 2. For example: + +[source,arduino] +---- +int x = 1000; +int y = x >> 3; // integer division of 1000 by 8, causing y = 125. +---- + +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:bitshiftLeft{ext-relative}[<< Bitshift Left] + +[role="example"] +* #EXAMPLE# http://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Bitwise Operators/bitwiseAnd.adoc b/Language/Structure/Bitwise Operators/bitwiseAnd.adoc new file mode 100644 index 000000000..a5a380a77 --- /dev/null +++ b/Language/Structure/Bitwise Operators/bitwiseAnd.adoc @@ -0,0 +1,70 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += & Bitwise AND + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The bitwise AND operator in C++ is a single ampersand `&`, used between two other integer expressions. Bitwise AND operates on each bit position of the surrounding expressions independently, according to this rule: if both input bits are 1, the resulting output is 1, otherwise the output is 0. +[%hardbreaks] + +Another way of expressing this is: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 0 0 1 (operand1 & operand2) - returned result +[%hardbreaks] + +In Arduino, the type int is a 16-bit value, so using & between two int expressions causes 16 simultaneous AND operations to occur. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +In a code fragment like: + +[source,arduino] +---- +int a = 92; // in binary: 0000000001011100 +int b = 101; // in binary: 0000000001100101 +int c = a & b; // result: 0000000001000100, or 68 in decimal. +---- +Each of the 16 bits in a and b are processed by using the bitwise AND, and all 16 resulting bits are stored in c, resulting in the value 01000100 in binary, which is 68 in decimal. +[%hardbreaks] + +One of the most common uses of bitwise AND is to select a particular bit (or bits) from an integer value, often called masking. See below for an example + +[source,arduino] +---- +PORTD = PORTD & B00000011; // clear out bits 2 - 7, leave pins 0 and 1 untouched (xx & 11 == xx) +---- +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:bitwiseOr{ext-relative}[| Bitwise OR] +* #LANGUAGE# link:bitwiseNot{ext-relative}[~ Bitwise NOT] +* #LANGUAGE# link:../Boolean%20Operators/logicalAnd{ext-relative}[&& Logical AND] + +[role="example"] +* #EXAMPLE# http://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Bitwise Operators/bitwiseNot.adoc b/Language/Structure/Bitwise Operators/bitwiseNot.adoc new file mode 100644 index 000000000..2110bc3ec --- /dev/null +++ b/Language/Structure/Bitwise Operators/bitwiseNot.adoc @@ -0,0 +1,64 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += ~ Bitwise NOT + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The bitwise NOT operator in C++ is the tilde character `~`. Unlike & and |, the bitwise NOT operator is applied to a single operand to its right. Bitwise NOT changes each bit to its opposite: 0 becomes 1, and 1 becomes 0. +[%hardbreaks] + +In other words: + + 0 1 operand1 + ----- + 1 0 ~operand1 +[%hardbreaks] +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 103; // binary: 0000000001100111 +int b = ~a; // binary: 1111111110011000 = -104 +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +You might be surprised to see a negative number like -104 as the result of this operation. This is because the highest bit in an int variable is the so-called sign bit. If the highest bit is 1, the number is interpreted as negative. This encoding of positive and negative numbers is referred to as two's complement. For more information, see the Wikipedia article on http://en.wikipedia.org/wiki/Twos_complement[two's complement^]. + +As an aside, it is interesting to note that for any integer x, ~x is the same as -x-1. + +At times, the sign bit in a signed integer expression can cause some unwanted surprises. +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:bitwiseAnd{ext-relative}[& Bitwise AND] +* #LANGUAGE# link:bitwiseOr{ext-relative}[| Bitwise OR] +* #LANGUAGE# link:../Boolean%20Operators/logicalNot{ext-relative}[! Logical NOT] + +[role="example"] +* #EXAMPLE# http://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Bitwise Operators/bitwiseOr.adoc b/Language/Structure/Bitwise Operators/bitwiseOr.adoc new file mode 100644 index 000000000..89eab7a9e --- /dev/null +++ b/Language/Structure/Bitwise Operators/bitwiseOr.adoc @@ -0,0 +1,66 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += | Bitwise OR + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The bitwise OR operator in C++ is the vertical bar symbol, |. Like the & operator, | operates independently each bit in its two surrounding integer expressions, but what it does is different (of course). The bitwise OR of two bits is 1 if either or both of the input bits is 1, otherwise it is 0. +[%hardbreaks] + +In other words: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) - returned result +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 92; // in binary: 0000000001011100 +int b = 101; // in binary: 0000000001100101 +int c = a | b; // result: 0000000001111101, or 125 in decimal. +---- +[%hardbreaks] + +One of the most common uses of the Bitwise OR is to set multiple bits in a bit-packed number. + +[source,arduino] +---- +DDRD = DDRD | B11111100; // set direction bits for pins 2 to 7, leave 0 and 1 untouched (xx | 00 == xx) +// same as pinMode(pin, OUTPUT) for pins 2 to 7 +---- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:bitwiseAnd{ext-relative}[& Bitwise AND] +* #LANGUAGE# link:bitwiseNot{ext-relative}[~ Bitwise NOT] +* #LANGUAGE# link:../Boolean%20Operators/logicalOr{ext-relative}[|| Logical OR] + +[role="example"] +* #EXAMPLE# http://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Bitwise Operators/bitwiseXor.adoc b/Language/Structure/Bitwise Operators/bitwiseXor.adoc new file mode 100644 index 000000000..8012cd3d0 --- /dev/null +++ b/Language/Structure/Bitwise Operators/bitwiseXor.adoc @@ -0,0 +1,78 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += ^ Bitwise XOR + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +There is a somewhat unusual operator in C++ called bitwise EXCLUSIVE OR, also known as bitwise XOR. (In English this is usually pronounced "eks-or".) The bitwise XOR operator is written using the caret symbol `^`. A bitwise XOR operation results in a 1 only if the input bits are different, else it results in a 0. +[%hardbreaks] + +Precisely, + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 0 (operand1 ^ operand2) - returned result +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int x = 12; // binary: 1100 +int y = 10; // binary: 1010 +int z = x ^ y; // binary: 0110, or decimal 6 +---- +[%hardbreaks] + +The ^ operator is often used to toggle (i.e. change from 0 to 1, or 1 to 0) some of the bits in an integer expression. In a bitwise OR operation if there is a 1 in the mask bit, that bit is inverted; if there is a 0, the bit is not inverted and stays the same. Below is a program to blink digital pin 5. + +[source,arduino] +---- +// Blink_Pin_5 +// demo for Exclusive OR +void setup(){ +DDRD = DDRD | B00100000; // set digital pin five as OUTPUT +Serial.begin(9600); +} + +void loop(){ +PORTD = PORTD ^ B00100000; // invert bit 5 (digital pin 5), leave others untouched +delay(100); +} +---- +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:bitwiseAnd{ext-relative}[& Bitwise AND] +* #LANGUAGE# link:bitwiseOr{ext-relative}[| Bitwise OR] +* #LANGUAGE# link:bitwiseNot{ext-relative}[~ Bitwise NOT] + + +[role="example"] +* #EXAMPLE# http://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] + + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Boolean Operators/logicalAnd.adoc b/Language/Structure/Boolean Operators/logicalAnd.adoc new file mode 100644 index 000000000..89f132a5d --- /dev/null +++ b/Language/Structure/Boolean Operators/logicalAnd.adoc @@ -0,0 +1,53 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += && Logical AND + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Logical AND* results in `true` *only* if both operands are `true`. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +This operator can be used inside the condition of an link:../Control%20Structures/if[if] statement. + +[source,arduino] +---- +if (digitalRead(2) == HIGH && digitalRead(3) == HIGH) { // if BOTH the switches read HIGH + // statements +} +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +Make sure you don't mistake the boolean AND operator, && (double ampersand) for the bitwise AND operator & (single ampersand). They are entirely different beasts. +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:logicalOr{ext-relative}[|| Logical OR] +* #LANGUAGE# link:logicalNot{ext-relative}[! Logical NOT] +* #LANGUAGE# link:../Bitwise%20Operators/bitwiseAnd{ext-relative}[& (Bitwise AND)] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Boolean Operators/logicalNot.adoc b/Language/Structure/Boolean Operators/logicalNot.adoc new file mode 100644 index 000000000..6a4edd5ec --- /dev/null +++ b/Language/Structure/Boolean Operators/logicalNot.adoc @@ -0,0 +1,61 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += ! Logical NOT + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Logical NOT* results in a `true` if the operand is `false` and vice versa. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +This operator can be used inside the condition of an link:../Control%20Structures/if[if] statement. + +[source,arduino] +---- +if (!x) { // if x is not true + // statements +} +---- + +It can be used to invert the boolean value. +[source,arduino] +---- +x = !y; // the inverted value of y is stored in x +---- + + +[%hardbreaks] + +[float] +=== Notes and Warnings +The bitwise not ~ (tilde) looks much different than the boolean not ! (exclamation point or "bang" as the programmers say) but you still have to be sure which one you want where. +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:logicalAnd{ext-relative}[&& Logical AND] +* #LANGUAGE# link:logicalOr{ext-relative}[|| Logical OR] +* #LANGUAGE# link:../Bitwise%20Operators/bitwiseNot{ext-relative}[~ Bitwise NOT] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Boolean Operators/logicalOr.adoc b/Language/Structure/Boolean Operators/logicalOr.adoc new file mode 100644 index 000000000..c80ed5f9a --- /dev/null +++ b/Language/Structure/Boolean Operators/logicalOr.adoc @@ -0,0 +1,54 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += || Logical OR + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Logical OR* results in a `true` if either of the two operands is `true`. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +This operator can be used inside the condition of an link:../Control%20Structures/if[if] statement. + +[source,arduino] +---- +if (x > 0 || y > 0) { // if either x or y is greater than zero + // statements +} +---- + +[%hardbreaks] + +[float] +=== Notes and Warnings +Do not confuse the boolean || (double pipe) operator with the bitwise OR operator | (single pipe). +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:logicalAnd{ext-relative}[&& Logical AND] +* #LANGUAGE# link:logicalNot{ext-relative}[! Logical NOT] +* #LANGUAGE# link:../Bitwise%20Operators/bitwiseNot{ext-relative}[| Bitwise OR] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Compound Operators/compoundAddition.adoc b/Language/Structure/Compound Operators/compoundAddition.adoc new file mode 100644 index 000000000..00c015890 --- /dev/null +++ b/Language/Structure/Compound Operators/compoundAddition.adoc @@ -0,0 +1,64 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += += Compound Addition + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This is a convenient shorthand to perform addition on a variable with another constant or variable. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +x += y; // equivalent to the expression x = x + y; +---- + +[float] +=== Parameters +`x`: variable. *Allowed data types:* int, float, double, byte, short, long + +`y`: variable or constant. *Allowed data types:* int, float, double, byte, short, long + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +x = 2; +x += 4; // x now contains 6 +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../Arithmetic%20Operators/addition{ext-relative}[Normal Addition] +* #LANGUAGE# link:compoundSubtraction{ext-relative}[Compound Subtraction] +* #LANGUAGE# link:compoundMultiplication{ext-relative}[Compound Multiplication] +* #LANGUAGE# link:compoundDivision{ext-relative}[Compound Division] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Compound Operators/compoundBitwiseAnd.adoc b/Language/Structure/Compound Operators/compoundBitwiseAnd.adoc new file mode 100644 index 000000000..5cf5dba0c --- /dev/null +++ b/Language/Structure/Compound Operators/compoundBitwiseAnd.adoc @@ -0,0 +1,106 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += &= Compound Bitwise AND + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== 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. +[%hardbreaks] + +A review of the Bitwise AND `&` operator: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 0 0 1 (operand1 & operand2) - returned result +[%hardbreaks] + +[float] +=== Syntax +[source,arduino] +---- +x &= y; // equivalent to x = x & y; +---- + +[float] +=== Parameters +`x`: variable. *Allowed data types:* char, int, long + +`y`: variable or constant. *Allowed data types:* char, int, long + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +Bits that are "bitwise ANDed" with 0 are cleared to 0 so, if myByte is a byte variable, + +[source,arduino] +---- +myByte & B00000000 = 0; +---- + +Bits that are "bitwise ANDed" with 1 are unchanged so, + +[source,arduino] +---- +myByte & B11111111 = myByte; +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +Because we are dealing with bits in a bitwise operator - it is convenient to use the binary formatter with constants. 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?) + +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 + + 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 + + bits unchanged + bits 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 + + bits unchanged + bits cleared + +So if: + +[source,arduino] +---- +myByte = 10101010; +myByte &= B1111100; // results in B10101000 +---- + +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../Bitwise%20Operators/bitwiseAnd{ext-relative}[& Bitwise AND] +* #LANGUAGE# link:compoundBitwiseOr{ext-relative}[|= Compound Bitwise OR] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Compound Operators/compoundBitwiseOr.adoc b/Language/Structure/Compound Operators/compoundBitwiseOr.adoc new file mode 100644 index 000000000..d5b2e01ca --- /dev/null +++ b/Language/Structure/Compound Operators/compoundBitwiseOr.adoc @@ -0,0 +1,102 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += |= Compound Bitwise OR + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The compound bitwise OR operator `|=` is often used with a variable and a constant to "set" (set to 1) particular bits in a variable. +[%hardbreaks] + +A review of the Bitwise OR `|` operator: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) - returned result +[%hardbreaks] + +[float] +=== Syntax +[source,arduino] +---- +x |= y; // equivalent to x = x | y; +---- + +[float] +=== Parameters +`x`: variable. *Allowed data types:* char, int, long + +`y`: variable or constant. *Allowed data types:* char, int, long + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +Bits that are "bitwise ORed" with 0 are unchanged, so if myByte is a byte variable, +[source,arduino] +---- +myByte | B00000000 = myByte; +---- + +Bits that are "bitwise ORed" with 1 are set to 1 so: +[source,arduino] +---- +myByte | B11111111 = B11111111; +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +Because we are dealing with bits in a bitwise operator - it is convenient to use the binary formatter with constants. 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. +[%hardbreaks] + +Consequently - to set bits 0 & 1 of a variable, while leaving the rest of the variable unchanged, use the compound bitwise OR operator (|=) with the constant B00000011 + + 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 + + bits unchanged + bits set + + +Here is the same representation with the variables 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 + + bits unchanged + bits set + +So if: +[source,arduino] +---- +myByte = B10101010; +myByte |= B00000011 == B10101011; +---- +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../Bitwise%20Operators/bitwiseOr{ext-relative}[& Bitwise OR] +* #LANGUAGE# link:compoundBitwiseAnd{ext-relative}[&= Compound Bitwise AND] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Compound Operators/compoundDivision.adoc b/Language/Structure/Compound Operators/compoundDivision.adoc new file mode 100644 index 000000000..e19ee7f38 --- /dev/null +++ b/Language/Structure/Compound Operators/compoundDivision.adoc @@ -0,0 +1,64 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += /= Compound Division + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This is a convenient shorthand to perform division of a variable with another constant or variable. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +x /= y; // equivalent to the expression x = x / y; +---- + +[float] +=== Parameters +`x`: variable. *Allowed data types:* int, float, double, byte, short, long + +`y`: *non zero* variable or constant. *Allowed data types:* int, float, double, byte, short, long + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +x = 2; +x /= 2; // x now contains 1 +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../Arithmetic%20Operators/division{ext-relative}[Normal Division] +* #LANGUAGE# link:compoundAddition{ext-relative}[Compound Addition] +* #LANGUAGE# link:compoundSubtraction{ext-relative}[Compound Subtraction] +* #LANGUAGE# link:compoundMultiplication{ext-relative}[Compound Multiplication] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Compound Operators/compoundMultiplication.adoc b/Language/Structure/Compound Operators/compoundMultiplication.adoc new file mode 100644 index 000000000..ce8d21f36 --- /dev/null +++ b/Language/Structure/Compound Operators/compoundMultiplication.adoc @@ -0,0 +1,64 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += *= Compound Multiplication + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This is a convenient shorthand to perform multiplication of a variable with another constant or variable. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +x *= y; // equivalent to the expression x = x * y; +---- + +[float] +=== Parameters +`x`: variable. *Allowed data types:* int, float, double, byte, short, long + +`y`: variable or constant. *Allowed data types:* int, float, double, byte, short, long + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +x = 2; +x *= 2; // x now contains 4 +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../Arithmetic%20Operators/multiplication{ext-relative}[Normal Multiplication] +* #LANGUAGE# link:compoundAddition{ext-relative}[Compound Addition] +* #LANGUAGE# link:compoundSubtraction{ext-relative}[Compound Subtraction] +* #LANGUAGE# link:compoundDivision{ext-relative}[Compound Division] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Compound Operators/compoundSubtraction.adoc b/Language/Structure/Compound Operators/compoundSubtraction.adoc new file mode 100644 index 000000000..7e6873546 --- /dev/null +++ b/Language/Structure/Compound Operators/compoundSubtraction.adoc @@ -0,0 +1,64 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += -= Compound Subtraction + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This is a convenient shorthand to perform subtraction of a constant or a variable from a variable. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +x -= y; // equivalent to the expression x = x - y; +---- + +[float] +=== Parameters +`x`: variable. *Allowed data types:* int, float, double, byte, short, long + +`y`: variable or constant. *Allowed data types:* int, float, double, byte, short, long + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +x = 20; +x -= 2; // x now contains 18 +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../Arithmetic%20Operators/subtraction{ext-relative}[Normal Subtraction] +* #LANGUAGE# link:compoundAddition{ext-relative}[Compound Addition] +* #LANGUAGE# link:compoundMultiplication{ext-relative}[Compound Multiplication] +* #LANGUAGE# link:compoundDivision{ext-relative}[Compound Division] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Compound Operators/decrement.adoc b/Language/Structure/Compound Operators/decrement.adoc new file mode 100644 index 000000000..eda7b9422 --- /dev/null +++ b/Language/Structure/Compound Operators/decrement.adoc @@ -0,0 +1,62 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += -- Decrement + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Decrements the value of a variable by 1. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +x-- ; // decrement x by one and returns the old value of x +--x ; // decrement x by one and returns the new value of x +---- + +[float] +=== Parameters +`x`: variable. *Allowed data types:* integer, long (possibly unsigned) + +[float] +=== Returns +The original or newly decremented value of the variable. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +x = 2; +y = --x; // x now contains 1, y contains 1 +y = x--; // x contains 0, but y still contains 1 +---- +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:increment{ext-relative}[Increment] +* #LANGUAGE# link:compoundSubtraction{ext-relative}[Compound Subtraction] +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Compound Operators/increment.adoc b/Language/Structure/Compound Operators/increment.adoc new file mode 100644 index 000000000..e8a0d0c41 --- /dev/null +++ b/Language/Structure/Compound Operators/increment.adoc @@ -0,0 +1,67 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += ++ Increment + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Increments the value of a variable by 1. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +x++; // increment x by one and returns the old value of x +++x; // increment x by one and returns the new value of x +---- + +[float] +=== Parameters +`x`: variable. *Allowed data types:* integer, long (possibly unsigned) + +[float] +=== Returns +The original or newly incremented value of the variable. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +x = 2; +y = ++x; // x now contains 3, y contains 3 +y = x++; // x contains 4, but y still contains 3 +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:decrement{ext-relative}[Decrement] +* #LANGUAGE# link:compoundAddition{ext-relative}[Compound Addition] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Control Structure/break.adoc b/Language/Structure/Control Structure/break.adoc new file mode 100644 index 000000000..7fe2dc19f --- /dev/null +++ b/Language/Structure/Control Structure/break.adoc @@ -0,0 +1,52 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += break + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +[%hardbreaks] +`break` is used to exit from a link:for{ext-relative}[for], link:while{ext-relative}[while] or link:doWhile{ext-relative}[do...while] loop, bypassing the normal loop condition. It is also used to exit from a link:switchCase{ext-relative}[switch case] statement. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- +[float] +=== Example Code +In the following code, the control exits the `for` loop when the sensor value exceeds the threshold. +[source,arduino] +---- +for (x = 0; x < 255; x ++) +{ + digitalWrite(PWMpin, x); + sens = analogRead(sensorPin); + if (sens > threshold){ // bail out on sensor detect + x = 0; + break; + } + delay(50); +} +---- +[%hardbreaks] + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:continue{ext-relative}[continue] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Control Structure/continue.adoc b/Language/Structure/Control Structure/continue.adoc new file mode 100644 index 000000000..552e2c86a --- /dev/null +++ b/Language/Structure/Control Structure/continue.adoc @@ -0,0 +1,53 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += continue + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +[%hardbreaks] +The `continue` statement skips the rest of the current iteration of a loop (link:for{ext-relative}[for], link:while{ext-relative}[while], or link:doWhile{ext-relative}[do...while]). It continues by checking the conditional expression of the loop, and proceeding with any subsequent iterations. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +The following code writes the value of 0 to 255 to the `PWMpin`, but skips the values in the range of 41 to 119. +[source,arduino] +---- +for (x = 0; x <= 255; x ++) +{ + if (x > 40 && x < 120){ // create jump in values + continue; + } + + digitalWrite(PWMpin, x); + delay(50); +} +---- +[%hardbreaks] + + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:break{ext-relative}[break] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Control Structure/doWhile.adoc b/Language/Structure/Control Structure/doWhile.adoc new file mode 100644 index 000000000..afee15128 --- /dev/null +++ b/Language/Structure/Control Structure/doWhile.adoc @@ -0,0 +1,60 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += do...while loop + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +[%hardbreaks] +The `do...while` loop works in the same manner as the link:while{ext-relative}[while] loop, with the exception that the condition is tested at the end of the loop, so the do loop will always run at least once. + +[float] +=== Syntax +[source,arduino] +---- +do +{ + // statement block +} while (condition); +---- +The `condition` is a boolean expression that evaluates to `true` or `false`. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +do +{ + delay(50); // wait for sensors to stabilize + x = readSensors(); // check the sensors + +} while (x < 100); +---- +[%hardbreaks] + + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:for{ext-relative}[for] +* #LANGUAGE# link:while{ext-relative}[while] +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Control Structure/else.adoc b/Language/Structure/Control Structure/else.adoc new file mode 100644 index 000000000..d467be583 --- /dev/null +++ b/Language/Structure/Control Structure/else.adoc @@ -0,0 +1,73 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += if...else + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The `if...else` allows greater control over the flow of code than the basic link:if{ext-relative}[if] statement, by allowing multiple tests to be grouped together. An `else` clause (if at all exists) will be executed if the condition in the `if` statement results in `false`. The `else` can proceed another `if` test, so that multiple, mutually exclusive tests can be run at the same time. +[%hardbreaks] + +Each test will proceed to the next one until a true test is encountered. When a true test is found, its associated block of code is run, and the program then skips to the line following the entire if/else construction. If no test proves to be true, the default `else` block is executed, if one is present, and sets the default behavior. +[%hardbreaks] + +Note that an `else if` block may be used with or without a terminating `else` block and vice versa. An unlimited number of such `else if` branches is allowed. + +[float] +=== Syntax +[source,arduino] +---- +if (condition1) +{ + // do Thing A +} +else if (condition2) +{ + // do Thing B +} +else +{ + // do Thing C +} +---- +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- +[float] +=== Example Code +Below is an extract from a code for temperature sensor system +[source,arduino] +---- +if (temperature >= 70) +{ + //Danger! Shut down the system +} +else if (temperature >= 60 && temperature < 70) +{ + //Warning! User attention required +} +else +{ + //Safe! Continue usual tasks... +} +---- + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:switchCase{ext-relative}[switch case] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Control Structure/for.adoc b/Language/Structure/Control Structure/for.adoc new file mode 100644 index 000000000..f8d63b1c6 --- /dev/null +++ b/Language/Structure/Control Structure/for.adoc @@ -0,0 +1,104 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += for loop + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The `for` statement is used to repeat a block of statements enclosed in curly braces. An increment counter is usually used to increment and terminate the loop. The `for` statement is useful for any repetitive operation, and is often used in combination with arrays to operate on collections of data/pins. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +for (initialization; condition; increment) { + //statement(s); +} +---- + +The *initialization* happens first and exactly once. Each time through the loop, the *condition* is tested; if it's `true`, the statement block, and the *increment* is executed, then the *condition* is tested again. When the *condition* becomes `false`, the loop ends. +[%hardbreaks] + + +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +[source,arduino] +---- +// Dim an LED using a PWM pin +int PWMpin = 10; // LED in series with 470 ohm resistor on pin 10 + +void setup() +{ + // no setup needed +} + +void loop() +{ + for (int i=0; i <= 255; i++){ + analogWrite(PWMpin, i); + delay(10); + } +} +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +The C `for` loop is much more flexible than `for` loops found in some other computer languages, including BASIC. Any or all of the three header elements may be omitted, although the semicolons are required. Also the statements for initialization, condition, and increment can be any valid C statements with unrelated variables, and use any C datatypes including floats. These types of unusual `for` statements may provide solutions to some rare programming problems. +[%hardbreaks] + +For example, using a multiplication in the increment line will generate a logarithmic progression: + +[source,arduino] +---- +for(int x = 2; x < 100; x = x * 1.5){ +println(x); +} +---- + +Generates: 2,3,4,6,9,13,19,28,42,63,94 +[%hardbreaks] + +Another example, fade an LED up and down with one `for` loop: + +[source,arduino] +---- +void loop() +{ + int x = 1; + for (int i = 0; i > -1; i = i + x){ + analogWrite(PWMpin, i); + if (i == 255) x = -1; // switch direction at peak + delay(10); + } +} +---- + + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:while{ext-relative}[while] + + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Control Structure/goto.adoc b/Language/Structure/Control Structure/goto.adoc new file mode 100644 index 000000000..f328f65ba --- /dev/null +++ b/Language/Structure/Control Structure/goto.adoc @@ -0,0 +1,70 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += goto + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Transfers program flow to a labeled point in the program +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +label: + +goto label; // sends program flow to the label +---- + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +for(byte r = 0; r < 255; r++){ + for(byte g = 255; g > -1; g--){ + for(byte b = 0; b < 255; b++){ + if (analogRead(0) > 250){ goto bailout;} + // more statements ... + } + } +} + +bailout: +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +The use of `goto` is discouraged in C programming, and some authors of C programming books claim that the `goto` statement is never necessary, but used judiciously, it can simplify certain programs. The reason that many programmers frown upon the use of goto is that with the unrestrained use of `goto` statements, it is easy to create a program with undefined program flow, which can never be debugged. + +With that said, there are instances where a `goto` statement can come in handy, and simplify coding. One of these situations is to break out of deeply nested link:for{ext-relative}[for] loops, or link:if{ext-relative}[if] logic blocks, on a certain condition. +[%hardbreaks] + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:continue{ext-relative}[continue] +* #LANGUAGE# link:break{ext-relative}[break] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Control Structure/if.adoc b/Language/Structure/Control Structure/if.adoc new file mode 100644 index 000000000..7ffa9464f --- /dev/null +++ b/Language/Structure/Control Structure/if.adoc @@ -0,0 +1,79 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += if (conditional) and ==, !=, <, > (comparison operators) + + +// OVERVIEW SECTION STARTS +[#overview] +-- +[float] +=== Description +The `if` statement checks for a condition and executes the proceeding statement or set of statements if the condition is 'true'. +[%hardbreaks] + +[float] +=== Syntax +[source,arduino] +---- +if (condition) +{ + //statement(s) +} +---- + +[float] +=== Parameters +condition: a boolean expression i.e., can be `true` or `false` + +[float] +=== Example Code + +The brackets may be omitted after an if statement. If this is done, the next line (defined by the semicolon) becomes the only conditional statement. +[%hardbreaks] + +[source,arduino] +---- +if (x > 120) digitalWrite(LEDpin, HIGH); + +if (x > 120) +digitalWrite(LEDpin, HIGH); + +if (x > 120){ digitalWrite(LEDpin, HIGH); } + +if (x > 120){ + digitalWrite(LEDpin1, HIGH); + digitalWrite(LEDpin2, HIGH); +} // all are correct +---- +[%hardbreaks] + + +[float] +=== Notes and Warnings +The statements being evaluated inside the parentheses require the use of one or more operators shown below. +[%hardbreaks] + +*Comparison Operators:* + + x == y (x is equal to y) + x != y (x is not equal to y) + x < y (x is less than y) + x > y (x is greater than y) + x <= y (x is less than or equal to y) + x >= y (x is greater than or equal to y) + + +Beware of accidentally using the single equal sign (e.g. `if (x = 10)` ). 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 (http://arduino.cc/en/Reference/Assignment[assignment operator^])), so `x` now contains 10. Then the 'if' conditional evaluates 10, which always evaluates to `TRUE`, since any non-zero number evaluates to TRUE. Consequently, `if (x = 10)` will always evaluate to `TRUE`, which is not the desired result when using an 'if' statement. Additionally, the variable `x` will be set to 10, which is also not a desired action. +[%hardbreaks] + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:else{ext-relative}[if...else] +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Control Structure/return.adoc b/Language/Structure/Control Structure/return.adoc new file mode 100644 index 000000000..6ae3c7894 --- /dev/null +++ b/Language/Structure/Control Structure/return.adoc @@ -0,0 +1,81 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += return + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Terminate a function and return a value from a function to the calling function, if desired. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +return; + +return value; // both forms are valid +---- + + +[float] +=== Parameters +`value': any variable or constant type + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +A function to compare a sensor input to a threshold + +[source,arduino] +---- + int checkSensor(){ + if (analogRead(0) > 400) { + return 1; + else{ + return 0; + } +} +---- + +The return keyword is handy to test a section of code without having to "comment out" large sections of possibly buggy code. +[source,arduino] +---- +void loop(){ + +// brilliant code idea to test here + +return; + +// the rest of a dysfunctional sketch here +// this code will never be executed +} +---- +[%hardbreaks] + + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:break{ext-relative}[break] +* #LANGUAGE# link:continue{ext-relative}[continue] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Control Structure/switchCase.adoc b/Language/Structure/Control Structure/switchCase.adoc new file mode 100644 index 000000000..cd88abeb9 --- /dev/null +++ b/Language/Structure/Control Structure/switchCase.adoc @@ -0,0 +1,85 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += switch...case statement + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Like link:if{ext-relative}[if] statements, link:switchCase{ext-relative}[switch case] controls the flow of programs by allowing programmers to specify different code that should be executed in various conditions. In particular, a switch statement compares the value of a variable to the values specified in case statements. When a case statement is found whose value matches that of the variable, the code in that case statement is run. +[%hardbreaks] + +The link:break{ext-relative}[break] keyword exits the switch statement, and is typically used at the end of each case. Without a break statement, the switch statement will continue executing the following expressions ("falling-through") until a break, or the end of the switch statement is reached. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +switch (var) { + case label1: + // statements + break; + case label2: + // statements + break; + default: + // statements +} +---- + + +[float] +=== Parameters +`var`: a variable whose value to compare with various cases. *Allowed data types:* int, char + +`label1`, `label2`: constants. *Allowed data types:* int, char + +[float] +=== Returns +Nothing + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- + switch (var) { + case 1: + //do something when var equals 1 + break; + case 2: + //do something when var equals 2 + break; + default: + // if nothing else matches, do the default + // default is optional + } + +---- +[%hardbreaks] + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:else{ext-relative}[if...else] +* #LANGUAGE# link:break{ext-relative}[break] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Control Structure/while.adoc b/Language/Structure/Control Structure/while.adoc new file mode 100644 index 000000000..943287f7f --- /dev/null +++ b/Language/Structure/Control Structure/while.adoc @@ -0,0 +1,62 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += while loop + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +[%hardbreaks] +A `while` loop will loop continuously, and infinitely, until the expression inside the parenthesis, () becomes false. Something must change the tested variable, or the while loop will never exit. This could be in your code, such as an incremented variable, or an external condition, such as testing a sensor. + +[float] +=== Syntax +[source,arduino] +---- +while(condition){ + // statement(s) +} +---- +The `condition` is a boolean expression that evaluates to `true` or `false`. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +var = 0; +while(var < 200){ + // do something repetitive 200 times + var++; +} +---- +[%hardbreaks] + + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:doWhile{ext-relative}[do...while] + +[role="example"] +* #EXAMPLE# http://arduino.cc/en/Tutorial/WhileLoop[While Loop Tutorial^] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Further Syntax/blockComment.adoc b/Language/Structure/Further Syntax/blockComment.adoc new file mode 100644 index 000000000..c2e5723f6 --- /dev/null +++ b/Language/Structure/Further Syntax/blockComment.adoc @@ -0,0 +1,66 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += /* */ Block Comment + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Comments* are lines in the program that are used to inform yourself or others about the way the program works. They are ignored by the compiler, and not exported to the processor, so they don't take up any space in the microcontroller's flash memory. Comments' only purpose is to help you understand (or remember), or to inform others about how your program works. +[%hardbreaks] + +The beginning of a *block comment* or a *multi-line comment* is marked by the symbol `/\*` and the symbol `*/` marks its end. This type of a comment is called so as this can extend over more than one line; once the compiler reads the `/\*` it ignores whatever follows unitl it enounters a `*/`. + +// NOTE TO THE EDITOR: The '\' before the '*' in certain places are to escape the '*' from making the text bolder. +// In places were '\' is not used before '*', it is not actually required. +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +[source,arduino] +---- +/* This is a valid comment */ + +/* + Blink + Turns on an LED on for one second, then off for one second, repeatedly. + + This example code is in the public domain. + (Another valid comment) +*/ + +/* + if (gwb == 0){ // single line comment is OK inside a multi-line comment + x = 3; /* but not another multi-line comment - this is invalid */ + } +// don't forget the "closing" comment - they have to be balanced! +*/ +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +When experimenting with code, "commenting out" parts of your program is a convenient way to remove lines that may be buggy. This leaves the lines in the code, but turns them into comments, so the compiler just ignores them. This can be especially useful when trying to locate a problem, or when a program refuses to compile and the compiler error is cryptic or unhelpful. +[%hardbreaks] + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:singleLineComment{ext-relative}[// Single Line Comment] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Further Syntax/curlyBraces.adoc b/Language/Structure/Further Syntax/curlyBraces.adoc new file mode 100644 index 000000000..dcc0ae1ec --- /dev/null +++ b/Language/Structure/Further Syntax/curlyBraces.adoc @@ -0,0 +1,105 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + += {} Curly Braces + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Curly braces (also referred to as just "braces" or as "curly brackets") are a major part of the C programming language. They are used in several different constructs, outlined below, and this can sometimes be confusing for beginners. + +An opening curly brace `{` must always be followed by a closing curly brace `}`. This is a condition that is often referred to as the braces being balanced. The Arduino IDE (Integrated Development Environment) includes a convenient feature to check the balance of curly braces. Just select a brace, or even click the insertion point immediately following a brace, and its logical companion will be highlighted. +[%hardbreaks] +Beginners programmers, and programmers coming to C from the BASIC language often find using braces confusing or daunting. After all, the same curly braces replace the RETURN statement in a subroutine (function), the ENDIF statement in a conditional and the NEXT statement in a FOR loop. +[%hardbreaks] +Unbalanced braces can often lead to cryptic, impenetrable compiler errors that can sometimes be hard to track down in a large program. Because of their varied usages, braces are also incredibly important to the syntax of a program and moving a brace one or two lines will often dramatically affect the meaning of a program. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +The main uses of curly braces are listed in the examples below. + + +[float] +==== Functions + +[source,arduino] +---- +void myfunction(datatype argument){ + statements(s) +} +---- +[%hardbreaks] + + +[float] +==== Loops + +[source,arduino] +---- +while (boolean expression) +{ + statement(s) +} + +do +{ + statement(s) +} while (boolean expression); + +for (initialisation; termination condition; incrementing expr) +{ + statement(s) +} +---- +[%hardbreaks] + + + + +[float] +==== Conditional Statements + +[source,arduino] +---- +if (boolean expression) +{ + statement(s) +} + +else if (boolean expression) +{ + statement(s) +} +else +{ + statement(s) +} +---- +[%hardbreaks] + + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:semicolon{ext-relative}[; Semicolon] +* #LANGUAGE# link:singleLineComment{ext-relative}[// Single Line Comment] +* #LANGUAGE# link:blockComment{ext-relative}[/* */ Block Comment] + + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Further Syntax/define.adoc b/Language/Structure/Further Syntax/define.adoc new file mode 100644 index 000000000..cc81c78a1 --- /dev/null +++ b/Language/Structure/Further Syntax/define.adoc @@ -0,0 +1,78 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += #define + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +`#define` is a useful C component that allows the programmer to give a name to a constant value before the program is compiled. Defined constants in arduino don't take up any program memory space on the chip. The compiler will replace references to these constants with the defined value at compile time. +[%hardbreaks] + +This can have some unwanted side effects though, if for example, a constant name that had been #defined is included in some other constant or variable name. In that case the text would be replaced by the #defined number (or text). +[%hardbreaks] + +In general, the link:../../Variables/Variable%20Scope%20&%20Qualifiers/const{ext-relative}[const] keyword is preferred for defining constants and should be used instead of #define. +[%hardbreaks] + +[float] +=== Syntax +[source,arduino] +---- +#define constantName value +---- +Note that the # is necessary. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +#define ledPin 3 +// The compiler will replace any mention of ledPin with the value 3 at compile time. +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +There is no semicolon after the #define statement. If you include one, the compiler will throw cryptic errors further down the page. + +[source,arduino] +---- +#define ledPin 3; // this is an error +---- + +Similarly, including an equal sign after the #define statement will also generate a cryptic compiler error further down the page. + +[source,arduino] +---- +#define ledPin = 3 // this is also an error +---- +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../Variables/Variable%20Scope%20&%20Qualifiers/const{ext-relative}[const] +* #LANGUAGE# link:../../Variables/Constants/integerConstants{ext-relative}[Constants] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Further Syntax/include.adoc b/Language/Structure/Further Syntax/include.adoc new file mode 100644 index 000000000..9761f44ad --- /dev/null +++ b/Language/Structure/Further Syntax/include.adoc @@ -0,0 +1,54 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += #include + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +`#include` is used to include outside libraries in your sketch. This gives the programmer access to a large group of standard C libraries (groups of pre-made functions), and also libraries written especially for Arduino. +[%hardbreaks] + +The main reference page for AVR C libraries (AVR is a reference to the Atmel chips on which the Arduino is based) is http://www.nongnu.org/avr-libc/user-manual/modules.html[here^]. +[%hardbreaks] + +Note that `#include`, similar to link:define{ext-relative}[`#define`], has no semicolon terminator, and the compiler will yield cryptic error messages if you add one. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +This example includes a library that is used to put data into the program space _flash_ instead of _ram_. This saves the ram space for dynamic memory needs and makes large lookup tables more practical. + + +[source,arduino] +---- +#include + +prog_uint16_t myConstants[] PROGMEM = {0, 21140, 702 , 9128, 0, 25764, 8456, +0,0,0,0,0,0,0,0,29810,8968,29762,29762,4500}; +---- +[%hardbreaks] + + +[float] +=== See also + + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Further Syntax/semicolon.adoc b/Language/Structure/Further Syntax/semicolon.adoc new file mode 100644 index 000000000..a6c8253d1 --- /dev/null +++ b/Language/Structure/Further Syntax/semicolon.adoc @@ -0,0 +1,48 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += ; Semicolon + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Used to end a statement. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 13; +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +Forgetting to end a line in a semicolon will result in a compiler error. The error text may be obvious, and refer to a missing semicolon, or it may not. If an impenetrable or seemingly illogical compiler error comes up, one of the first things to check is a missing semicolon, in the immediate vicinity, preceding the line at which the compiler complained. +[%hardbreaks] + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:semicolon{ext-relative}[; Semicolon] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Further Syntax/singleLineComment.adoc b/Language/Structure/Further Syntax/singleLineComment.adoc new file mode 100644 index 000000000..272fe2ce8 --- /dev/null +++ b/Language/Structure/Further Syntax/singleLineComment.adoc @@ -0,0 +1,55 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += // Single Line Comment + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Comments* are lines in the program that are used to inform yourself or others about the way the program works. They are ignored by the compiler, and not exported to the processor, so they don't take up any space in the microcontroller's flash memory. Comments' only purpose is to help you understand (or remember), or to inform others about how your program works. +[%hardbreaks] + +A *single line comment* begins with `//` (two adjacent slashes). This comment ends automatically at the end of a line. whatever follows `//` till the end of a line will be ignored by the compiler. +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +There are two different ways of marking a line as a comment: + +[source,arduino] +---- +// Pin 13 has an LED connected on most Arduino boards. +// give it a name: +int led = 13; + + +digitalWrite(led, HIGH); // turn the LED on (HIGH is the voltage level) +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +When experimenting with code, "commenting out" parts of your program is a convenient way to remove lines that may be buggy. This leaves the lines in the code, but turns them into comments, so the compiler just ignores them. This can be especially useful when trying to locate a problem, or when a program refuses to compile and the compiler error is cryptic or unhelpful. +[%hardbreaks] + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:blockComment{ext-relative}[/* */ Block Comment] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Main/loop.adoc b/Language/Structure/Main/loop.adoc new file mode 100644 index 000000000..f44395804 --- /dev/null +++ b/Language/Structure/Main/loop.adoc @@ -0,0 +1,60 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += loop() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +After creating a link:setup{ext-relative}[setup()] function, which initializes and sets the initial values, the `loop()` function does precisely what its name suggests, and loops consecutively, allowing your program to change and respond. Use it to actively control the Arduino board. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +[source,arduino] +---- +int buttonPin = 3; + +// setup initializes serial and the button pin +void setup() +{ + beginSerial(9600); + pinMode(buttonPin, INPUT); +} + +// loop checks the button pin each time, +// and will send serial if it is pressed +void loop() +{ + if (digitalRead(buttonPin) == HIGH) + serialWrite('H'); + else + serialWrite('L'); + + delay(1000); +} +---- +[%hardbreaks] + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:setup{ext-relative}[setup()] +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Main/setup.adoc b/Language/Structure/Main/setup.adoc index 7e96be04c..278f9be8b 100644 --- a/Language/Structure/Main/setup.adoc +++ b/Language/Structure/Main/setup.adoc @@ -1,61 +1,53 @@ -:source-highlighter: pygments -:pygments-style: arduino -:ext-relative: adoc - -= setup() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -The `setup()` function is called when a sketch starts. Use it to initialize variables, pin modes, when you start using libraries, etc. The setup function will only run once, after each powerup or reset of the Arduino board. -[%hardbreaks] - -[float] -=== Syntax -`setup()` - -[float] -=== Returns -Nothing - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int buttonPin = 3; - -void setup() -{ - Serial.begin(9600); - pinMode(buttonPin, INPUT); -} - -void loop() -{ - // ... -} ----- -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - -[float] -=== See also -[role="language"] -* #LANGUAGE# link:Loop{ext-relative}[loop^] +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += setup() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The `setup()` function is called when a sketch starts. Use it to initialize variables, pin modes, start using libraries, etc. The `setup()` function will only run once, after each powerup or reset of the Arduino board. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int buttonPin = 3; + +void setup() +{ + Serial.begin(9600); + pinMode(buttonPin, INPUT); +} + +void loop() +{ + // ... +} +---- +[%hardbreaks] + +[float] +=== See also +[role="language"] +* #LANGUAGE# link:loop{ext-relative}[loop()] +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Pointer Access Operators/dereference.adoc b/Language/Structure/Pointer Access Operators/dereference.adoc new file mode 100644 index 000000000..2cc0ffe35 --- /dev/null +++ b/Language/Structure/Pointer Access Operators/dereference.adoc @@ -0,0 +1,55 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += * Dereference Operator + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Dereferencing is one of the features specifically for use with pointers. The asterisk operator `*` is used for this purpose. If `p` is a pointer, then `*p` represents the value contained in the address pointed by `p`. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int *p; // declare a pointer to an int data type +int i = 5, result = 0; +p = &i; // now 'p' contains the address of 'i' +result = *p; // 'result' gets the value at the address pointed by 'p' + // i.e., it gets the value of 'i' which is 5 +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +Pointers are one of the complicated subjects for beginners in learning C, and it is possible to write the vast majority of Arduino sketches without ever encountering pointers. However for manipulating certain data structures, the use of pointers can simplify the code, and and knowledge of manipulating pointers is handy to have in one's toolkit. +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:reference{ext-relative}[& Reference Operator] + +[role="definition"] +* #DEFINITION# http://en.wikipedia.org/wiki/Pointer_%28computer_programming%29[Pointers^] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Structure/Pointer Access Operators/reference.adoc b/Language/Structure/Pointer Access Operators/reference.adoc new file mode 100644 index 000000000..cd50805f3 --- /dev/null +++ b/Language/Structure/Pointer Access Operators/reference.adoc @@ -0,0 +1,55 @@ +:source-highlighter: pygments +:pygments-style: arduino +:ext-relative: adoc + + += & Reference Operator + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Referencing is one of the features specifically for use with pointers. The ampersand operator `&` is used for this purpose. If `x` is a variable, then `&x` represents the address of the variable `x`. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int *p; // declare a pointer to an int data type +int i = 5, result = 0; +p = &i; // now 'p' contains the address of 'i' +result = *p; // 'result' gets the value at the address pointed by 'p' + // i.e., it gets the value of 'i' which is 5 +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +Pointers are one of the complicated subjects for beginners in learning C, and it is possible to write the vast majority of Arduino sketches without ever encountering pointers. However for manipulating certain data structures, the use of pointers can simplify the code, and and knowledge of manipulating pointers is handy to have in one's toolkit. +[%hardbreaks] + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:dereference{ext-relative}[* Dereference Operator] + +[role="definition"] +* #DEFINITION# http://en.wikipedia.org/wiki/Pointer_%28computer_programming%29[Pointers^] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Variables/Utilities/PROGMEM.adoc b/Language/Variables/Utilities/PROGMEM.adoc index 047c5fa97..e82a9c811 100644 --- a/Language/Variables/Utilities/PROGMEM.adoc +++ b/Language/Variables/Utilities/PROGMEM.adoc @@ -24,29 +24,22 @@ The `PROGMEM` keyword is a variable modifier, it should be used only with the da [float] === Syntax -`dataType variableName[] PROGMEM = {dataInt0, dataInt1, dataInt3...};` +const dataType variableName[] PROGMEM = {data0, data1, data3...};` -`program memory dataType` - any program memory variable type (see below) +`dataType` - any variable type `variableName` - the name for your array of data -Note that because PROGMEM is a variable modifier, there is no hard and fast rule about where it should go, so the Arduino compiler accepts all of the definitions below, which are also synonymous. However experiments have indicated that, in various versions of Arduino (having to do with GCC version), PROGMEM may work in one location and not in another. The "string table" example below has been tested to work with Arduino 13. Earlier versions of the IDE may work better if PROGMEM is included after the variable name. +Note that because PROGMEM is a variable modifier, there is no hard and fast rule about where it should go, so the Arduino compiler accepts all of the definitions below, which are also synonymous. However experiments have indicated that, in various versions of Arduino (having to do with GCC version), PROGMEM may work in one location and not in another. The "string table" example below has been tested to work with Arduino 13. Earlier versions of the IDE may work better if PROGMEM is included after the variable name. + +`const dataType variableName[] PROGMEM = {}; // use this form` + +`const PROGMEM dataType variableName[] = {}; // or this one`+ +`const dataType PROGMEM variableName[] = {}; // not this one -`dataType variableName[] PROGMEM = {}; // use this form` + -`dataType PROGMEM variableName[] = {}; // not this one` + -`PROGMEM dataType variableName[] = {}; // use this form` While `PROGMEM` could be used on a single variable, it is really only worth the fuss if you have a larger block of data that needs to be stored, which is usually easiest in an array, (or another C data structure beyond our present discussion). Using `PROGMEM` is also a two-step procedure. After getting the data into Flash memory, it requires special methods (functions), also defined in the http://www.nongnu.org/avr-libc/user-manual/group__avr__pgmspace.html[pgmspace.h] library, to read the data from program memory back into SRAM, so we can do something useful with it. -As mentioned above, it is important to use the datatypes outlined in http://www.nongnu.org/avr-libc/user-manual/group__avr__pgmspace.html[pgmspace.h]. Some cryptic bugs are generated by using ordinary datatypes for program memory calls. Below is a list of variable types to use. Floating point numbers in program memory do not appear to be supported. - - `prog_char` - a signed char (1 byte) -127 to 128 + - `prog_uchar` - an unsigned char (1 byte) 0 to 255 + - `prog_int16_t` - a signed int (2 bytes) -32,767 to 32,768 + - `prog_uint16_t` - an unsigned int (2 bytes) 0 to 65,535 + - `prog_int32_t` - a signed long (4 bytes) -2,147,483,648 to * 2,147,483,647. + - `prog_uint32_t` - an unsigned long (4 bytes) 0 to 4,294,967,295 [%hardbreaks] -- // OVERVIEW SECTION ENDS @@ -69,20 +62,43 @@ The following code fragments illustrate how to read and write unsigned chars (by // save some unsigned ints -PROGMEM prog_uint16_t charSet[] = { 65000, 32796, 16843, 10, 11234}; +const PROGMEM uint16_t charSet[] = { 65000, 32796, 16843, 10, 11234}; // save some chars -prog_uchar signMessage[] PROGMEM = {"I AM PREDATOR, UNSEEN COMBATANT. CREATED BY THE UNITED STATES DEPART"}; +const char signMessage[] PROGMEM = {"I AM PREDATOR, UNSEEN COMBATANT. CREATED BY THE UNITED STATES DEPART"}; unsigned int displayInt; int k; // counter variable char myChar; -// read back a 2-byte int - displayInt = pgm_read_word_near(charSet + k) -// read back a char -myChar = pgm_read_byte_near(signMessage + k); +void setup() { + Serial.begin(9600); + while (!Serial); + + // put your setup code here, to run once: + // read back a 2-byte int + for (k = 0; k < 5; k++) + { + displayInt = pgm_read_word_near(charSet + k); + Serial.println(displayInt); + } + Serial.println(); + + // read back a char + for (k = 0; k < strlen(signMessage); k++) + { + myChar = pgm_read_byte_near(signMessage + k); + Serial.print(myChar); + } + + Serial.println(); +} + +void loop() { + // put your main code here, to run repeatedly: + +} ---- *Arrays of strings* @@ -105,34 +121,28 @@ These tend to be large structures so putting them into program memory is often d here is a good template to follow. Setting up the strings is a two-step process. First define the strings. - */ #include -prog_char string_0[] PROGMEM = "String 0"; // "String 0" etc are strings to store - change to suit. -prog_char string_1[] PROGMEM = "String 1"; -prog_char string_2[] PROGMEM = "String 2"; -prog_char string_3[] PROGMEM = "String 3"; -prog_char string_4[] PROGMEM = "String 4"; -prog_char string_5[] PROGMEM = "String 5"; +const char string_0[] PROGMEM = "String 0"; // "String 0" etc are strings to store - change to suit. +const char string_1[] PROGMEM = "String 1"; +const char string_2[] PROGMEM = "String 2"; +const char string_3[] PROGMEM = "String 3"; +const char string_4[] PROGMEM = "String 4"; +const char string_5[] PROGMEM = "String 5"; // Then set up a table to refer to your strings. -PROGMEM const char *string_table[] = // change "string_table" name to suit -{ - string_0, - string_1, - string_2, - string_3, - string_4, - string_5 }; +const char* const string_table[] PROGMEM = {string_0, string_1, string_2, string_3, string_4, string_5}; char buffer[30]; // make sure this is large enough for the largest string it must hold void setup() { Serial.begin(9600); + while(!Serial); + Serial.println("OK"); } @@ -147,10 +157,11 @@ void loop() for (int i = 0; i < 6; i++) { strcpy_P(buffer, (char*)pgm_read_word(&(string_table[i]))); // Necessary casts and dereferencing, just copy. - Serial.println( buffer ); + Serial.println(buffer); delay( 500 ); } } + ---- [%hardbreaks]