aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/lang/api/map.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/lang/api/map.rst')
-rw-r--r--docs/source/lang/api/map.rst68
1 files changed, 68 insertions, 0 deletions
diff --git a/docs/source/lang/api/map.rst b/docs/source/lang/api/map.rst
new file mode 100644
index 0000000..79122b3
--- /dev/null
+++ b/docs/source/lang/api/map.rst
@@ -0,0 +1,68 @@
+.. highlight:: cpp
+
+.. _lang-map:
+
+map()
+=====
+
+Re-maps a number from one range to another.
+
+.. contents:: Contents
+ :local:
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: map
+
+Discussion
+----------
+
+``map()`` does not constrain values to within the range, because
+out-of-range values are sometimes intended and useful. The
+:ref:`constrain() <lang-constrain>` macro may be used either before or
+after this function, if limits to the ranges are desired.
+
+Note that the "lower bounds" of either range may be larger or smaller
+than the "upper bounds" so that ``map()`` may be used to reverse a
+range of numbers; for example::
+
+ y = map(x, 1, 50, 50, 1);
+
+The function also handles negative numbers well, so that this
+example ::
+
+ y = map(x, 1, 50, 50, -100);
+
+is also valid.
+
+The ``map()`` function uses integer math (its arguments and return
+values all have type :ref:`long <lang-long>`), so it will not generate
+fractions, when the math might indicate that it should do so.
+Fractional remainders are truncated, and are not rounded or averaged.
+
+Example
+-------
+
+::
+
+ /* Map an ADC reading (12 bits) to 16-bit PWM (0 to 65,535) */
+
+ void setup() {
+ pinMode(0, INPUT_ANALOG);
+ pinMode(9, PWM);
+ }
+
+ void loop() {
+ int val = analogRead(0);
+ val = map(val, 0, 4095, 0, 65535);
+ analogWrite(9, val);
+ }
+
+
+See Also
+--------
+
+- :ref:`constrain() <lang-constrain>`
+
+.. include:: cc-attribution.txt