Add details about integer overflow

[mrhota]

CC #9

[mrhota]

I asserted that arithmetic overflow indicates programmer error, which is stronger than the claim in RFC 560. However, I do point users at the wrapping_xxx inherent methods for programmers to annotate and explicitly ask for wrapping arithmetic.

I remained confused after reading the RFC about Rust's overflow semantics. It seemed to indicate two's complement, wrapping overflow is the default if the compiler doesn't insert dynamic checks, but it also indicated an implementation could insert static or dynamic checks at any time to panic or prevent this behavior, excepting of course uses of the wrapping primitives.

[mrhota]

r? @steveklabnik

[mrhota]

@steveklabnik ping

[steveklabnik]

Hey @mrhota sorry about this.

I remained confused after reading the RFC about Rust's overflow semantics. It seemed to indicate two's complement, wrapping overflow is the default if the compiler doesn't insert dynamic checks, but it also indicated an implementation could insert static or dynamic checks at any time to panic or prevent this behavior, excepting of course uses of the wrapping primitives.

My understanding is that it's like this:

1. overflow is a "programmer error", that is, not UB, but not well-formed.
2. In the case of overflow:
   1. When debug_assertions are enabled, implementations are required to panic at runtime.
   2. When they are not enabled, implementations are allowed to panic or not panic.
   3. If they choose to not panic, overflow is well-defined as two's compliment overflow.
3. If overflow is a desired behavior, then using the wrapper types is the proper way to do it.

So, it seems like this PR is correct, though maybe not complete, exactly. Thoughts?

[mrhota]

@steveklabnik that's very helpful. I'll clarify what I have written.

[steveklabnik]

@mrhota ping!

[mrhota]

@steveklabnik OK, give these changes a shot. I hope it clarifies things

[steveklabnik]

Looks great, thank you!