diff options
| -rw-r--r-- | docs/source/lang/api/constants.rst | 94 |
1 files changed, 44 insertions, 50 deletions
diff --git a/docs/source/lang/api/constants.rst b/docs/source/lang/api/constants.rst index 3ba99f0..6f69dfe 100644 --- a/docs/source/lang/api/constants.rst +++ b/docs/source/lang/api/constants.rst @@ -62,7 +62,7 @@ pin is configured as an ``INPUT`` (using :ref:`pinMode() <lang-digitalread>`, the microcontroller will report ``HIGH`` if a voltage of 3 volts or more is present at the pin. -When a pin is configured to ``OUTPUT`` with pinMode, and set to +When a pin is configured to ``OUTPUT`` with ``pinMode()``, and set to ``HIGH`` with :ref:`digitalWrite() <lang-digitalwrite>`, the pin is at 3.3 volts. In this state it can *source* current, e.g. light an LED that is connected through a series resistor to ground, or to another @@ -82,9 +82,9 @@ pin. When a pin is configured to ``OUTPUT`` with ``pinMode()``, and set to ``LOW`` with :ref:`digitalWrite() <lang-digitalwrite>`, the -microcontroller will attempt to keep that pin's voltage at 0V. In this +microcontroller will attempt to keep that pin's voltage at 0 V. In this state it can *sink* current, e.g. light an LED that is connected -through a series resistor to +3.3V, or to another pin configured as an +through a series resistor to +3.3 V, or to another pin configured as an output, and set to ``HIGH``. Pin Modes @@ -104,11 +104,11 @@ modes, see the :ref:`pinMode() <lang-pinmode>` reference page. INPUT ^^^^^ -Maple (STM32) pins configured as ``INPUT`` are said to be in a -high-impedance state. One way of explaining this is that pins -configured as ``INPUT`` make extremely small demands on the circuit -that they are sampling. This makes them useful for reading a sensor, -but not powering an LED. +Pins configured as ``INPUT`` are said to be in a *high-impedance +state*. One way of explaining this is that pins configured as +``INPUT`` make very few demans on circuit that they are connected +to. This makes them useful for reading a sensor, but not powering an +LED. .. _lang-constants-output: @@ -117,31 +117,31 @@ OUTPUT Pins configured as ``OUTPUT`` with :ref:`pinMode() <lang-pinmode>` are said to be in a low-impedance state. This means that they can provide -a substantial amount of current to other circuits. STM32 pins can -source (provide positive current) or sink (provide negative current) -up to 50 mA (milliamps) of current to other devices/circuits. This -makes them useful for powering LEDs, but useless for reading sensors. +a substantial amount of current to other circuits. Pins can source +(provide positive current) or sink (provide negative current) up to 50 +mA (milliamps) of current to other devices/circuits. This makes them +useful for powering LEDs, but useless for reading sensors. Pins configured as outputs can also be damaged or destroyed if short -circuited to either ground or 3.3V power rails. The amount of current -provided by an STM32 pin is also not enough to power most relays or -motors, and some interface circuitry will be required. +circuited to either ground or power supplies. The amount of current +provided by a pin is also not enough to power most relays or motors, +and some interface circuitry will be required. .. _lang-constants-integers: Integer Constants ----------------- -Integer constants (or more properly speaking, integer *literals*) are -numbers used directly in a sketch, like ``123``. By default, an -integer literal is treated as a (signed) :ref:`int <lang-int>`, but -you can change this with the U and L modifiers (see :ref:`below -<lang-constants-integers-u-l>`). You can specify negative numbers by -putting a minus sign in front, like ``-123``. +Integer constants are numbers used directly in a sketch, like +``123``. By default, an integer constant is treated as a (signed) +:ref:`int <lang-int>`, but you can change this with the U and L +modifiers (see :ref:`below <lang-constants-integers-u-l>`). You can +specify negative numbers by putting a minus sign in front, like +``-123``. -Normally, integer literals are treated as base 10 (decimal) integers, +Normally, integer constants are treated as base 10 (decimal) integers, but special notation (formatters) may be used to enter numbers in -other bases. These are summarized in the following table: +other bases. These are explained in the following table: .. list-table:: :header-rows: 1 @@ -172,8 +172,8 @@ other bases. These are summarized in the following table: - Characters 0-9, A-F (or a-f) valid Binary constants (like ``B1111011``) for values between 0 and 255 are -supported for compatibility with Arduino only. Their use in new -programs is discouraged. +supported for compatibility with Arduino only. You shouldn't use them +in new programs. .. _lang-constants-integers-dec: @@ -187,8 +187,7 @@ For example, the decimal literal ``101`` is one hundred and one: 1×10\ .. _lang-constants-integers-bin: **Binary** is base two. Only characters 0 and 1 are valid. Binary -literals are indicated by the prefix ``0b`` (this is a :ref:`GCC -<arm-gcc>` extension; it's not standard C++). +literals are indicated by the prefix ``0b``. For example, the binary literal ``0b101`` is five: 1×2\ :sup:`2` + 0×2\ :sup:`1` + 1×2\ :sup:`0` = 5. @@ -203,19 +202,19 @@ For example, the octal literal ``0101`` is sixty five: 1×8\ :sup:`2` + .. warning:: Bugs sometimes result by (unintentionally) including a leading "0" before an integer literal, which makes the compiler - interpret it in octal. + treat it as an octal number. .. _lang-constants-integers-hex: **Hexadecimal** (or "hex") is base sixteen. Valid characters are 0 through 9 and letters A through F; A has the value 10, B is 11, up to -F, which is 15. Hex values are indicated by the prefix ``0x``. A-F -may be typed in upper or lower case (a-f). +F, which is 15. Hex values are indicated by the prefix ``0x``. A-F +can be typed in upper or lower case (a-f). -For example, the hexadecimal literal ``0x101`` is two hundred fifty +For example, the hexadecimal constant ``0x101`` is two hundred fifty seven: 1×16\ :sup:`2` + 0×16\ :sup:`1` + 1×16\ :sup:`0` = 257. -The hexadecimal literal ``0xCF2`` is three thousand, three hundred +The hexadecimal constant ``0xCF2`` is three thousand, three hundred fourteen: 12×16\ :sup:`2` + 15×16\ :sup:`1` + 2×16\ :sup:`0` = 3314. (Remember that in hex, ``A`` means 10, and counting up, ``B``\ =11, so @@ -226,10 +225,10 @@ fourteen: 12×16\ :sup:`2` + 15×16\ :sup:`1` + 2×16\ :sup:`0` = 3314. U and L Suffixes ^^^^^^^^^^^^^^^^ -By default, an integer constant is treated as an :ref:`int -<lang-int>`, with the attendant :ref:`limitations in values -<lang-int-overflow>`. To specify an integer constant with another data -type, follow it with: +By default, an integer constant is treated as an :ref:`int <lang-int>` +(and must be in the int type's :ref:`range limits +<lang-int-overflow>`). To specify an integer constant with another +data type, follow it with: - a ``u`` or ``U`` to interpret the constant as an unsigned value. For example, ``33U`` is an :ref:`unsigned int <lang-unsignedint>`. @@ -253,17 +252,12 @@ type, follow it with: Floating-Point Constants ------------------------ -Similar to integer literals, floating point constants (properly: -floating-point *literals*) are used to make code more readable. -Floating point literals are swapped at compile time for the value to -which the expression evaluates. - -A floating point literal is any number which includes a decimal point. -For instance, ``3.0`` is a floating-point literal for the number 3. -By default, a floating-point literal is a :ref:`double <lang-double>`. -In order for the literal to be interpreted as a :ref:`float -<lang-float>`, you can write ``f`` directly after it. For example, -``3.0f`` is a floating-point literal with type ``float``. +A floating point constant is any number which includes a decimal +point. For instance, ``3.0`` is a floating-point constant for the +number 3. By default, a floating-point constant is a :ref:`double +<lang-double>`. In order for the constant to be interpreted as a +:ref:`float <lang-float>`, you can write ``f`` directly after it. For +example, ``3.0f`` is a floating-point constant with type ``float``. Floating point constants can also be expressed in a variety of scientific notation. ``E`` and ``e`` are both accepted as valid @@ -273,7 +267,7 @@ exponent indicators. Some examples are given in the following table: .. list-table:: :header-rows: 1 - * - Floating-point literal + * - Floating-point constant - Evaluates to - Alternate expression @@ -297,8 +291,8 @@ Board-Specific Constants There are several :ref:`board-specific constants <lang-board-values>` whose value depends on which LeafLabs board you have. If you use them, it will help make sure that your code will work well on all -LeafLabs boards, not just the one you have. This will make it much -easier to share your code with others. +LeafLabs boards, not just the one you have. This will make it easier +to share your code with others. For example, the pin number connected to the board's built-in LED is different on the different boards, but the board-specific constant |