map()

Description

Re-maps a number from one range to another. That is, a value of fromLow would get mapped to toLow, a value of fromHigh to toHigh, values in-between to values in-between, etc.

Does not constrain values to within the range, because out-of-range values are sometimes intended and useful. The

constrain()

Note that the "lower bounds" of either range may be larger or smaller than the "upper bounds" so the

map()

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 and works well.

The

map()

Syntax

map(value, fromLow, fromHigh, toLow, toHigh)

Parameters

• value

  : the number to map

• fromLow

  : the lower bound of the value’s current range

• fromHigh

  : the upper bound of the value’s current range

• toLow

  : the lower bound of the value’s target range

• toHigh

  : the upper bound of the value’s target range

Returns

The mapped value. Data type:

long

Example Code

1/* Map an analog value to 8 bits (0 to 255) */
2    void setup() {}
3
4    void loop() {
5      int val = analogRead(0);
6      val = map(val, 0, 1023, 0, 255);
7      analogWrite(9, val);
8    }

Appendix

For the mathematically inclined, here’s the whole function

1long map(long x, long in_min, long in_max, long out_min, long out_max) {
2      return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
3    }

Notes & Warnings

As previously mentioned, the map() function uses integer math. So fractions might get suppressed due to this. For example, fractions like 3/2, 4/3, 5/4 will all be returned as 1 from the map() function, despite their different actual values. So if your project requires precise calculations (e.g. voltage accurate to 3 decimal places), please consider avoiding map() and implementing the calculations manually in your code yourself.

See also

• abs()
• constrain()
• max()
• min()
• pow()
• sq()
• sqrt()