diff --git a/src/behavior-not-considered-unsafe.md b/src/behavior-not-considered-unsafe.md index e16103372..a938daa6d 100644 --- a/src/behavior-not-considered-unsafe.md +++ b/src/behavior-not-considered-unsafe.md @@ -1,15 +1,31 @@ -## Behavior not considered unsafe - -This is a list of behavior not considered *unsafe* in Rust terms, but that may -be undesired. - -* Deadlocks -* Leaks of memory and other resources -* Exiting without calling destructors -* Integer overflow - - Overflow is considered "unexpected" behavior and is always user-error, - unless the `wrapping` primitives are used. In non-optimized builds, the compiler - will insert debug checks that panic on overflow, but in optimized builds overflow - instead results in wrapped values. See [RFC 560] for the rationale and more details. +## Behavior not considered `unsafe` + +The Rust compiler does not consider the following behaviors _unsafe_, +though a programmer may (should) find them undesirable, unexpected, +or erroneous. + +##### Deadlocks +##### Leaks of memory and other resources +##### Exiting without calling destructors +##### Integer overflow + +If a program contains arithmetic overflow, the programmer has made an +error. + +When the programmer has enabled `debug_assert!` assertions (for +example, by enabling a non-optimized build), the compiler will insert +dynamic checks that `panic` on overflow. Other kinds of builds may +result in silently wrapped values on overflow. + +The integral types provide inherent methods to allow programmers +explicitly to perform wrapping arithmetic. For example, (using UFCS) +`i32::wrapping_add` provides two's complement, wrapping addition, as +in `a + b` in the C programming language. + +The standard library also provides a `Wrapping` newtype which +overloads arithmetic operators by way of the `WrappingOps` trait. + +See [RFC 560] for error conditions, rationale, and more details about +integer overflow. [RFC 560]: https://github.com/rust-lang/rfcs/blob/master/text/0560-integer-overflow.md