Document the overflow behavior

[meithecatte]

I cannot find any information on what happens when the result of an arithmetic operation does not fit in the value range of an integer. Is it wrapping around, a panic, or perhaps nasal demons or other undefined behavior?

[thbwd]

The compiler does not use nsw/nuw flags, therefore:

If the sum has unsigned overflow, the result returned is the mathematical result modulo 2n, where n is the bit width of the result.

If the difference has unsigned overflow, the result returned is the mathematical result modulo 2n, where n is the bit width of the result.

If the result of the multiplication has unsigned overflow, the result returned is the mathematical result modulo 2n, where n is the bit width of the result.

Division by zero is undefined behavior. For vectors, if any element of the divisor is zero, the operation has undefined behavior. Overflow also leads to undefined behavior; this is a rare case, but can occur, for example, by doing a 32-bit division of -2147483648 by -1.

If you want to add that to the documentation, that would be very welcome.