constrain() is a macro -- please change reference page?

Development Tools IDE 1.x
1

i realize this is an old, outstanding issue, but the reference page page at

really ought to state, even in small print, that constrain() is a macro, and has Side Effects. i know it's not a simple thing to explain to relatively inexperienced programmers (i gave up trying to formulate a simple example for this post without a lot of digression) but it's fairly serious.

it would be better if constrain(), and any other macros, were recoded as overloaded functions.

i tried to search the Reference to find reference to anything else implemented as a macro (eg. toupper()) but failed.

2

They actually did add a warning to min() and max() about this:

https://www.arduino.cc/en/Reference/Max
But it's missing from other macros that would have the same problem, such as constrain. It would be better to avoid presenting beginners with these pitfalls completely but a warning is better than nothing.

3

I just got hit by this. Fortunately, it "smelled" like a macro problem and a Google search landed me here, first.

Any macro should be called out as such in the reference due to potential (likely) side-effect issues.

Thanks,

4

I have now added a warning to the documentation for constrain() and sq(). I believe all the problematic macros in the Language Reference now have warnings, but if anyone spots one I missed, please let me know.