aboutsummaryrefslogtreecommitdiffstats
path: root/source/lang/api/constants.rst
blob: 72738b8ce31badcdc5218ffe3bd39f522df360da (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
.. _lang-constants:

Constants
=========

Constants are like predefined variables, whose values can't
change. They are used to make the programs easier to read and modify.
This page describes the most commonly used constants.

.. contents:: Contents
   :local:

.. _lang-constants-bool:

Boolean Constants
-----------------

There are two constants used to represent truth and falsity: ``true``,
and ``false``.

.. _lang-constants-false:

false
^^^^^

``false`` is the false ``bool`` value. An integer which is 0 evaluates
to ``false`` as a boolean.

.. _lang-constants-true:

true
^^^^

``true`` is the true ``bool`` value.  As an integer, ``true`` is often
said to be 1.  This is correct in the sense that ``true`` evaluates to
1 as an integer.  However, any integer which is *non-zero* is ``true``
as a :ref:`bool <lang-booleanvariables>`. So -1, 2 and -200 are all
"true", in the sense that these numbers are treated the same as
``true`` in a boolean context.

Note that the ``true`` and ``false`` constants are typed in lowercase;
unlike e.g. ``HIGH``, ``LOW``, ``INPUT``, and ``OUTPUT`` (which are
described below).


Pin Levels: HIGH and LOW
------------------------

When reading or writing to a digital pin there are only two possible
values a pin can be set to: ``HIGH`` and ``LOW``.

.. _lang-constants-high:

HIGH
^^^^

The meaning of ``HIGH`` (in reference to a pin) is somewhat different
depending on whether the pin is set to ``INPUT`` or ``OUTPUT``. When a
pin is configured as an ``INPUT`` (using :ref:`pinMode()
<lang-pinmode>`), and read with :ref:`digitalRead()
<lang-digitalread>`, the microcontroller will report ``HIGH`` if a
voltage of 3 volts or more is present at the pin.

.. TODO? Following seems false; check it out sometime, leave out for now:

.. A pin may also be configured as an ``INPUT`` with ``pinMode()``, and
.. subsequently made ``HIGH`` with :ref:`digitalWrite()
.. <lang-digitalwrite>`, this will set the internal pullup resistors,
.. which will *steer* the input pin to a HIGH reading unless it is pulled
.. LOW by external circuitry.

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
pin configured as an output and set to ``LOW``.

.. _lang-constants-low:

LOW
^^^

The meaning of ``LOW`` also has a different meaning depending on
whether a pin is set to ``INPUT`` or ``OUTPUT``. When a pin is
configured as an ``INPUT`` with :ref:`pinMode() <lang-pinmode>`, and
read with :ref:`digitalRead() <lang-digitalread>`, the microcontroller
will report ``LOW`` if a voltage of 2 volts or less is present at the
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
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
output, and set to ``HIGH``.

Pin Modes
---------

Digital pins can be used in a variety of modes.  The basic modes,
``INPUT`` and ``OUTPUT``, have been introduced above.  Changing a pin
from ``INPUT`` TO ``OUTPUT`` with :ref:`pinMode() <lang-pinmode>`
drastically changes the electrical behavior of the pin.

This section describes the basic digital pin modes (``INPUT`` and
``OUTPUT``) only.  For a detailed description of all possible pin
modes, see the :ref:`pinMode() <lang-pinmode>` reference page.

.. _lang-constants-input:

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.

.. _lang-constants-output:

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.

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.

.. _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``.

Normally, integer literals 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:

.. list-table::
   :header-rows: 1

   * - Base
     - Example
     - Formatter
     - Comment

   * - 10 (decimal)
     - ``123``
     - None
     -

   * - 2 (binary)
     - ``0b1111011``
     - Leading "0b"
     - GCC extension; not standard C++

   * - 8 (octal)
     - ``0173``
     - Leading "0"
     - Characters 0-7 valid

   * - 16 (hexadecimal)
     - ``0x7B``
     - Leading "0x"
     - 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.

.. _lang-constants-integers-dec:

**Decimal** is base 10. This is the common number system we learn in
school.  Integer literals without other prefixes are assumed to be in
decimal format.

For example, the decimal literal ``101`` is one hundred and one: 1×10\
:sup:`2` + 0×10\ :sup:`1` + 1×10\ :sup:`0` = 101.

.. _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++).

