I just sent a newbie to the map() function and he wrote back saying it wasn't clear. I then re-read it and he has a point. The first paragraph of its documentation says:
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.
but nowhere does it explain where those parameters appear in the function's signature. It might be helpful to provide a function prototype using those terms, like:
Appendix
For the mathematically inclined, here’s the whole function
long map(long x, long in_min, long in_max, long out_min, long out_max)
{
return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
}
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
True, and we can go round-and-round on this, but if a newbie doesn't think it's clear, and it's pretty easy to help that along, it wouldn't be that hard to add a function prototype and use that as the center of discussion. Otherwise, why use the first paragraph at all?
it wouldn't be that hard to add a function prototype and use that as the center of discussion.
I think the example using hard-coded values sucks. Using variables with the names mentioned before the example would make it clear what the inputs are.
Used to use a similar function called "scale" (by Allen - Bradley IIRC) in PLC work that gave me fits until I just stopped, went through it line by line, tried it with trial numbers I could do in my head 'til I "got" it, it's really simple once you "get" it.
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.
Say, the new value in the new map is x; how do I relate x with all other 5 parameters? So, a complete declaration of function prototype is required along with data types.
Post#1 has provided the correct form of function prototype from which we know that the function supports -ve numbers; but, it does not support floating point numbers.
Applying the map formula of Post#1, I get 169 for x. I have scaled down/compressed the input value. What is the advantage of such compression?
GolamMostafa:
Applying the map formula of Post#1, I get 169 for x. I have scaled down/compressed the input value. What is the advantage of such compression?
For example, I'm working with a TFT display that has pixel limits for the x value from 22 to 190, or 168 pixels for values of x. The data coming from my sensor can have any value between 0 and 1023. So if I read the value 512, that should sit "in the middle" of the x axis. The map() function makes it easy for me to use an x pixel value of 106 to represent the analog value 512.
In other words, the map() function makes it easy to scale data between disparate data sets.
GolamMostafa:
What is the advantage of such compression?
Since an analogRead() is from 0-1023 (a potentiometer, for example) while an analogWrite() is only 0-255 (an led say), the answer to that is trivially clear from the comment in the example code:
/* Map an analog value to 8 bits (0 to 255) */
void setup() {}
void loop()
{
int val = analogRead(0);
val = map(val, 0, 1023, 0, 255);
analogWrite(9, val);
}
LesserMole:
Since an analogRead() is from 0-1023 (a potentiometer, for example) while an analogWrite() is only 0-255 (an led say), the answer to that is trivially clear from the comment in the example code:
/* Map an analog value to 8 bits (0 to 255) */
void setup() {}
void loop()
{
int val = analogRead(0);
val = map(val, 0, 1023, 0, 255);
analogWrite(9, val);
}
That is one of the classic uses for map(), but what you are really doing in that example is dividing by 4 which you can do very efficiently by bit shifting.
It's indeed a problem with that page, the paragraph Syntax is empty... If you look at another ref page (for example analogRead()) it has the info that's missing here. The paragraph syntax should have
map(value, fromLow, fromHigh, toLow, toHigh)
Is there someone who has already forked the ref pages and can do a pull request?
