From 2a6e20afda4ef2494218a691156fc0aad276c93f Mon Sep 17 00:00:00 2001 From: "A.J. Gardner" Date: Mon, 17 Apr 2017 23:17:53 -0500 Subject: [PATCH 1/3] Add details about integer overflow --- src/behavior-not-considered-unsafe.md | 42 ++++++++++++++++++--------- 1 file changed, 29 insertions(+), 13 deletions(-) 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 From 25e919bcd1197e0451835c1756fd4c5af7e344ce Mon Sep 17 00:00:00 2001 From: "A.J. Gardner" Date: Mon, 17 Apr 2017 23:36:49 -0500 Subject: [PATCH 2/3] Shrink the undocumented list --- src/undocumented.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/undocumented.md b/src/undocumented.md index c3ae24788..27a98e7e3 100644 --- a/src/undocumented.md +++ b/src/undocumented.md @@ -16,8 +16,6 @@ to shrink! in [Conditional compilation] - [Unambiguous function call syntax] - [Require parentheses for chained comparisons] -- [Integer overflow not `unsafe`] - documented with a reference to the RFC, but - requires further details - [`dllimport`] - one element mentioned but not explained at [FFI attributes] - [define `crt_link`] - [define `unaligned_access`] From 1fc592442d43cc0fc4d590483df8782942f8c006 Mon Sep 17 00:00:00 2001 From: "A.J. Gardner" Date: Sun, 4 Jun 2017 20:55:41 -0500 Subject: [PATCH 3/3] Rephrase and clarify integer overflow semantics --- src/behavior-not-considered-unsafe.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/src/behavior-not-considered-unsafe.md b/src/behavior-not-considered-unsafe.md index a938daa6d..7e2e2db79 100644 --- a/src/behavior-not-considered-unsafe.md +++ b/src/behavior-not-considered-unsafe.md @@ -10,20 +10,27 @@ or erroneous. ##### Integer overflow If a program contains arithmetic overflow, the programmer has made an -error. +error. In the following discussion, we maintain a distinction between +arithmetic overflow and wrapping arithmetic. The first is erroneous, +while the second is intentional. 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. +example, by enabling a non-optimized build), implementations must +insert dynamic checks that `panic` on overflow. Other kinds of builds +may result in `panics` or silently wrapped values on overflow, at the +implementation's discretion. + +In the case of implicitly-wrapped overflow, implementations must +provide well-defined (even if still considered erroneous) results by +using two's complement overflow conventions. 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. +explicitly to perform wrapping arithmetic. For example, +`i32::wrapping_add` provides two's complement, wrapping addition. The standard library also provides a `Wrapping` newtype which -overloads arithmetic operators by way of the `WrappingOps` trait. +ensures all standard arithmetic operations for `T` have wrapping +semantics. See [RFC 560] for error conditions, rationale, and more details about integer overflow.