For example, the binary literal ``0b101`` is five: 1×2\ :sup:`2` +
0×2\ :sup:`1` + 1×2\ :sup:`0` = 5.

.. _lang-constants-integers-oct:

**Octal** is base eight. Only characters 0 through 7 are valid.  Octal
literals are indicated by the prefix ``0``.

For example, the octal literal ``0101`` is sixty five: 1×8\ :sup:`2` +
0×8\ :sup:`1` + 1×8\ :sup:`0` = 65.

.. warning:: Bugs sometimes result by (unintentionally) including a
   leading "0" before an integer literal, which makes the compiler
   interpret it in octal.

.. _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).

For example, the hexadecimal literal ``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
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
``C``\ =12 and ``F``\ =15).

.. _lang-constants-integers-u-l:

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:

- a ``u`` or ``U`` to interpret the constant as an unsigned value.
  For example, ``33U`` is an :ref:`unsigned int <lang-unsignedint>`.

- an ``l`` or ``L`` to interpret the constant as a long value.  For
  example, ``100000L`` is a :ref:`long <lang-long>`.  On the Maple,
  ``long`` is just a synonym for ``int``.

- a ``ul`` or ``UL`` to do both.  For example, ``32767UL`` is an
  :ref:`unsigned long <lang-unsignedlong>`.  On the Maple, ``unsigned
  long`` is just a synonym for ``unsigned int``.

- an ``ll`` or ``LL`` to interpret the constant as a :ref:`long long
  <lang-longlong>` value.

- a ``ull`` or ``ULL`` to interpret the constant as an :ref:`unsigned
  long long <lang-unsignedlonglong>`.

.. _lang-constants-fp:

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``.

Floating point constants can also be expressed in a variety of
scientific notation. ``E`` and ``e`` are both accepted as valid
exponent indicators.  Some examples are given in the following table:


.. list-table::
   :header-rows: 1

   * - Floating-point literal
     - Evaluates to
     - Alternate expression

   * - ``10.0``
     - 10
     -

   * - ``2.34E5``
     - 2.34×10\ :sup:`5`
     - ``234000.0``

   * - ``67e-12``
     - 67.0×10\ :sup:`-12`
     - ``0.000000000067``

.. _lang-constants-board:

Board-Specific Constants
------------------------

This section documents constants whose value might change across
different LeafLabs boards.  You can use these constants to help ensure
that your code will be portable across different boards.

.. TODO replace "upcoming" when Mini, Native come out

.. _lang-constants-led:

- ``BOARD_LED_PIN``: the number of the pin which connects to the
  built-in LED.  On the Maple, this is pin 13, but it's not guaranteed
  to be the same in upcoming boards like the Maple Mini.

.. _lang-constants-but:

- ``BOARD_BUTTON_PIN``: the number of the pin which connects to the
  built-in button (labeled "BUT").  On the Maple, this is pin 38, but
  it's not guaranteed to be the same in other boards.

See Also
--------

- :ref:`pinMode() <lang-pinmode>`
- :ref:`Boolean Variables <lang-booleanvariables>`
- :ref:`#define <lang-define>`
- :ref:`int <lang-int>`
- :ref:`unsigned int <lang-unsignedint>`
- :ref:`long <lang-long>`
- :ref:`unsigned long <lang-unsignedlong>`
- :ref:`long long <lang-longlong>`
- :ref:`unsigned long long <lang-unsignedlonglong>`
- :ref:`float <lang-float>`
- :ref:`double <lang-double>`

.. include:: cc-attribution.txt