Fix documentation about int "roll over"

[cousteaulecommandant]

Currently the documentation for int claims that int wraps when overflowing. This is not the case; signed integer overflow is undefined behavior and the GCC compiler used by Arduino may do weird things (see bug #4511).
This bug would be solved by pull request #4624, but until it is accepted, it would be nice to change the documentation and remove the whole "coding tip" paragraph (or at least leave it commented until Arduino handles it as the documentation claims).
I already requested this on arduino/reference-en#23 but apparently this repository is more appropriate for requesting documentation changes.

[agdl]

Can you please provide and example to show this? Did you notice this only on AVR or also on SAM and SAMD?

[cousteaulecommandant]

It should affect both AVR and SAM.

Bug #4511 explains this issue in detail. Here's an example snippet:

bool will_overflow(int x) {
    int y = x+1;
    return y < x; // compiler assumes this will never happen => will always return false
}

#include <limits.h>  // INT_MAX
void start() {
    pinMode(13, OUTPUT);
}
void loop() {
    int res = will_overflow(INT_MAX);  // returns false instead of true, even though INT_MAX+1 overflows
    digitalWrite(13, res);  // LED (pin 13) should turn on, but it is off
}

I don't have a physical Arduino to try this right now (neither AVR nor ARM/SAM), but enabling the -Wall warnings (File > Preferences > Settings > Compiler warnings: More/All) displays this warning message (for both AVR and SAM):

warning: assuming signed overflow does not occur when assuming that (X + c) < X is always false [-Wstrict-overflow]
     return y < x;
                ^

Basically, "this should not happen" when you're writing a C++ (or C) compliant program; doing so is forbidden according to the standard, so the compiler is free to assume that it will never happen when optimizing the code (which happens with -O2 or greater, which is what Arduino uses).

GCC provides a -fwrapv option to override this behavior, as I mentioned in issue #4511 and PR #4624. Honestly I'd prefer this "bug" to be fixed rather than documented, but even if it gets fixed it might be important to document it in case someone's using an old version.

PS: as I said I haven't physically tested this code snippet (although I did back in the day), and undefined behavior being undefined behavior it might be possible that it does something unexpected such as working.

[cmaglie]

Documentation is fixed, let's continue on #4624 about frwap option