From 8ceca524f4a411f88308c40c432d6eaeec86b855 Mon Sep 17 00:00:00 2001 From: bstrie Date: Mon, 13 May 2019 17:36:05 -0400 Subject: [PATCH 01/13] Initial draft --- text/0000-associated-constants-on-ints.md | 164 ++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 text/0000-associated-constants-on-ints.md diff --git a/text/0000-associated-constants-on-ints.md b/text/0000-associated-constants-on-ints.md new file mode 100644 index 00000000000..862d3006cf3 --- /dev/null +++ b/text/0000-associated-constants-on-ints.md @@ -0,0 +1,164 @@ +- Feature Name: assoc-int-consts +- Start Date: 2019-05-13 +- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000) +- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) + +# Summary +[summary]: #summary + +Add the relevant associated constants to the numeric types in the standard library, and consider a timeline for the deprecation of the corresponding (and originally intended to be temporary) primitive numeric modules and associated functions. + +# Motivation +[motivation]: #motivation + +All programming languages with bounded integers provide numeric constants for their maximum and minimum extents. In Rust, [these constants were stabilized](https://github.com/rust-lang/rust/pull/23549) in the eleventh hour before Rust 1.0 (literally the day before the branching of 1.0-beta on April 1, 2015), with some known-to-be-undesirable properties. In particular, associated consts were yet to be implemented (these landed, amusingly, one month after 1.0-beta and two weeks before 1.0-stable), and so each of the twelve numeric types were given their own top-level modules in the standard library, whose contents are exclusively these constants (all related non-constants being defined in inherent impls directly on each type). However, in the even-eleventh-er hour before 1.0-beta, it was realized that this solution did not work for anyone seeking to reference these constants when working with types such as `c_int`, which are defined as type aliases and can thus access inherent impls but not modules that merely happen to be named the same as the original type; as a result, [an emergency PR](https://github.com/rust-lang/rust/pull/23947) also added redundant `max_value` and `min_value` inherent functions as a last-second workaround. The PR itself notes how distasteful this remedy is: + +> It's unfortunate to freeze these as methods, but when we can provide inherent associated constants these methods can be deprecated. [aturon, Apr 1, 2015] + +Meanwhile, the author of the associated consts patch [despairs](https://github.com/rust-lang/rust/pull/23606#issuecomment-88541583) of just barely missing the deadline: + +> @nikomatsakis The original motivation for trying to get this in before the beta was to get rid of all the functions that deal with constants in Int/Float, and then to get rid of all the modules like std::i64 that just hold constants as well. We could have dodged most of the issues (ICEs and generic code design) by using inherent impls instead of associating the constants with traits. But since [#23549](https://github.com/rust-lang/rust/pull/23549) came in a bit earlier and stabilized a bunch more of those constants before the beta, whereas this hasn't landed yet, blegh. [quantheory, Apr 1, 2015] + +Anticipating the situation, an [issue](https://github.com/rust-lang/rfcs/issues/1099) was filed in the RFCs repo regarding moving the contents of these modules into associated consts: + +> I think it's a minor enough breaking change to move the constants and deprecate the modules u8, u16, etc. Not so sure about removing these modules entirely, I'd appreciate that, but it'll break all the code use-ing them. [petrochenkov, Apr 29, 2015] + +Finally, so obvious was this solution that [the original RFC for associated items](https://github.com/nox/rust-rfcs/blob/master/text/0195-associated-items.md#expressiveness) used the numeric constants as the only motivating example for the feature of associated consts: + +> For example, today's Rust includes a variety of numeric traits, including Float, which must currently expose constants as static functions [...] Associated constants would allow the consts to live directly on the traits + +Despite the obvious intent, 1.0 came and went and there were plenty of other things to occupy everyone's attention. Now, two days shy of Rust's fourth anniversary, let's re-examine the situation. We propose to deprecate all of the aforementioned functions and constants in favor of associated constants defined on the appropriate types, and to additionally deprecate the `i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `u8`, `u16`, `u32`, `u64`, `u128`, `usize`, `f32`, and `f64` modules in `std`. Advantages of this: + +1. Consistency with the rest of the language. As demonstrated by the above quotes, associated consts have been the natural way to express these concepts in Rust since before associated consts were even implemented; this approach satisfies the principle of least surprise. + +2. Documentation. On the front page of the [standard library API docs](https://doc.rust-lang.org/std/index.html), 14 of the 56 modules in the standard library (25%) are the aforementioned numeric modules whose only purpose is to namespace these constants. This number will continue to rise as new numeric primitives are added to Rust, as already seen with `i128` and `u128`. Although deprecated modules cannot be easily removed from std, they can be removed from the documentation, making the stdlib API docs less cluttered and easier to navigate. + +3. Beginner ease. For a beginner, finding two identical ways to achieve something immediately raises the question of "why", to which the answer here is ultimately uninteresting (and even then, the question of "which one to use" remains unanswered; neither current approach is idiomatic). As noted, deprecated items can be removed from the documentation, thereby decreasing the likelihood of head-scratching and incredulous sidelong glances from people new to Rust. + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +Deprecate the following items in the standard library: + +```rust +[i8::min_value](https://doc.rust-lang.org/std/primitive.i8.html#method.min_value) +[i8::max_value](https://doc.rust-lang.org/std/primitive.i8.html#method.max_value) +[std::i8::MIN](https://doc.rust-lang.org/std/i8/constant.MIN.html) +[std::i8::MAX](https://doc.rust-lang.org/std/i8/constant.MIN.html) +[i16::min_value](https://doc.rust-lang.org/std/primitive.i16.html#method.min_value) +[i16::max_value](https://doc.rust-lang.org/std/primitive.i16.html#method.max_value) +[std::i16::MIN](https://doc.rust-lang.org/std/i16/constant.MIN.html) +[std::i16::MAX](https://doc.rust-lang.org/std/i16/constant.MIN.html) +[i32::min_value](https://doc.rust-lang.org/std/primitive.i32.html#method.min_value) +[i32::max_value](https://doc.rust-lang.org/std/primitive.i32.html#method.max_value) +[std::i32::MIN](https://doc.rust-lang.org/std/i32/constant.MIN.html) +[std::i32::MAX](https://doc.rust-lang.org/std/i32/constant.MIN.html) +[i64::min_value](https://doc.rust-lang.org/std/primitive.i64.html#method.min_value) +[i64::max_value](https://doc.rust-lang.org/std/primitive.i64.html#method.max_value) +[std::i64::MIN](https://doc.rust-lang.org/std/i64/constant.MIN.html) +[std::i64::MAX](https://doc.rust-lang.org/std/i64/constant.MIN.html) +[i128::min_value](https://doc.rust-lang.org/std/primitive.i128.html#method.min_value) +[i128::max_value](https://doc.rust-lang.org/std/primitive.i128.html#method.max_value) +[std::i128::MIN](https://doc.rust-lang.org/std/i128/constant.MIN.html) +[std::i128::MAX](https://doc.rust-lang.org/std/i128/constant.MIN.html) +[isize::min_value](https://doc.rust-lang.org/std/primitive.isize.html#method.min_value) +[isize::max_value](https://doc.rust-lang.org/std/primitive.isize.html#method.max_value) +[std::isize::MIN](https://doc.rust-lang.org/std/isize/constant.MIN.html) +[std::isize::MAX](https://doc.rust-lang.org/std/isize/constant.MIN.html) +[u8::min_value](https://doc.rust-lang.org/std/primitive.u8.html#method.min_value) +[u8::max_value](https://doc.rust-lang.org/std/primitive.u8.html#method.max_value) +[std::u8::MIN](https://doc.rust-lang.org/std/u8/constant.MIN.html) +[std::u8::MAX](https://doc.rust-lang.org/std/u8/constant.MIN.html) +[u16::min_value](https://doc.rust-lang.org/std/primitive.u16.html#method.min_value) +[u16::max_value](https://doc.rust-lang.org/std/primitive.u16.html#method.max_value) +[std::u16::MIN](https://doc.rust-lang.org/std/u16/constant.MIN.html) +[std::u16::MAX](https://doc.rust-lang.org/std/u16/constant.MIN.html) +[u32::min_value](https://doc.rust-lang.org/std/primitive.u32.html#method.min_value) +[u32::max_value](https://doc.rust-lang.org/std/primitive.u32.html#method.max_value) +[std::u32::MIN](https://doc.rust-lang.org/std/u32/constant.MIN.html) +[std::u32::MAX](https://doc.rust-lang.org/std/u32/constant.MIN.html) +[u64::min_value](https://doc.rust-lang.org/std/primitive.u64.html#method.min_value) +[u64::max_value](https://doc.rust-lang.org/std/primitive.u64.html#method.max_value) +[std::u64::MIN](https://doc.rust-lang.org/std/u64/constant.MIN.html) +[std::u64::MAX](https://doc.rust-lang.org/std/u64/constant.MIN.html) +[u128::min_value](https://doc.rust-lang.org/std/primitive.u128.html#method.min_value) +[u128::max_value](https://doc.rust-lang.org/std/primitive.u128.html#method.max_value) +[std::u128::MIN](https://doc.rust-lang.org/std/u128/constant.MIN.html) +[std::u128::MAX](https://doc.rust-lang.org/std/u128/constant.MIN.html) +[usize::min_value](https://doc.rust-lang.org/std/primitive.usize.html#method.min_value) +[usize::max_value](https://doc.rust-lang.org/std/primitive.usize.html#method.max_value) +[std::usize::MIN](https://doc.rust-lang.org/std/usize/constant.MIN.html) +[std::usize::MAX](https://doc.rust-lang.org/std/usize/constant.MIN.html) +[std::f32::DIGITS](https://doc.rust-lang.org/std/f32/constant.DIGITS.html) +[std::f32::EPSILON](https://doc.rust-lang.org/std/f32/constant.EPSILON.html) +[std::f32::INFINITY](https://doc.rust-lang.org/std/f32/constant.INFINITY.html) +[std::f32::MANTISSA_DIGITS](https://doc.rust-lang.org/std/f32/constant.MANTISSA_DIGITS.html) +[std::f32::MAX](https://doc.rust-lang.org/std/f32/constant.MAX.html) +[std::f32::MAX_10_EXP](https://doc.rust-lang.org/std/f32/constant.MAX_10_EXP.html) +[std::f32::MAX_EXP](https://doc.rust-lang.org/std/f32/constant.MAX_EXP.html) +[std::f32::MIN](https://doc.rust-lang.org/std/f32/constant.MIN.html) +[std::f32::MIN_10_EXP](https://doc.rust-lang.org/std/f32/constant.MIN_10_EXP.html) +[std::f32::MIN_EXP](https://doc.rust-lang.org/std/f32/constant.MIN_EXP.html) +[std::f32::MIN_POSITIVE](https://doc.rust-lang.org/std/f32/constant.MIN_POSITIVE.html) +[std::f32::NAN](https://doc.rust-lang.org/std/f32/constant.NAN.html) +[std::f32::NEG_INFINITY](https://doc.rust-lang.org/std/f32/constant.NEG_INFINITY.html) +[std::f32::RADIX](https://doc.rust-lang.org/std/f32/constant.RADIX.html) +[std::f32::consts::E](https://doc.rust-lang.org/std/f32/consts/constant.E.html) +[std::f32::consts::FRAC_1_PI](https://doc.rust-lang.org/std/f32/consts/constant.E.html) +[std::f32::consts::FRAC_2_PI](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_2_PI.html) +[std::f32::consts::FRAC_2_SQRT_PI](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_2_SQRT_PI.html) +[std::f32::consts::FRAC_1_SQRT_2](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_1_SQRT_2.html) +[std::f32::consts::FRAC_PI_2](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_2.html) +[std::f32::consts::FRAC_PI_3](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_3.html) +[std::f32::consts::FRAC_PI_4](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_4.html) +[std::f32::consts::FRAC_PI_6](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_6.html) +[std::f32::consts::FRAC_PI_8](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_8.html) +[std::f32::consts::LN_2](https://doc.rust-lang.org/std/f32/consts/constant.LN_2.html) +[std::f32::consts::LN_10](https://doc.rust-lang.org/std/f32/consts/constant.LN_10.html) +[std::f32::consts::LOG2_E](https://doc.rust-lang.org/std/f32/consts/constant.LOG2_E.html) +[std::f32::consts::LOG10_E](https://doc.rust-lang.org/std/f32/consts/constant.LOG10_E.html) +[std::f32::consts::PI](https://doc.rust-lang.org/std/f32/consts/constant.PI.html) +[std::f32::consts::SQRT_2](https://doc.rust-lang.org/std/f32/consts/constant.SQRT_2.html) +[std::f64::DIGITS](https://doc.rust-lang.org/std/f64/constant.DIGITS.html) +[std::f64::EPSILON](https://doc.rust-lang.org/std/f64/constant.EPSILON.html) +[std::f64::INFINITY](https://doc.rust-lang.org/std/f64/constant.INFINITY.html) +[std::f64::MANTISSA_DIGITS](https://doc.rust-lang.org/std/f64/constant.MANTISSA_DIGITS.html) +[std::f64::MAX](https://doc.rust-lang.org/std/f64/constant.MAX.html) +[std::f64::MAX_10_EXP](https://doc.rust-lang.org/std/f64/constant.MAX_10_EXP.html) +[std::f64::MAX_EXP](https://doc.rust-lang.org/std/f64/constant.MAX_EXP.html) +[std::f64::MIN](https://doc.rust-lang.org/std/f64/constant.MIN.html) +[std::f64::MIN_10_EXP](https://doc.rust-lang.org/std/f64/constant.MIN_10_EXP.html) +[std::f64::MIN_EXP](https://doc.rust-lang.org/std/f64/constant.MIN_EXP.html) +[std::f64::MIN_POSITIVE](https://doc.rust-lang.org/std/f64/constant.MIN_POSITIVE.html) +[std::f64::NAN](https://doc.rust-lang.org/std/f64/constant.NAN.html) +[std::f64::NEG_INFINITY](https://doc.rust-lang.org/std/f64/constant.NEG_INFINITY.html) +[std::f64::RADIX](https://doc.rust-lang.org/std/f64/constant.RADIX.html) +[std::f64::consts::E](https://doc.rust-lang.org/std/f64/consts/constant.E.html) +[std::f64::consts::FRAC_1_PI](https://doc.rust-lang.org/std/f64/consts/constant.E.html) +[std::f64::consts::FRAC_2_PI](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_2_PI.html) +[std::f64::consts::FRAC_2_SQRT_PI](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_2_SQRT_PI.html) +[std::f64::consts::FRAC_1_SQRT_2](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_1_SQRT_2.html) +[std::f64::consts::FRAC_PI_2](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_2.html) +[std::f64::consts::FRAC_PI_3](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_3.html) +[std::f64::consts::FRAC_PI_4](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_4.html) +[std::f64::consts::FRAC_PI_6](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_6.html) +[std::f64::consts::FRAC_PI_8](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_8.html) +[std::f64::consts::LN_2](https://doc.rust-lang.org/std/f64/consts/constant.LN_2.html) +[std::f64::consts::LN_10](https://doc.rust-lang.org/std/f64/consts/constant.LN_10.html) +[std::f64::consts::LOG2_E](https://doc.rust-lang.org/std/f64/consts/constant.LOG2_E.html) +[std::f64::consts::LOG10_E](https://doc.rust-lang.org/std/f64/consts/constant.LOG10_E.html) +[std::f64::consts::PI](https://doc.rust-lang.org/std/f64/consts/constant.PI.html) +[std::f64::consts::SQRT_2](https://doc.rust-lang.org/std/f64/consts/constant.SQRT_2.html) +``` + +Replace each item with an associated const value on the appropriate type. Deprecate the fourteen numeric-type modules and remove them from the documentation. + +# Drawbacks +[drawbacks]: #drawbacks + +Deprecation warnings are annoying. + +# Alternatives +[rationale-and-alternatives]: #rationale-and-alternatives + +There is an alternative design where the proposed changes are only made to the integral numeric modules in the standard library, leaving alone `f32` and `f64`. Unlike the integral modules, these modules do not contain both constants and redundant associated items. In addition, these two modules contain submodules named `consts`, which contain constants of a more mathematical bent (the sort of thing other languages might put in a `std::math` module). This RFC argues for giving the float modules the same treatment as the integral modules, both since associated consts are "obviously the right thing" in this case and because we do not consider the mathematical/machine constant distinction to be particularly useful or intuitive. However, making these changes only to the integral types would still achieve most of the goals of this RFC. From 10b930743c4da485ad3316f607684ac9f5892c85 Mon Sep 17 00:00:00 2001 From: bstrie Date: Mon, 13 May 2019 17:44:08 -0400 Subject: [PATCH 02/13] Formatting --- text/0000-associated-constants-on-ints.md | 109 +++++++++++++++++++++- 1 file changed, 107 insertions(+), 2 deletions(-) diff --git a/text/0000-associated-constants-on-ints.md b/text/0000-associated-constants-on-ints.md index 862d3006cf3..1bea438d67f 100644 --- a/text/0000-associated-constants-on-ints.md +++ b/text/0000-associated-constants-on-ints.md @@ -40,116 +40,221 @@ Despite the obvious intent, 1.0 came and went and there were plenty of other thi Deprecate the following items in the standard library: -```rust [i8::min_value](https://doc.rust-lang.org/std/primitive.i8.html#method.min_value) + [i8::max_value](https://doc.rust-lang.org/std/primitive.i8.html#method.max_value) + [std::i8::MIN](https://doc.rust-lang.org/std/i8/constant.MIN.html) + [std::i8::MAX](https://doc.rust-lang.org/std/i8/constant.MIN.html) + [i16::min_value](https://doc.rust-lang.org/std/primitive.i16.html#method.min_value) + [i16::max_value](https://doc.rust-lang.org/std/primitive.i16.html#method.max_value) + [std::i16::MIN](https://doc.rust-lang.org/std/i16/constant.MIN.html) + [std::i16::MAX](https://doc.rust-lang.org/std/i16/constant.MIN.html) + [i32::min_value](https://doc.rust-lang.org/std/primitive.i32.html#method.min_value) + [i32::max_value](https://doc.rust-lang.org/std/primitive.i32.html#method.max_value) + [std::i32::MIN](https://doc.rust-lang.org/std/i32/constant.MIN.html) + [std::i32::MAX](https://doc.rust-lang.org/std/i32/constant.MIN.html) + [i64::min_value](https://doc.rust-lang.org/std/primitive.i64.html#method.min_value) + [i64::max_value](https://doc.rust-lang.org/std/primitive.i64.html#method.max_value) + [std::i64::MIN](https://doc.rust-lang.org/std/i64/constant.MIN.html) + [std::i64::MAX](https://doc.rust-lang.org/std/i64/constant.MIN.html) + [i128::min_value](https://doc.rust-lang.org/std/primitive.i128.html#method.min_value) + [i128::max_value](https://doc.rust-lang.org/std/primitive.i128.html#method.max_value) + [std::i128::MIN](https://doc.rust-lang.org/std/i128/constant.MIN.html) + [std::i128::MAX](https://doc.rust-lang.org/std/i128/constant.MIN.html) + [isize::min_value](https://doc.rust-lang.org/std/primitive.isize.html#method.min_value) + [isize::max_value](https://doc.rust-lang.org/std/primitive.isize.html#method.max_value) + [std::isize::MIN](https://doc.rust-lang.org/std/isize/constant.MIN.html) + [std::isize::MAX](https://doc.rust-lang.org/std/isize/constant.MIN.html) + [u8::min_value](https://doc.rust-lang.org/std/primitive.u8.html#method.min_value) + [u8::max_value](https://doc.rust-lang.org/std/primitive.u8.html#method.max_value) + [std::u8::MIN](https://doc.rust-lang.org/std/u8/constant.MIN.html) + [std::u8::MAX](https://doc.rust-lang.org/std/u8/constant.MIN.html) + [u16::min_value](https://doc.rust-lang.org/std/primitive.u16.html#method.min_value) + [u16::max_value](https://doc.rust-lang.org/std/primitive.u16.html#method.max_value) + [std::u16::MIN](https://doc.rust-lang.org/std/u16/constant.MIN.html) + [std::u16::MAX](https://doc.rust-lang.org/std/u16/constant.MIN.html) + [u32::min_value](https://doc.rust-lang.org/std/primitive.u32.html#method.min_value) + [u32::max_value](https://doc.rust-lang.org/std/primitive.u32.html#method.max_value) + [std::u32::MIN](https://doc.rust-lang.org/std/u32/constant.MIN.html) + [std::u32::MAX](https://doc.rust-lang.org/std/u32/constant.MIN.html) + [u64::min_value](https://doc.rust-lang.org/std/primitive.u64.html#method.min_value) + [u64::max_value](https://doc.rust-lang.org/std/primitive.u64.html#method.max_value) + [std::u64::MIN](https://doc.rust-lang.org/std/u64/constant.MIN.html) + [std::u64::MAX](https://doc.rust-lang.org/std/u64/constant.MIN.html) + [u128::min_value](https://doc.rust-lang.org/std/primitive.u128.html#method.min_value) + [u128::max_value](https://doc.rust-lang.org/std/primitive.u128.html#method.max_value) + [std::u128::MIN](https://doc.rust-lang.org/std/u128/constant.MIN.html) + [std::u128::MAX](https://doc.rust-lang.org/std/u128/constant.MIN.html) + [usize::min_value](https://doc.rust-lang.org/std/primitive.usize.html#method.min_value) + [usize::max_value](https://doc.rust-lang.org/std/primitive.usize.html#method.max_value) + [std::usize::MIN](https://doc.rust-lang.org/std/usize/constant.MIN.html) + [std::usize::MAX](https://doc.rust-lang.org/std/usize/constant.MIN.html) + [std::f32::DIGITS](https://doc.rust-lang.org/std/f32/constant.DIGITS.html) + [std::f32::EPSILON](https://doc.rust-lang.org/std/f32/constant.EPSILON.html) + [std::f32::INFINITY](https://doc.rust-lang.org/std/f32/constant.INFINITY.html) + [std::f32::MANTISSA_DIGITS](https://doc.rust-lang.org/std/f32/constant.MANTISSA_DIGITS.html) + [std::f32::MAX](https://doc.rust-lang.org/std/f32/constant.MAX.html) + [std::f32::MAX_10_EXP](https://doc.rust-lang.org/std/f32/constant.MAX_10_EXP.html) + [std::f32::MAX_EXP](https://doc.rust-lang.org/std/f32/constant.MAX_EXP.html) + [std::f32::MIN](https://doc.rust-lang.org/std/f32/constant.MIN.html) + [std::f32::MIN_10_EXP](https://doc.rust-lang.org/std/f32/constant.MIN_10_EXP.html) + [std::f32::MIN_EXP](https://doc.rust-lang.org/std/f32/constant.MIN_EXP.html) + [std::f32::MIN_POSITIVE](https://doc.rust-lang.org/std/f32/constant.MIN_POSITIVE.html) + [std::f32::NAN](https://doc.rust-lang.org/std/f32/constant.NAN.html) + [std::f32::NEG_INFINITY](https://doc.rust-lang.org/std/f32/constant.NEG_INFINITY.html) + [std::f32::RADIX](https://doc.rust-lang.org/std/f32/constant.RADIX.html) + [std::f32::consts::E](https://doc.rust-lang.org/std/f32/consts/constant.E.html) + [std::f32::consts::FRAC_1_PI](https://doc.rust-lang.org/std/f32/consts/constant.E.html) + [std::f32::consts::FRAC_2_PI](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_2_PI.html) + [std::f32::consts::FRAC_2_SQRT_PI](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_2_SQRT_PI.html) + [std::f32::consts::FRAC_1_SQRT_2](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_1_SQRT_2.html) + [std::f32::consts::FRAC_PI_2](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_2.html) + [std::f32::consts::FRAC_PI_3](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_3.html) + [std::f32::consts::FRAC_PI_4](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_4.html) + [std::f32::consts::FRAC_PI_6](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_6.html) + [std::f32::consts::FRAC_PI_8](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_8.html) + [std::f32::consts::LN_2](https://doc.rust-lang.org/std/f32/consts/constant.LN_2.html) + [std::f32::consts::LN_10](https://doc.rust-lang.org/std/f32/consts/constant.LN_10.html) + [std::f32::consts::LOG2_E](https://doc.rust-lang.org/std/f32/consts/constant.LOG2_E.html) + [std::f32::consts::LOG10_E](https://doc.rust-lang.org/std/f32/consts/constant.LOG10_E.html) + [std::f32::consts::PI](https://doc.rust-lang.org/std/f32/consts/constant.PI.html) + [std::f32::consts::SQRT_2](https://doc.rust-lang.org/std/f32/consts/constant.SQRT_2.html) + [std::f64::DIGITS](https://doc.rust-lang.org/std/f64/constant.DIGITS.html) + [std::f64::EPSILON](https://doc.rust-lang.org/std/f64/constant.EPSILON.html) + [std::f64::INFINITY](https://doc.rust-lang.org/std/f64/constant.INFINITY.html) + [std::f64::MANTISSA_DIGITS](https://doc.rust-lang.org/std/f64/constant.MANTISSA_DIGITS.html) + [std::f64::MAX](https://doc.rust-lang.org/std/f64/constant.MAX.html) + [std::f64::MAX_10_EXP](https://doc.rust-lang.org/std/f64/constant.MAX_10_EXP.html) + [std::f64::MAX_EXP](https://doc.rust-lang.org/std/f64/constant.MAX_EXP.html) + [std::f64::MIN](https://doc.rust-lang.org/std/f64/constant.MIN.html) + [std::f64::MIN_10_EXP](https://doc.rust-lang.org/std/f64/constant.MIN_10_EXP.html) + [std::f64::MIN_EXP](https://doc.rust-lang.org/std/f64/constant.MIN_EXP.html) + [std::f64::MIN_POSITIVE](https://doc.rust-lang.org/std/f64/constant.MIN_POSITIVE.html) + [std::f64::NAN](https://doc.rust-lang.org/std/f64/constant.NAN.html) + [std::f64::NEG_INFINITY](https://doc.rust-lang.org/std/f64/constant.NEG_INFINITY.html) + [std::f64::RADIX](https://doc.rust-lang.org/std/f64/constant.RADIX.html) + [std::f64::consts::E](https://doc.rust-lang.org/std/f64/consts/constant.E.html) + [std::f64::consts::FRAC_1_PI](https://doc.rust-lang.org/std/f64/consts/constant.E.html) + [std::f64::consts::FRAC_2_PI](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_2_PI.html) + [std::f64::consts::FRAC_2_SQRT_PI](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_2_SQRT_PI.html) + [std::f64::consts::FRAC_1_SQRT_2](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_1_SQRT_2.html) + [std::f64::consts::FRAC_PI_2](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_2.html) + [std::f64::consts::FRAC_PI_3](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_3.html) + [std::f64::consts::FRAC_PI_4](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_4.html) + [std::f64::consts::FRAC_PI_6](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_6.html) + [std::f64::consts::FRAC_PI_8](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_8.html) + [std::f64::consts::LN_2](https://doc.rust-lang.org/std/f64/consts/constant.LN_2.html) + [std::f64::consts::LN_10](https://doc.rust-lang.org/std/f64/consts/constant.LN_10.html) + [std::f64::consts::LOG2_E](https://doc.rust-lang.org/std/f64/consts/constant.LOG2_E.html) + [std::f64::consts::LOG10_E](https://doc.rust-lang.org/std/f64/consts/constant.LOG10_E.html) + [std::f64::consts::PI](https://doc.rust-lang.org/std/f64/consts/constant.PI.html) + [std::f64::consts::SQRT_2](https://doc.rust-lang.org/std/f64/consts/constant.SQRT_2.html) -``` Replace each item with an associated const value on the appropriate type. Deprecate the fourteen numeric-type modules and remove them from the documentation. From e3de748ae48650d7b33325b8917e929a8e08e1b9 Mon Sep 17 00:00:00 2001 From: bstrie Date: Tue, 14 May 2019 18:17:59 -0400 Subject: [PATCH 03/13] Expand on alternatives and rationale WRT floats --- text/0000-associated-constants-on-ints.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-associated-constants-on-ints.md b/text/0000-associated-constants-on-ints.md index 1bea438d67f..5a157b0a830 100644 --- a/text/0000-associated-constants-on-ints.md +++ b/text/0000-associated-constants-on-ints.md @@ -263,7 +263,7 @@ Replace each item with an associated const value on the appropriate type. Deprec Deprecation warnings are annoying. -# Alternatives +# Rationale and alternatives [rationale-and-alternatives]: #rationale-and-alternatives -There is an alternative design where the proposed changes are only made to the integral numeric modules in the standard library, leaving alone `f32` and `f64`. Unlike the integral modules, these modules do not contain both constants and redundant associated items. In addition, these two modules contain submodules named `consts`, which contain constants of a more mathematical bent (the sort of thing other languages might put in a `std::math` module). This RFC argues for giving the float modules the same treatment as the integral modules, both since associated consts are "obviously the right thing" in this case and because we do not consider the mathematical/machine constant distinction to be particularly useful or intuitive. However, making these changes only to the integral types would still achieve most of the goals of this RFC. +There is an alternative design where the proposed changes are only made to the integral numeric modules in the standard library, leaving alone `f32` and `f64`. Unlike the integral modules, these modules do not contain both constants and redundant associated items. In addition, these two modules contain submodules named `consts`, which contain constants of a more mathematical bent (the sort of thing other languages might put in a `std::math` module). This RFC argues for giving the float modules the same treatment as the integral modules, both since associated consts are "obviously the right thing" in this case and because we do not consider the mathematical/machine constant distinction to be particularly useful or intuitive. In particular, this distinction is not consistent with the existing set of associated functions implemented on `f32` and `f64`, which consist of a mix of both functions concerned with mathematical operations (e.g. `f32::atanh`) and functions concerned with machine representation (e.g. `f32::is_sign_negative`). As noted, if a `math` module existed in Rust's stdlib this would be the natural place to put them, however, such a module does not exist; further, any consideration of this hyptothetical module would, for the sake of consistency, want to also adopt not only the aforementioned mathematical associated functions that currently exist on `f32` and `f64`, but would also want to adopt the integral mathematical functions such as `i32::pow`--all while in some way recreating the module-level distinction between the operations as they exist on the various different numeric types. This is all to say that such a `std::math` module is out of scope for this proposal, in addition to lacking the technical motivation of this proposal. Ultimately, however, leaving `f32` and `f64` along and making the proposed changes only to the integral types would still be considered a success by this RFC. From 972d24a9cb7cad32e13c11d8ed35afecc759b06a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Linus=20F=C3=A4rnstrand?= Date: Wed, 20 Nov 2019 07:14:04 +0100 Subject: [PATCH 04/13] Exclude fXX::consts from this RFC --- text/0000-associated-constants-on-ints.md | 69 +---------------------- 1 file changed, 3 insertions(+), 66 deletions(-) diff --git a/text/0000-associated-constants-on-ints.md b/text/0000-associated-constants-on-ints.md index 5a157b0a830..eee05116f8f 100644 --- a/text/0000-associated-constants-on-ints.md +++ b/text/0000-associated-constants-on-ints.md @@ -27,7 +27,7 @@ Finally, so obvious was this solution that [the original RFC for associated item > For example, today's Rust includes a variety of numeric traits, including Float, which must currently expose constants as static functions [...] Associated constants would allow the consts to live directly on the traits -Despite the obvious intent, 1.0 came and went and there were plenty of other things to occupy everyone's attention. Now, two days shy of Rust's fourth anniversary, let's re-examine the situation. We propose to deprecate all of the aforementioned functions and constants in favor of associated constants defined on the appropriate types, and to additionally deprecate the `i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `u8`, `u16`, `u32`, `u64`, `u128`, `usize`, `f32`, and `f64` modules in `std`. Advantages of this: +Despite the obvious intent, 1.0 came and went and there were plenty of other things to occupy everyone's attention. Now, two days shy of Rust's fourth anniversary, let's re-examine the situation. We propose to deprecate all of the aforementioned functions and constants in favor of associated constants defined on the appropriate types, and to additionally deprecate all constants living directly in the `i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `u8`, `u16`, `u32`, `u64`, `u128`, `usize`, `f32` and `f64` modules in `std`. But leaving `std::f64::consts` and `std::f32::consts` as they are. Advantages of this: 1. Consistency with the rest of the language. As demonstrated by the above quotes, associated consts have been the natural way to express these concepts in Rust since before associated consts were even implemented; this approach satisfies the principle of least surprise. @@ -164,38 +164,6 @@ Deprecate the following items in the standard library: [std::f32::RADIX](https://doc.rust-lang.org/std/f32/constant.RADIX.html) -[std::f32::consts::E](https://doc.rust-lang.org/std/f32/consts/constant.E.html) - -[std::f32::consts::FRAC_1_PI](https://doc.rust-lang.org/std/f32/consts/constant.E.html) - -[std::f32::consts::FRAC_2_PI](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_2_PI.html) - -[std::f32::consts::FRAC_2_SQRT_PI](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_2_SQRT_PI.html) - -[std::f32::consts::FRAC_1_SQRT_2](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_1_SQRT_2.html) - -[std::f32::consts::FRAC_PI_2](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_2.html) - -[std::f32::consts::FRAC_PI_3](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_3.html) - -[std::f32::consts::FRAC_PI_4](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_4.html) - -[std::f32::consts::FRAC_PI_6](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_6.html) - -[std::f32::consts::FRAC_PI_8](https://doc.rust-lang.org/std/f32/consts/constant.FRAC_PI_8.html) - -[std::f32::consts::LN_2](https://doc.rust-lang.org/std/f32/consts/constant.LN_2.html) - -[std::f32::consts::LN_10](https://doc.rust-lang.org/std/f32/consts/constant.LN_10.html) - -[std::f32::consts::LOG2_E](https://doc.rust-lang.org/std/f32/consts/constant.LOG2_E.html) - -[std::f32::consts::LOG10_E](https://doc.rust-lang.org/std/f32/consts/constant.LOG10_E.html) - -[std::f32::consts::PI](https://doc.rust-lang.org/std/f32/consts/constant.PI.html) - -[std::f32::consts::SQRT_2](https://doc.rust-lang.org/std/f32/consts/constant.SQRT_2.html) - [std::f64::DIGITS](https://doc.rust-lang.org/std/f64/constant.DIGITS.html) [std::f64::EPSILON](https://doc.rust-lang.org/std/f64/constant.EPSILON.html) @@ -224,39 +192,8 @@ Deprecate the following items in the standard library: [std::f64::RADIX](https://doc.rust-lang.org/std/f64/constant.RADIX.html) -[std::f64::consts::E](https://doc.rust-lang.org/std/f64/consts/constant.E.html) - -[std::f64::consts::FRAC_1_PI](https://doc.rust-lang.org/std/f64/consts/constant.E.html) - -[std::f64::consts::FRAC_2_PI](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_2_PI.html) - -[std::f64::consts::FRAC_2_SQRT_PI](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_2_SQRT_PI.html) - -[std::f64::consts::FRAC_1_SQRT_2](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_1_SQRT_2.html) - -[std::f64::consts::FRAC_PI_2](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_2.html) - -[std::f64::consts::FRAC_PI_3](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_3.html) - -[std::f64::consts::FRAC_PI_4](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_4.html) - -[std::f64::consts::FRAC_PI_6](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_6.html) - -[std::f64::consts::FRAC_PI_8](https://doc.rust-lang.org/std/f64/consts/constant.FRAC_PI_8.html) - -[std::f64::consts::LN_2](https://doc.rust-lang.org/std/f64/consts/constant.LN_2.html) - -[std::f64::consts::LN_10](https://doc.rust-lang.org/std/f64/consts/constant.LN_10.html) - -[std::f64::consts::LOG2_E](https://doc.rust-lang.org/std/f64/consts/constant.LOG2_E.html) - -[std::f64::consts::LOG10_E](https://doc.rust-lang.org/std/f64/consts/constant.LOG10_E.html) - -[std::f64::consts::PI](https://doc.rust-lang.org/std/f64/consts/constant.PI.html) - -[std::f64::consts::SQRT_2](https://doc.rust-lang.org/std/f64/consts/constant.SQRT_2.html) - -Replace each item with an associated const value on the appropriate type. Deprecate the fourteen numeric-type modules and remove them from the documentation. +Replace each item with an associated const value on the appropriate type. Deprecate the twelve +integer type modules and remove them from the documentation. # Drawbacks [drawbacks]: #drawbacks From a3fa24c12ab44197fee3f6a6e92656c35fda9ac0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Linus=20F=C3=A4rnstrand?= Date: Wed, 20 Nov 2019 07:14:31 +0100 Subject: [PATCH 05/13] Add one benefit of doing this --- text/0000-associated-constants-on-ints.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/text/0000-associated-constants-on-ints.md b/text/0000-associated-constants-on-ints.md index eee05116f8f..af1c9f18beb 100644 --- a/text/0000-associated-constants-on-ints.md +++ b/text/0000-associated-constants-on-ints.md @@ -35,6 +35,14 @@ Despite the obvious intent, 1.0 came and went and there were plenty of other thi 3. Beginner ease. For a beginner, finding two identical ways to achieve something immediately raises the question of "why", to which the answer here is ultimately uninteresting (and even then, the question of "which one to use" remains unanswered; neither current approach is idiomatic). As noted, deprecated items can be removed from the documentation, thereby decreasing the likelihood of head-scratching and incredulous sidelong glances from people new to Rust. +4. Remove ambiguity between primitive type and module with same name. Currently if you import an +integer module and access constants in the module and methods on the type, it's very unclear what +comes from where: + ```rust + use std::u32; + assert_eq!(u32::MAX, u32::max_value()); + ``` + # Guide-level explanation [guide-level-explanation]: #guide-level-explanation From b9a14394397e0c6d080ba6d7354216ea74d28fa2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Linus=20F=C3=A4rnstrand?= Date: Wed, 20 Nov 2019 07:40:58 +0100 Subject: [PATCH 06/13] Break lines on 100 chars and update rationale/alternatives --- text/0000-associated-constants-on-ints.md | 121 +++++++++++++++++----- 1 file changed, 96 insertions(+), 25 deletions(-) diff --git a/text/0000-associated-constants-on-ints.md b/text/0000-associated-constants-on-ints.md index af1c9f18beb..d85eb0ff7a9 100644 --- a/text/0000-associated-constants-on-ints.md +++ b/text/0000-associated-constants-on-ints.md @@ -6,34 +6,82 @@ # Summary [summary]: #summary -Add the relevant associated constants to the numeric types in the standard library, and consider a timeline for the deprecation of the corresponding (and originally intended to be temporary) primitive numeric modules and associated functions. +Add the relevant associated constants to the numeric types in the standard library, and consider a +timeline for the deprecation of the corresponding (and originally intended to be temporary) +primitive numeric modules and associated functions. # Motivation [motivation]: #motivation -All programming languages with bounded integers provide numeric constants for their maximum and minimum extents. In Rust, [these constants were stabilized](https://github.com/rust-lang/rust/pull/23549) in the eleventh hour before Rust 1.0 (literally the day before the branching of 1.0-beta on April 1, 2015), with some known-to-be-undesirable properties. In particular, associated consts were yet to be implemented (these landed, amusingly, one month after 1.0-beta and two weeks before 1.0-stable), and so each of the twelve numeric types were given their own top-level modules in the standard library, whose contents are exclusively these constants (all related non-constants being defined in inherent impls directly on each type). However, in the even-eleventh-er hour before 1.0-beta, it was realized that this solution did not work for anyone seeking to reference these constants when working with types such as `c_int`, which are defined as type aliases and can thus access inherent impls but not modules that merely happen to be named the same as the original type; as a result, [an emergency PR](https://github.com/rust-lang/rust/pull/23947) also added redundant `max_value` and `min_value` inherent functions as a last-second workaround. The PR itself notes how distasteful this remedy is: - -> It's unfortunate to freeze these as methods, but when we can provide inherent associated constants these methods can be deprecated. [aturon, Apr 1, 2015] - -Meanwhile, the author of the associated consts patch [despairs](https://github.com/rust-lang/rust/pull/23606#issuecomment-88541583) of just barely missing the deadline: - -> @nikomatsakis The original motivation for trying to get this in before the beta was to get rid of all the functions that deal with constants in Int/Float, and then to get rid of all the modules like std::i64 that just hold constants as well. We could have dodged most of the issues (ICEs and generic code design) by using inherent impls instead of associating the constants with traits. But since [#23549](https://github.com/rust-lang/rust/pull/23549) came in a bit earlier and stabilized a bunch more of those constants before the beta, whereas this hasn't landed yet, blegh. [quantheory, Apr 1, 2015] - -Anticipating the situation, an [issue](https://github.com/rust-lang/rfcs/issues/1099) was filed in the RFCs repo regarding moving the contents of these modules into associated consts: - -> I think it's a minor enough breaking change to move the constants and deprecate the modules u8, u16, etc. Not so sure about removing these modules entirely, I'd appreciate that, but it'll break all the code use-ing them. [petrochenkov, Apr 29, 2015] - -Finally, so obvious was this solution that [the original RFC for associated items](https://github.com/nox/rust-rfcs/blob/master/text/0195-associated-items.md#expressiveness) used the numeric constants as the only motivating example for the feature of associated consts: - -> For example, today's Rust includes a variety of numeric traits, including Float, which must currently expose constants as static functions [...] Associated constants would allow the consts to live directly on the traits - -Despite the obvious intent, 1.0 came and went and there were plenty of other things to occupy everyone's attention. Now, two days shy of Rust's fourth anniversary, let's re-examine the situation. We propose to deprecate all of the aforementioned functions and constants in favor of associated constants defined on the appropriate types, and to additionally deprecate all constants living directly in the `i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `u8`, `u16`, `u32`, `u64`, `u128`, `usize`, `f32` and `f64` modules in `std`. But leaving `std::f64::consts` and `std::f32::consts` as they are. Advantages of this: - -1. Consistency with the rest of the language. As demonstrated by the above quotes, associated consts have been the natural way to express these concepts in Rust since before associated consts were even implemented; this approach satisfies the principle of least surprise. - -2. Documentation. On the front page of the [standard library API docs](https://doc.rust-lang.org/std/index.html), 14 of the 56 modules in the standard library (25%) are the aforementioned numeric modules whose only purpose is to namespace these constants. This number will continue to rise as new numeric primitives are added to Rust, as already seen with `i128` and `u128`. Although deprecated modules cannot be easily removed from std, they can be removed from the documentation, making the stdlib API docs less cluttered and easier to navigate. - -3. Beginner ease. For a beginner, finding two identical ways to achieve something immediately raises the question of "why", to which the answer here is ultimately uninteresting (and even then, the question of "which one to use" remains unanswered; neither current approach is idiomatic). As noted, deprecated items can be removed from the documentation, thereby decreasing the likelihood of head-scratching and incredulous sidelong glances from people new to Rust. +All programming languages with bounded integers provide numeric constants for their maximum and +minimum extents. In Rust, [these constants were +stabilized](https://github.com/rust-lang/rust/pull/23549) in the eleventh hour before Rust 1.0 +(literally the day before the branching of 1.0-beta on April 1, 2015), with some +known-to-be-undesirable properties. In particular, associated consts were yet to be implemented +(these landed, amusingly, one month after 1.0-beta and two weeks before 1.0-stable), and so each of +the twelve numeric types were given their own top-level modules in the standard library, whose +contents are exclusively these constants (all related non-constants being defined in inherent impls +directly on each type). However, in the even-eleventh-er hour before 1.0-beta, it was realized that +this solution did not work for anyone seeking to reference these constants when working with types +such as `c_int`, which are defined as type aliases and can thus access inherent impls but not +modules that merely happen to be named the same as the original type; as a result, [an emergency +PR](https://github.com/rust-lang/rust/pull/23947) also added redundant `max_value` and `min_value` +inherent functions as a last-second workaround. The PR itself notes how distasteful this remedy is: + +> It's unfortunate to freeze these as methods, but when we can provide inherent associated constants +> these methods can be deprecated. [aturon, Apr 1, 2015] + +Meanwhile, the author of the associated consts patch +[despairs](https://github.com/rust-lang/rust/pull/23606#issuecomment-88541583) of just barely +missing the deadline: + +> @nikomatsakis The original motivation for trying to get this in before the beta was to get rid of +> all the functions that deal with constants in Int/Float, and then to get rid of all the modules +> like std::i64 that just hold constants as well. We could have dodged most of the issues (ICEs and +> generic code design) by using inherent impls instead of associating the constants with traits. But +> since [#23549](https://github.com/rust-lang/rust/pull/23549) came in a bit earlier and stabilized +> a bunch more of those constants before the beta, whereas this hasn't landed yet, blegh. +> [quantheory, Apr 1, 2015] + +Anticipating the situation, an [issue](https://github.com/rust-lang/rfcs/issues/1099) was filed in +the RFCs repo regarding moving the contents of these modules into associated consts: + +> I think it's a minor enough breaking change to move the constants and deprecate the modules u8, +> u16, etc. Not so sure about removing these modules entirely, I'd appreciate that, but it'll break +> all the code use-ing them. [petrochenkov, Apr 29, 2015] + +Finally, so obvious was this solution that [the original RFC for associated +items](https://github.com/nox/rust-rfcs/blob/master/text/0195-associated-items.md#expressiveness) +used the numeric constants as the only motivating example for the feature of associated consts: + +> For example, today's Rust includes a variety of numeric traits, including Float, which must +> currently expose constants as static functions [...] Associated constants would allow the consts +> to live directly on the traits + +Despite the obvious intent, 1.0 came and went and there were plenty of other things to occupy +everyone's attention. Now, two days shy of Rust's fourth anniversary, let's re-examine the +situation. We propose to deprecate all of the aforementioned functions and constants in favor of +associated constants defined on the appropriate types, and to additionally deprecate all constants +living directly in the `i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `u8`, `u16`, `u32`, `u64`, +`u128`, `usize`, `f32` and `f64` modules in `std`. But leaving `std::f64::consts` and +`std::f32::consts` as they are. Advantages of this: + +1. Consistency with the rest of the language. As demonstrated by the above quotes, associated consts +have been the natural way to express these concepts in Rust since before associated consts were even +implemented; this approach satisfies the principle of least surprise. + +2. Documentation. On the front page of the [standard library API +docs](https://doc.rust-lang.org/std/index.html), 14 of the 56 modules in the standard library (25%) +are the aforementioned numeric modules whose only purpose is to namespace these constants. This +number will continue to rise as new numeric primitives are added to Rust, as already seen with +`i128` and `u128`. Although deprecated modules cannot be easily removed from std, they can be +removed from the documentation, making the stdlib API docs less cluttered and easier to navigate. + +3. Beginner ease. For a beginner, finding two identical ways to achieve something immediately raises +the question of "why", to which the answer here is ultimately uninteresting (and even then, the +question of "which one to use" remains unanswered; neither current approach is idiomatic). As noted, +deprecated items can be removed from the documentation, thereby decreasing the likelihood of +head-scratching and incredulous sidelong glances from people new to Rust. 4. Remove ambiguity between primitive type and module with same name. Currently if you import an integer module and access constants in the module and methods on the type, it's very unclear what @@ -211,4 +259,27 @@ Deprecation warnings are annoying. # Rationale and alternatives [rationale-and-alternatives]: #rationale-and-alternatives -There is an alternative design where the proposed changes are only made to the integral numeric modules in the standard library, leaving alone `f32` and `f64`. Unlike the integral modules, these modules do not contain both constants and redundant associated items. In addition, these two modules contain submodules named `consts`, which contain constants of a more mathematical bent (the sort of thing other languages might put in a `std::math` module). This RFC argues for giving the float modules the same treatment as the integral modules, both since associated consts are "obviously the right thing" in this case and because we do not consider the mathematical/machine constant distinction to be particularly useful or intuitive. In particular, this distinction is not consistent with the existing set of associated functions implemented on `f32` and `f64`, which consist of a mix of both functions concerned with mathematical operations (e.g. `f32::atanh`) and functions concerned with machine representation (e.g. `f32::is_sign_negative`). As noted, if a `math` module existed in Rust's stdlib this would be the natural place to put them, however, such a module does not exist; further, any consideration of this hyptothetical module would, for the sake of consistency, want to also adopt not only the aforementioned mathematical associated functions that currently exist on `f32` and `f64`, but would also want to adopt the integral mathematical functions such as `i32::pow`--all while in some way recreating the module-level distinction between the operations as they exist on the various different numeric types. This is all to say that such a `std::math` module is out of scope for this proposal, in addition to lacking the technical motivation of this proposal. Ultimately, however, leaving `f32` and `f64` along and making the proposed changes only to the integral types would still be considered a success by this RFC. +There is an alternative design where the proposed changes are also done to the `consts` submodules +in `std::f32` and `std::f64`, which contain constants of a more mathematical bent (the sort of +thing other languages might put in a `std::math` module). Doing so would be more consistent. Given +that we do not consider the mathematical/machine constant distinction to be particularly useful or +intuitive. In particular, this distinction is not consistent with the existing set of associated +functions implemented on `f32` and `f64`, which consist of a mix of both functions concerned with +mathematical operations (e.g. `f32::atanh`) and functions concerned with machine representation +(e.g. `f32::is_sign_negative`). The reason this RFC leaves the `consts` module as is, is because +the language currently does not allow imports of type-relative names, and likely never will. This +means every associated constant must be accessed by prefixing it with the type, `f32::PI` instead +of just `PI`. Having to do so met some resistance. So the scope of the RFC was changed to leave +the mathematical constants, where the exact float type might not be as important, compared to +constants tightly coupled with its type, such as for `MIN`. + +As noted, if a `math` module existed in Rust's stdlib this would be the natural place to put +aforementioned constants from `consts`, however, such a module does not exist; further, any +consideration of this hyptothetical module would, for the sake of consistency, want to also adopt +not only the aforementioned mathematical associated functions that currently exist on `f32` and +`f64`, but would also want to adopt the integral mathematical functions such as `i32::pow`--all +while in some way recreating the module-level distinction between the operations as they exist on +the various different numeric types. This is all to say that such a `std::math` module is out of +scope for this proposal, in addition to lacking the technical motivation of this proposal. +Ultimately, however, leaving `f32` and `f64` along and making the proposed changes only to the +integral types would still be considered a success by this RFC. From 2f3e4c9bd1d0cdd6c1865d1eb26b06ae9401d51d Mon Sep 17 00:00:00 2001 From: Ben Striegel Date: Wed, 4 Dec 2019 16:48:50 -0500 Subject: [PATCH 07/13] Update and polish --- text/0000-associated-constants-on-ints.md | 288 +++++++--------------- 1 file changed, 87 insertions(+), 201 deletions(-) diff --git a/text/0000-associated-constants-on-ints.md b/text/0000-associated-constants-on-ints.md index d85eb0ff7a9..07ea50514df 100644 --- a/text/0000-associated-constants-on-ints.md +++ b/text/0000-associated-constants-on-ints.md @@ -63,223 +63,109 @@ everyone's attention. Now, two days shy of Rust's fourth anniversary, let's re-e situation. We propose to deprecate all of the aforementioned functions and constants in favor of associated constants defined on the appropriate types, and to additionally deprecate all constants living directly in the `i8`, `i16`, `i32`, `i64`, `i128`, `isize`, `u8`, `u16`, `u32`, `u64`, -`u128`, `usize`, `f32` and `f64` modules in `std`. But leaving `std::f64::consts` and -`std::f32::consts` as they are. Advantages of this: +`u128`, `usize`, `f32` and `f64` modules in `std`. Advantages of this: 1. Consistency with the rest of the language. As demonstrated by the above quotes, associated consts have been the natural way to express these concepts in Rust since before associated consts were even implemented; this approach satisfies the principle of least surprise. 2. Documentation. On the front page of the [standard library API -docs](https://doc.rust-lang.org/std/index.html), 14 of the 56 modules in the standard library (25%) -are the aforementioned numeric modules whose only purpose is to namespace these constants. This -number will continue to rise as new numeric primitives are added to Rust, as already seen with +docs](https://doc.rust-lang.org/std/index.html), 12 of the 60 modules in the standard library (20%) +are the aforementioned numeric modules which exist only to namespace two constants each. This +number will increase as new numeric primitives are added to Rust, as already seen with `i128` and `u128`. Although deprecated modules cannot be easily removed from std, they can be removed from the documentation, making the stdlib API docs less cluttered and easier to navigate. 3. Beginner ease. For a beginner, finding two identical ways to achieve something immediately raises -the question of "why", to which the answer here is ultimately uninteresting (and even then, the -question of "which one to use" remains unanswered; neither current approach is idiomatic). As noted, -deprecated items can be removed from the documentation, thereby decreasing the likelihood of -head-scratching and incredulous sidelong glances from people new to Rust. +the question of "why", to which the answer here is ultimately uninteresting (and mildly +embarrassing). Even then the question of "which one to use" remains unanswered; neither current +approach is more idiomatic than the other. As noted, deprecated items can be removed from the +documentation, thereby decreasing the likelihood of head-scratching and incredulous sidelong +glances from people new to Rust. -4. Remove ambiguity between primitive type and module with same name. Currently if you import an -integer module and access constants in the module and methods on the type, it's very unclear what -comes from where: - ```rust - use std::u32; - assert_eq!(u32::MAX, u32::max_value()); - ``` +4. Removal of ambiguity between primitive types and their identically-named modules. Currently +if you import an integer module and access constants in the module and methods on the type, +one has no apparent indication as to what comes from where: + +```rust +use std::u32; +assert_eq!(u32::MAX, u32::max_value()); +``` # Guide-level explanation [guide-level-explanation]: #guide-level-explanation -Deprecate the following items in the standard library: - -[i8::min_value](https://doc.rust-lang.org/std/primitive.i8.html#method.min_value) - -[i8::max_value](https://doc.rust-lang.org/std/primitive.i8.html#method.max_value) - -[std::i8::MIN](https://doc.rust-lang.org/std/i8/constant.MIN.html) - -[std::i8::MAX](https://doc.rust-lang.org/std/i8/constant.MIN.html) - -[i16::min_value](https://doc.rust-lang.org/std/primitive.i16.html#method.min_value) - -[i16::max_value](https://doc.rust-lang.org/std/primitive.i16.html#method.max_value) - -[std::i16::MIN](https://doc.rust-lang.org/std/i16/constant.MIN.html) - -[std::i16::MAX](https://doc.rust-lang.org/std/i16/constant.MIN.html) - -[i32::min_value](https://doc.rust-lang.org/std/primitive.i32.html#method.min_value) - -[i32::max_value](https://doc.rust-lang.org/std/primitive.i32.html#method.max_value) - -[std::i32::MIN](https://doc.rust-lang.org/std/i32/constant.MIN.html) - -[std::i32::MAX](https://doc.rust-lang.org/std/i32/constant.MIN.html) - -[i64::min_value](https://doc.rust-lang.org/std/primitive.i64.html#method.min_value) - -[i64::max_value](https://doc.rust-lang.org/std/primitive.i64.html#method.max_value) - -[std::i64::MIN](https://doc.rust-lang.org/std/i64/constant.MIN.html) - -[std::i64::MAX](https://doc.rust-lang.org/std/i64/constant.MIN.html) - -[i128::min_value](https://doc.rust-lang.org/std/primitive.i128.html#method.min_value) - -[i128::max_value](https://doc.rust-lang.org/std/primitive.i128.html#method.max_value) - -[std::i128::MIN](https://doc.rust-lang.org/std/i128/constant.MIN.html) - -[std::i128::MAX](https://doc.rust-lang.org/std/i128/constant.MIN.html) - -[isize::min_value](https://doc.rust-lang.org/std/primitive.isize.html#method.min_value) - -[isize::max_value](https://doc.rust-lang.org/std/primitive.isize.html#method.max_value) - -[std::isize::MIN](https://doc.rust-lang.org/std/isize/constant.MIN.html) - -[std::isize::MAX](https://doc.rust-lang.org/std/isize/constant.MIN.html) - -[u8::min_value](https://doc.rust-lang.org/std/primitive.u8.html#method.min_value) - -[u8::max_value](https://doc.rust-lang.org/std/primitive.u8.html#method.max_value) - -[std::u8::MIN](https://doc.rust-lang.org/std/u8/constant.MIN.html) - -[std::u8::MAX](https://doc.rust-lang.org/std/u8/constant.MIN.html) - -[u16::min_value](https://doc.rust-lang.org/std/primitive.u16.html#method.min_value) - -[u16::max_value](https://doc.rust-lang.org/std/primitive.u16.html#method.max_value) - -[std::u16::MIN](https://doc.rust-lang.org/std/u16/constant.MIN.html) - -[std::u16::MAX](https://doc.rust-lang.org/std/u16/constant.MIN.html) - -[u32::min_value](https://doc.rust-lang.org/std/primitive.u32.html#method.min_value) - -[u32::max_value](https://doc.rust-lang.org/std/primitive.u32.html#method.max_value) - -[std::u32::MIN](https://doc.rust-lang.org/std/u32/constant.MIN.html) - -[std::u32::MAX](https://doc.rust-lang.org/std/u32/constant.MIN.html) - -[u64::min_value](https://doc.rust-lang.org/std/primitive.u64.html#method.min_value) - -[u64::max_value](https://doc.rust-lang.org/std/primitive.u64.html#method.max_value) - -[std::u64::MIN](https://doc.rust-lang.org/std/u64/constant.MIN.html) - -[std::u64::MAX](https://doc.rust-lang.org/std/u64/constant.MIN.html) - -[u128::min_value](https://doc.rust-lang.org/std/primitive.u128.html#method.min_value) - -[u128::max_value](https://doc.rust-lang.org/std/primitive.u128.html#method.max_value) - -[std::u128::MIN](https://doc.rust-lang.org/std/u128/constant.MIN.html) - -[std::u128::MAX](https://doc.rust-lang.org/std/u128/constant.MIN.html) - -[usize::min_value](https://doc.rust-lang.org/std/primitive.usize.html#method.min_value) - -[usize::max_value](https://doc.rust-lang.org/std/primitive.usize.html#method.max_value) - -[std::usize::MIN](https://doc.rust-lang.org/std/usize/constant.MIN.html) - -[std::usize::MAX](https://doc.rust-lang.org/std/usize/constant.MIN.html) - -[std::f32::DIGITS](https://doc.rust-lang.org/std/f32/constant.DIGITS.html) - -[std::f32::EPSILON](https://doc.rust-lang.org/std/f32/constant.EPSILON.html) - -[std::f32::INFINITY](https://doc.rust-lang.org/std/f32/constant.INFINITY.html) - -[std::f32::MANTISSA_DIGITS](https://doc.rust-lang.org/std/f32/constant.MANTISSA_DIGITS.html) - -[std::f32::MAX](https://doc.rust-lang.org/std/f32/constant.MAX.html) - -[std::f32::MAX_10_EXP](https://doc.rust-lang.org/std/f32/constant.MAX_10_EXP.html) - -[std::f32::MAX_EXP](https://doc.rust-lang.org/std/f32/constant.MAX_EXP.html) - -[std::f32::MIN](https://doc.rust-lang.org/std/f32/constant.MIN.html) - -[std::f32::MIN_10_EXP](https://doc.rust-lang.org/std/f32/constant.MIN_10_EXP.html) - -[std::f32::MIN_EXP](https://doc.rust-lang.org/std/f32/constant.MIN_EXP.html) - -[std::f32::MIN_POSITIVE](https://doc.rust-lang.org/std/f32/constant.MIN_POSITIVE.html) - -[std::f32::NAN](https://doc.rust-lang.org/std/f32/constant.NAN.html) - -[std::f32::NEG_INFINITY](https://doc.rust-lang.org/std/f32/constant.NEG_INFINITY.html) - -[std::f32::RADIX](https://doc.rust-lang.org/std/f32/constant.RADIX.html) - -[std::f64::DIGITS](https://doc.rust-lang.org/std/f64/constant.DIGITS.html) - -[std::f64::EPSILON](https://doc.rust-lang.org/std/f64/constant.EPSILON.html) - -[std::f64::INFINITY](https://doc.rust-lang.org/std/f64/constant.INFINITY.html) - -[std::f64::MANTISSA_DIGITS](https://doc.rust-lang.org/std/f64/constant.MANTISSA_DIGITS.html) - -[std::f64::MAX](https://doc.rust-lang.org/std/f64/constant.MAX.html) - -[std::f64::MAX_10_EXP](https://doc.rust-lang.org/std/f64/constant.MAX_10_EXP.html) - -[std::f64::MAX_EXP](https://doc.rust-lang.org/std/f64/constant.MAX_EXP.html) - -[std::f64::MIN](https://doc.rust-lang.org/std/f64/constant.MIN.html) - -[std::f64::MIN_10_EXP](https://doc.rust-lang.org/std/f64/constant.MIN_10_EXP.html) - -[std::f64::MIN_EXP](https://doc.rust-lang.org/std/f64/constant.MIN_EXP.html) - -[std::f64::MIN_POSITIVE](https://doc.rust-lang.org/std/f64/constant.MIN_POSITIVE.html) - -[std::f64::NAN](https://doc.rust-lang.org/std/f64/constant.NAN.html) - -[std::f64::NEG_INFINITY](https://doc.rust-lang.org/std/f64/constant.NEG_INFINITY.html) - -[std::f64::RADIX](https://doc.rust-lang.org/std/f64/constant.RADIX.html) - -Replace each item with an associated const value on the appropriate type. Deprecate the twelve -integer type modules and remove them from the documentation. +1. Deprecate the following items in the standard library: + - i8::{[min_value](https://doc.rust-lang.org/std/primitive.i8.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i8.html#method.max_value)} + - std::i8::{[MIN](https://doc.rust-lang.org/std/i8/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i8/constant.MIN.html)} + - i16::{[min_value](https://doc.rust-lang.org/std/primitive.i16.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i16.html#method.max_value)} + - std::i16::{[MIN](https://doc.rust-lang.org/std/i16/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i16/constant.MIN.html)} + - i32::{[min_value](https://doc.rust-lang.org/std/primitive.i32.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i32.html#method.max_value)} + - std::i32::{[MIN](https://doc.rust-lang.org/std/i32/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i32/constant.MIN.html)} + - i64::{[min_value](https://doc.rust-lang.org/std/primitive.i64.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i64.html#method.max_value)} + - std::i64::{[MIN](https://doc.rust-lang.org/std/i64/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i64/constant.MIN.html)} + - i128::{[min_value](https://doc.rust-lang.org/std/primitive.i128.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i128.html#method.max_value)} + - std::i128::{[MIN](https://doc.rust-lang.org/std/i128/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i128/constant.MIN.html)} + - isize::{[min_value](https://doc.rust-lang.org/std/primitive.isize.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.isize.html#method.max_value)} + - std::isize::{[MIN](https://doc.rust-lang.org/std/isize/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/isize/constant.MIN.html)} + - u8::{[min_value](https://doc.rust-lang.org/std/primitive.u8.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u8.html#method.max_value)} + - std::u8::{[MIN](https://doc.rust-lang.org/std/u8/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u8/constant.MIN.html)} + - u16::{[min_value](https://doc.rust-lang.org/std/primitive.u16.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u16.html#method.max_value)} + - std::u16::{[MIN](https://doc.rust-lang.org/std/u16/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u16/constant.MIN.html)} + - u32::{[min_value](https://doc.rust-lang.org/std/primitive.u32.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u32.html#method.max_value)} + - std::u32::{[MIN](https://doc.rust-lang.org/std/u32/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u32/constant.MIN.html)} + - u64::{[min_value](https://doc.rust-lang.org/std/primitive.u64.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u64.html#method.max_value)} + - std::u64::{[MIN](https://doc.rust-lang.org/std/u64/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u64/constant.MIN.html)} + - u128::{[min_value](https://doc.rust-lang.org/std/primitive.u128.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u128.html#method.max_value)} + - std::u128::{[MIN](https://doc.rust-lang.org/std/u128/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u128/constant.MIN.html)} + - usize::{[min_value](https://doc.rust-lang.org/std/primitive.usize.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.usize.html#method.max_value)} + - std::usize::{[MIN](https://doc.rust-lang.org/std/usize/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/usize/constant.MIN.html)} + - std::f32::{[DIGITS](https://doc.rust-lang.org/std/f32/constant.DIGITS.html), [EPSILON](https://doc.rust-lang.org/std/f32/constant.EPSILON.html), [INFINITY](https://doc.rust-lang.org/std/f32/constant.INFINITY.html), [MANTISSA_DIGITS](https://doc.rust-lang.org/std/f32/constant.MANTISSA_DIGITS.html), [MAX](https://doc.rust-lang.org/std/f32/constant.MAX.html), [MAX_10_EXP](https://doc.rust-lang.org/std/f32/constant.MAX_10_EXP.html), [MAX_EXP](https://doc.rust-lang.org/std/f32/constant.MAX_EXP.html), [MIN](https://doc.rust-lang.org/std/f32/constant.MIN.html), [MIN_10_EXP](https://doc.rust-lang.org/std/f32/constant.MIN_10_EXP.html), [MIN_EXP](https://doc.rust-lang.org/std/f32/constant.MIN_EXP.html), [MIN_POSITIVE](https://doc.rust-lang.org/std/f32/constant.MIN_POSITIVE.html), [NAN](https://doc.rust-lang.org/std/f32/constant.NAN.html), [NEG_INFINITY](https://doc.rust-lang.org/std/f32/constant.NEG_INFINITY.html), [RADIX](https://doc.rust-lang.org/std/f32/constant.RADIX.html)} + - std::f64::{[DIGITS](https://doc.rust-lang.org/std/f64/constant.DIGITS.html), [EPSILON](https://doc.rust-lang.org/std/f64/constant.EPSILON.html), [INFINITY](https://doc.rust-lang.org/std/f64/constant.INFINITY.html), [MANTISSA_DIGITS](https://doc.rust-lang.org/std/f64/constant.MANTISSA_DIGITS.html), [MAX](https://doc.rust-lang.org/std/f64/constant.MAX.html), [MAX_10_EXP](https://doc.rust-lang.org/std/f64/constant.MAX_10_EXP.html), [MAX_EXP](https://doc.rust-lang.org/std/f64/constant.MAX_EXP.html), [MIN](https://doc.rust-lang.org/std/f64/constant.MIN.html), [MIN_10_EXP](https://doc.rust-lang.org/std/f64/constant.MIN_10_EXP.html), [MIN_EXP](https://doc.rust-lang.org/std/f64/constant.MIN_EXP.html), [MIN_POSITIVE](https://doc.rust-lang.org/std/f64/constant.MIN_POSITIVE.html), [NAN](https://doc.rust-lang.org/std/f64/constant.NAN.html), [NEG_INFINITY](https://doc.rust-lang.org/std/f64/constant.NEG_INFINITY.html), [RADIX](https://doc.rust-lang.org/std/f64/constant.RADIX.html)} +2. Deprecate the following modules and remove them from the stdlib documentation: `std::{i8, i16, i32, i64, i128, isize, u8, u16, u32, u64, u128, usize}` (note that this does not apply to either of `std::{f32, f64}`; see the Alternatives section below) +3. Add the following associated constants corresponding to the above deprecated module-level constants: + - i8::{MAX, MIN} + - i16::{MAX, MIN} + - i32::{MAX, MIN} + - i64::{MAX, MIN} + - i128::{MAX, MIN} + - isize::{MAX, MIN} + - u8::{MAX, MIN} + - u16::{MAX, MIN} + - u32::{MAX, MIN} + - u64::{MAX, MIN} + - u128::{MAX, MIN} + - usize::{MAX, MIN} + - f32::{DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX} + - f64::{DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX} + +Future editions of Rust will additionally have the option of making these deprecated items +no longer accessible to users of the new edition. # Drawbacks [drawbacks]: #drawbacks -Deprecation warnings are annoying. - -# Rationale and alternatives -[rationale-and-alternatives]: #rationale-and-alternatives - -There is an alternative design where the proposed changes are also done to the `consts` submodules -in `std::f32` and `std::f64`, which contain constants of a more mathematical bent (the sort of -thing other languages might put in a `std::math` module). Doing so would be more consistent. Given -that we do not consider the mathematical/machine constant distinction to be particularly useful or -intuitive. In particular, this distinction is not consistent with the existing set of associated -functions implemented on `f32` and `f64`, which consist of a mix of both functions concerned with -mathematical operations (e.g. `f32::atanh`) and functions concerned with machine representation -(e.g. `f32::is_sign_negative`). The reason this RFC leaves the `consts` module as is, is because -the language currently does not allow imports of type-relative names, and likely never will. This -means every associated constant must be accessed by prefixing it with the type, `f32::PI` instead -of just `PI`. Having to do so met some resistance. So the scope of the RFC was changed to leave -the mathematical constants, where the exact float type might not be as important, compared to -constants tightly coupled with its type, such as for `MIN`. - -As noted, if a `math` module existed in Rust's stdlib this would be the natural place to put -aforementioned constants from `consts`, however, such a module does not exist; further, any -consideration of this hyptothetical module would, for the sake of consistency, want to also adopt -not only the aforementioned mathematical associated functions that currently exist on `f32` and -`f64`, but would also want to adopt the integral mathematical functions such as `i32::pow`--all -while in some way recreating the module-level distinction between the operations as they exist on -the various different numeric types. This is all to say that such a `std::math` module is out of -scope for this proposal, in addition to lacking the technical motivation of this proposal. -Ultimately, however, leaving `f32` and `f64` along and making the proposed changes only to the -integral types would still be considered a success by this RFC. +1. Deprecation warnings, although these can be trivially addressed. +2. Because associated items cannot be directly imported, code of the form `use i32::MAX; foo(MAX, MAX);` + will most likely be changed to `foo(i32::MAX, i32::MAX)`, which is slightly more verbose. + However, given how many `MAX` and `MIN` constants there are in the stdlib, + it is easy to argue that such unprefixed constants in the wild would be confusing, + and ought to be avoided in the first place. In any case, users desperate for such behavior + will be trivially capable of doing `const MAX = i32::MAX; foo(MAX, MAX);` + +# Alternatives +[alternatives]: #alternatives + +Unlike the twelve integral modules, the two floating-point modules would not themselves be +entirely deprecated by the changes proposed here. This is because the `std::f32` and `std::f64` +modules each contain a `consts` submodule, in which reside constants of a more mathematical bent +(the sort of things other languages might put in a `std::math` module). +It is the author's opinion that special treatment for such "math-oriented constants" (as opposed to +the "machine-oriented constants" addressed by this RFC) is not particularly precedented; e.g. this +separation is not consistent with the existing set of associated functions implemented on `f32` +and `f64`, which consist of a mix of both functions concerned with mathematical operations +(e.g. `f32::atanh`) and functions concerned with machine representation (e.g. +`f32::is_sign_negative`). However, although earlier versions of this RFC proposed deprecating +`std::{f32, f64}::consts`, the current version does not do so, as this was met with mild resistance +(and, in any case, the greatest gains from this RFC will be its impact on the integral modules). +Ultimately, there is no reason that such a change could not be left to a future RFC if desired. From a72cf50fc358ddeb14908fdf3fcc5b5f6c71a13f Mon Sep 17 00:00:00 2001 From: Ben Striegel Date: Wed, 4 Dec 2019 17:47:54 -0500 Subject: [PATCH 08/13] Further rationale and alternatives --- text/0000-associated-constants-on-ints.md | 28 +++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/text/0000-associated-constants-on-ints.md b/text/0000-associated-constants-on-ints.md index 07ea50514df..4c066dd2071 100644 --- a/text/0000-associated-constants-on-ints.md +++ b/text/0000-associated-constants-on-ints.md @@ -92,6 +92,11 @@ use std::u32; assert_eq!(u32::MAX, u32::max_value()); ``` +The fact that this sort of shadowing of primitive types works in the first place is surprising +even to experience Rust programmers; the fact that such a pattern is seemingly encouraged by +the standard library is even more of a surprise. By making this change we would be able to +remove all modules in the standard library whose names shadow primitive types. + # Guide-level explanation [guide-level-explanation]: #guide-level-explanation @@ -151,12 +156,12 @@ no longer accessible to users of the new edition. However, given how many `MAX` and `MIN` constants there are in the stdlib, it is easy to argue that such unprefixed constants in the wild would be confusing, and ought to be avoided in the first place. In any case, users desperate for such behavior - will be trivially capable of doing `const MAX = i32::MAX; foo(MAX, MAX);` + will be trivially capable of doing `const MAX: i32 = i32::MAX; foo(MAX, MAX);` # Alternatives [alternatives]: #alternatives -Unlike the twelve integral modules, the two floating-point modules would not themselves be +- Unlike the twelve integral modules, the two floating-point modules would not themselves be entirely deprecated by the changes proposed here. This is because the `std::f32` and `std::f64` modules each contain a `consts` submodule, in which reside constants of a more mathematical bent (the sort of things other languages might put in a `std::math` module). @@ -166,6 +171,21 @@ separation is not consistent with the existing set of associated functions imple and `f64`, which consist of a mix of both functions concerned with mathematical operations (e.g. `f32::atanh`) and functions concerned with machine representation (e.g. `f32::is_sign_negative`). However, although earlier versions of this RFC proposed deprecating -`std::{f32, f64}::consts`, the current version does not do so, as this was met with mild resistance -(and, in any case, the greatest gains from this RFC will be its impact on the integral modules). +`std::{f32, f64}::consts` (and thereby `std::{f32, f64}` as well), the current version does not do +so, as this was met with mild resistance (and, in any case, the greatest gains from this RFC will +be its impact on the integral modules). Ultimately, there is no reason that such a change could not be left to a future RFC if desired. +However, one alternative design would be to turn all the constants in `{f32, f64}` into associated +consts as well, which would leave no more modules in the standard library that shadow primitive +types. A different alternative would be to restrict this RFC only to the integral modules, leaving +f32 and f64 for a future RFC, since the integral modules are the most important aspect of this +RFC and it would be a shame for them to get bogged down by the unrelated concerns of the +floating-point modules. + +- Rather than immediately deprecating the existing items in the standard library, we could add +the new associated consts without any corresponding deprecations. The downside of this idea is +that we now have *three* ways of doing the exact same thing, and without deprecation warnings +(and their associated notes) there is little enough to guide users as to which is solution +is the idiomatic one. It is the author's opinion that there is no downside to deprecation +warnings in this case, especially since mitigation of the warning is trivial (as discussed in +the Drawbacks section above). From 888137791c8ddd8fd1c7643c96d66ee550048297 Mon Sep 17 00:00:00 2001 From: Ben Striegel Date: Wed, 4 Dec 2019 18:07:46 -0500 Subject: [PATCH 09/13] Nits --- text/0000-associated-constants-on-ints.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/text/0000-associated-constants-on-ints.md b/text/0000-associated-constants-on-ints.md index 4c066dd2071..ddfaba03221 100644 --- a/text/0000-associated-constants-on-ints.md +++ b/text/0000-associated-constants-on-ints.md @@ -86,16 +86,14 @@ glances from people new to Rust. 4. Removal of ambiguity between primitive types and their identically-named modules. Currently if you import an integer module and access constants in the module and methods on the type, one has no apparent indication as to what comes from where: - ```rust use std::u32; assert_eq!(u32::MAX, u32::max_value()); ``` - The fact that this sort of shadowing of primitive types works in the first place is surprising -even to experience Rust programmers; the fact that such a pattern is seemingly encouraged by +even to experienced Rust programmers; the fact that such a pattern is seemingly encouraged by the standard library is even more of a surprise. By making this change we would be able to -remove all modules in the standard library whose names shadow primitive types. +remove all modules in the standard library whose names shadow integral types. # Guide-level explanation [guide-level-explanation]: #guide-level-explanation From 69931876228ffce9d8be6e8b5e9a2a1d8fbe14b2 Mon Sep 17 00:00:00 2001 From: Ben Striegel Date: Wed, 4 Dec 2019 18:32:33 -0500 Subject: [PATCH 10/13] Additional motivation --- text/0000-associated-constants-on-ints.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/text/0000-associated-constants-on-ints.md b/text/0000-associated-constants-on-ints.md index ddfaba03221..89358df48e2 100644 --- a/text/0000-associated-constants-on-ints.md +++ b/text/0000-associated-constants-on-ints.md @@ -95,6 +95,10 @@ even to experienced Rust programmers; the fact that such a pattern is seemingly the standard library is even more of a surprise. By making this change we would be able to remove all modules in the standard library whose names shadow integral types. +5. Removal of a frustrating papercut. Even experienced Rust programmers are prone to trip over +this and curse at having to be reminded of a bizarre and jarring artifact of Rust 1.0. +By removing these artifacts we can make the experience of using Rust more universally pleasant. + # Guide-level explanation [guide-level-explanation]: #guide-level-explanation From 5352bf930fcfaa07ff76c17760522647ec2c3ced Mon Sep 17 00:00:00 2001 From: Ben Striegel Date: Thu, 16 Jan 2020 20:26:13 -0500 Subject: [PATCH 11/13] Add MIN_10_EXP, which was mistakenly omitted --- text/0000-associated-constants-on-ints.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-associated-constants-on-ints.md b/text/0000-associated-constants-on-ints.md index 89358df48e2..2054eacd3bf 100644 --- a/text/0000-associated-constants-on-ints.md +++ b/text/0000-associated-constants-on-ints.md @@ -143,8 +143,8 @@ By removing these artifacts we can make the experience of using Rust more univer - u64::{MAX, MIN} - u128::{MAX, MIN} - usize::{MAX, MIN} - - f32::{DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX} - - f64::{DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX} + - f32::{DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_10_EXP, MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX} + - f64::{DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_10_EXP, MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX} Future editions of Rust will additionally have the option of making these deprecated items no longer accessible to users of the new edition. From 4ec587782309de8bcfff826ff03565a898d364a4 Mon Sep 17 00:00:00 2001 From: Ben Striegel Date: Fri, 17 Jan 2020 18:36:49 -0500 Subject: [PATCH 12/13] Shuffle guide-level steps and deprecation question --- text/0000-associated-constants-on-ints.md | 75 ++++++++++++----------- 1 file changed, 40 insertions(+), 35 deletions(-) diff --git a/text/0000-associated-constants-on-ints.md b/text/0000-associated-constants-on-ints.md index 2054eacd3bf..5f3314c854f 100644 --- a/text/0000-associated-constants-on-ints.md +++ b/text/0000-associated-constants-on-ints.md @@ -102,35 +102,7 @@ By removing these artifacts we can make the experience of using Rust more univer # Guide-level explanation [guide-level-explanation]: #guide-level-explanation -1. Deprecate the following items in the standard library: - - i8::{[min_value](https://doc.rust-lang.org/std/primitive.i8.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i8.html#method.max_value)} - - std::i8::{[MIN](https://doc.rust-lang.org/std/i8/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i8/constant.MIN.html)} - - i16::{[min_value](https://doc.rust-lang.org/std/primitive.i16.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i16.html#method.max_value)} - - std::i16::{[MIN](https://doc.rust-lang.org/std/i16/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i16/constant.MIN.html)} - - i32::{[min_value](https://doc.rust-lang.org/std/primitive.i32.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i32.html#method.max_value)} - - std::i32::{[MIN](https://doc.rust-lang.org/std/i32/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i32/constant.MIN.html)} - - i64::{[min_value](https://doc.rust-lang.org/std/primitive.i64.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i64.html#method.max_value)} - - std::i64::{[MIN](https://doc.rust-lang.org/std/i64/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i64/constant.MIN.html)} - - i128::{[min_value](https://doc.rust-lang.org/std/primitive.i128.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i128.html#method.max_value)} - - std::i128::{[MIN](https://doc.rust-lang.org/std/i128/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i128/constant.MIN.html)} - - isize::{[min_value](https://doc.rust-lang.org/std/primitive.isize.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.isize.html#method.max_value)} - - std::isize::{[MIN](https://doc.rust-lang.org/std/isize/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/isize/constant.MIN.html)} - - u8::{[min_value](https://doc.rust-lang.org/std/primitive.u8.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u8.html#method.max_value)} - - std::u8::{[MIN](https://doc.rust-lang.org/std/u8/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u8/constant.MIN.html)} - - u16::{[min_value](https://doc.rust-lang.org/std/primitive.u16.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u16.html#method.max_value)} - - std::u16::{[MIN](https://doc.rust-lang.org/std/u16/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u16/constant.MIN.html)} - - u32::{[min_value](https://doc.rust-lang.org/std/primitive.u32.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u32.html#method.max_value)} - - std::u32::{[MIN](https://doc.rust-lang.org/std/u32/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u32/constant.MIN.html)} - - u64::{[min_value](https://doc.rust-lang.org/std/primitive.u64.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u64.html#method.max_value)} - - std::u64::{[MIN](https://doc.rust-lang.org/std/u64/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u64/constant.MIN.html)} - - u128::{[min_value](https://doc.rust-lang.org/std/primitive.u128.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u128.html#method.max_value)} - - std::u128::{[MIN](https://doc.rust-lang.org/std/u128/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u128/constant.MIN.html)} - - usize::{[min_value](https://doc.rust-lang.org/std/primitive.usize.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.usize.html#method.max_value)} - - std::usize::{[MIN](https://doc.rust-lang.org/std/usize/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/usize/constant.MIN.html)} - - std::f32::{[DIGITS](https://doc.rust-lang.org/std/f32/constant.DIGITS.html), [EPSILON](https://doc.rust-lang.org/std/f32/constant.EPSILON.html), [INFINITY](https://doc.rust-lang.org/std/f32/constant.INFINITY.html), [MANTISSA_DIGITS](https://doc.rust-lang.org/std/f32/constant.MANTISSA_DIGITS.html), [MAX](https://doc.rust-lang.org/std/f32/constant.MAX.html), [MAX_10_EXP](https://doc.rust-lang.org/std/f32/constant.MAX_10_EXP.html), [MAX_EXP](https://doc.rust-lang.org/std/f32/constant.MAX_EXP.html), [MIN](https://doc.rust-lang.org/std/f32/constant.MIN.html), [MIN_10_EXP](https://doc.rust-lang.org/std/f32/constant.MIN_10_EXP.html), [MIN_EXP](https://doc.rust-lang.org/std/f32/constant.MIN_EXP.html), [MIN_POSITIVE](https://doc.rust-lang.org/std/f32/constant.MIN_POSITIVE.html), [NAN](https://doc.rust-lang.org/std/f32/constant.NAN.html), [NEG_INFINITY](https://doc.rust-lang.org/std/f32/constant.NEG_INFINITY.html), [RADIX](https://doc.rust-lang.org/std/f32/constant.RADIX.html)} - - std::f64::{[DIGITS](https://doc.rust-lang.org/std/f64/constant.DIGITS.html), [EPSILON](https://doc.rust-lang.org/std/f64/constant.EPSILON.html), [INFINITY](https://doc.rust-lang.org/std/f64/constant.INFINITY.html), [MANTISSA_DIGITS](https://doc.rust-lang.org/std/f64/constant.MANTISSA_DIGITS.html), [MAX](https://doc.rust-lang.org/std/f64/constant.MAX.html), [MAX_10_EXP](https://doc.rust-lang.org/std/f64/constant.MAX_10_EXP.html), [MAX_EXP](https://doc.rust-lang.org/std/f64/constant.MAX_EXP.html), [MIN](https://doc.rust-lang.org/std/f64/constant.MIN.html), [MIN_10_EXP](https://doc.rust-lang.org/std/f64/constant.MIN_10_EXP.html), [MIN_EXP](https://doc.rust-lang.org/std/f64/constant.MIN_EXP.html), [MIN_POSITIVE](https://doc.rust-lang.org/std/f64/constant.MIN_POSITIVE.html), [NAN](https://doc.rust-lang.org/std/f64/constant.NAN.html), [NEG_INFINITY](https://doc.rust-lang.org/std/f64/constant.NEG_INFINITY.html), [RADIX](https://doc.rust-lang.org/std/f64/constant.RADIX.html)} -2. Deprecate the following modules and remove them from the stdlib documentation: `std::{i8, i16, i32, i64, i128, isize, u8, u16, u32, u64, u128, usize}` (note that this does not apply to either of `std::{f32, f64}`; see the Alternatives section below) -3. Add the following associated constants corresponding to the above deprecated module-level constants: +1. Add the following associated constants to the relevant types in standard library, with their definitions taken from the corresponding legacy module-level constants: - i8::{MAX, MIN} - i16::{MAX, MIN} - i32::{MAX, MIN} @@ -146,19 +118,52 @@ By removing these artifacts we can make the experience of using Rust more univer - f32::{DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_10_EXP, MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX} - f64::{DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_10_EXP, MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX} -Future editions of Rust will additionally have the option of making these deprecated items -no longer accessible to users of the new edition. +2. Redefine the following module-level constants in terms of the associated constants added in step 1: + - std::i8::{[MIN](https://doc.rust-lang.org/std/i8/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i8/constant.MIN.html)} + - std::i16::{[MIN](https://doc.rust-lang.org/std/i16/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i16/constant.MIN.html)} + - std::i32::{[MIN](https://doc.rust-lang.org/std/i32/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i32/constant.MIN.html)} + - std::i64::{[MIN](https://doc.rust-lang.org/std/i64/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i64/constant.MIN.html)} + - std::i128::{[MIN](https://doc.rust-lang.org/std/i128/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i128/constant.MIN.html)} + - std::isize::{[MIN](https://doc.rust-lang.org/std/isize/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/isize/constant.MIN.html)} + - std::u8::{[MIN](https://doc.rust-lang.org/std/u8/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u8/constant.MIN.html)} + - std::u16::{[MIN](https://doc.rust-lang.org/std/u16/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u16/constant.MIN.html)} + - std::u32::{[MIN](https://doc.rust-lang.org/std/u32/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u32/constant.MIN.html)} + - std::u64::{[MIN](https://doc.rust-lang.org/std/u64/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u64/constant.MIN.html)} + - std::u128::{[MIN](https://doc.rust-lang.org/std/u128/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u128/constant.MIN.html)} + - std::usize::{[MIN](https://doc.rust-lang.org/std/usize/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/usize/constant.MIN.html)} + - std::f32::{[DIGITS](https://doc.rust-lang.org/std/f32/constant.DIGITS.html), [EPSILON](https://doc.rust-lang.org/std/f32/constant.EPSILON.html), [INFINITY](https://doc.rust-lang.org/std/f32/constant.INFINITY.html), [MANTISSA_DIGITS](https://doc.rust-lang.org/std/f32/constant.MANTISSA_DIGITS.html), [MAX](https://doc.rust-lang.org/std/f32/constant.MAX.html), [MAX_10_EXP](https://doc.rust-lang.org/std/f32/constant.MAX_10_EXP.html), [MAX_EXP](https://doc.rust-lang.org/std/f32/constant.MAX_EXP.html), [MIN](https://doc.rust-lang.org/std/f32/constant.MIN.html), [MIN_10_EXP](https://doc.rust-lang.org/std/f32/constant.MIN_10_EXP.html), [MIN_EXP](https://doc.rust-lang.org/std/f32/constant.MIN_EXP.html), [MIN_POSITIVE](https://doc.rust-lang.org/std/f32/constant.MIN_POSITIVE.html), [NAN](https://doc.rust-lang.org/std/f32/constant.NAN.html), [NEG_INFINITY](https://doc.rust-lang.org/std/f32/constant.NEG_INFINITY.html), [RADIX](https://doc.rust-lang.org/std/f32/constant.RADIX.html)} + - std::f64::{[DIGITS](https://doc.rust-lang.org/std/f64/constant.DIGITS.html), [EPSILON](https://doc.rust-lang.org/std/f64/constant.EPSILON.html), [INFINITY](https://doc.rust-lang.org/std/f64/constant.INFINITY.html), [MANTISSA_DIGITS](https://doc.rust-lang.org/std/f64/constant.MANTISSA_DIGITS.html), [MAX](https://doc.rust-lang.org/std/f64/constant.MAX.html), [MAX_10_EXP](https://doc.rust-lang.org/std/f64/constant.MAX_10_EXP.html), [MAX_EXP](https://doc.rust-lang.org/std/f64/constant.MAX_EXP.html), [MIN](https://doc.rust-lang.org/std/f64/constant.MIN.html), [MIN_10_EXP](https://doc.rust-lang.org/std/f64/constant.MIN_10_EXP.html), [MIN_EXP](https://doc.rust-lang.org/std/f64/constant.MIN_EXP.html), [MIN_POSITIVE](https://doc.rust-lang.org/std/f64/constant.MIN_POSITIVE.html), [NAN](https://doc.rust-lang.org/std/f64/constant.NAN.html), [NEG_INFINITY](https://doc.rust-lang.org/std/f64/constant.NEG_INFINITY.html), [RADIX](https://doc.rust-lang.org/std/f64/constant.RADIX.html)} + +3. At a future point to be determined (see "Unresolved questions" below), deprecate the items listed in step 2. Additionally, deprecate the following associated functions: + - i8::{[min_value](https://doc.rust-lang.org/std/primitive.i8.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i8.html#method.max_value)} + - i16::{[min_value](https://doc.rust-lang.org/std/primitive.i16.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i16.html#method.max_value)} + - i32::{[min_value](https://doc.rust-lang.org/std/primitive.i32.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i32.html#method.max_value)} + - i64::{[min_value](https://doc.rust-lang.org/std/primitive.i64.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i64.html#method.max_value)} + - i128::{[min_value](https://doc.rust-lang.org/std/primitive.i128.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.i128.html#method.max_value)} + - isize::{[min_value](https://doc.rust-lang.org/std/primitive.isize.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.isize.html#method.max_value)} + - u8::{[min_value](https://doc.rust-lang.org/std/primitive.u8.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u8.html#method.max_value)} + - u16::{[min_value](https://doc.rust-lang.org/std/primitive.u16.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u16.html#method.max_value)} + - u32::{[min_value](https://doc.rust-lang.org/std/primitive.u32.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u32.html#method.max_value)} + - u64::{[min_value](https://doc.rust-lang.org/std/primitive.u64.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u64.html#method.max_value)} + - u128::{[min_value](https://doc.rust-lang.org/std/primitive.u128.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.u128.html#method.max_value)} + - usize::{[min_value](https://doc.rust-lang.org/std/primitive.usize.html#method.min_value), [max_value](https://doc.rust-lang.org/std/primitive.usize.html#method.max_value)} + +4. Following step 3, the following modules will be made hidden from the front page of the stdlib documentation, as they no longer contain any non-deprecated items: `std::{i8, i16, i32, i64, i128, isize, u8, u16, u32, u64, u128, usize}` (note that this does not apply to either of `std::{f32, f64}`; see the Alternatives section below) # Drawbacks [drawbacks]: #drawbacks -1. Deprecation warnings, although these can be trivially addressed. -2. Because associated items cannot be directly imported, code of the form `use i32::MAX; foo(MAX, MAX);` - will most likely be changed to `foo(i32::MAX, i32::MAX)`, which is slightly more verbose. +1. Deprecation warnings, although these can be easily addressed. +2. Because associated items cannot be directly imported, code of the form `use std::i32::MAX; foo(MAX, MAX);` + will most likely be changed to `foo(i32::MAX, i32::MAX)`, which may be marginally more verbose. However, given how many `MAX` and `MIN` constants there are in the stdlib, it is easy to argue that such unprefixed constants in the wild would be confusing, and ought to be avoided in the first place. In any case, users desperate for such behavior - will be trivially capable of doing `const MAX: i32 = i32::MAX; foo(MAX, MAX);` + will be trivially capable of replacing `use std::i32::MAX;` with `const MAX: i32 = i32::MAX;`. + +# Unresolved questions + +How long should we go before issuing a deprecation warning? At the extreme end of the scale we could wait until the next edition of Rust is released, and have the legacy items only issue deprecation warnings when opting in to the new edition; this would limit disruption only to people opting in to a new edition (and, being merely an trivially-addressed deprecation, would constitute far less of a disruption than any ordinary edition-related change; any impact of the deprecation would be mere noise in light of the broader edition-related impacts). However long it takes, it is the opinion of the author that deprecation should happen *eventually*, as we should not give the impression that it is the ideal state of things that there should exist three ways of finding the maximum value of an integer type; we expect experienced users to intuitively reach for the new way proposed in this RFC as the "natural" way these constants ought to be implemented, but for the sake of new users it would be a pedagogical wart to allow all three to exist without explicitly calling out the preferred one. # Alternatives [alternatives]: #alternatives From 2e1ed05ab31f205e0ba6f43e6380b38355165df5 Mon Sep 17 00:00:00 2001 From: Lukas Kalbertodt Date: Thu, 23 Jan 2020 20:57:50 +0100 Subject: [PATCH 13/13] Fill links for RFC 2700 --- ...ants-on-ints.md => 2700-associated-constants-on-ints.md} | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename text/{0000-associated-constants-on-ints.md => 2700-associated-constants-on-ints.md} (98%) diff --git a/text/0000-associated-constants-on-ints.md b/text/2700-associated-constants-on-ints.md similarity index 98% rename from text/0000-associated-constants-on-ints.md rename to text/2700-associated-constants-on-ints.md index 5f3314c854f..db06bdbc3fe 100644 --- a/text/0000-associated-constants-on-ints.md +++ b/text/2700-associated-constants-on-ints.md @@ -1,7 +1,7 @@ -- Feature Name: assoc-int-consts +- Feature Name: `assoc_int_consts` - Start Date: 2019-05-13 -- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000) -- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) +- RFC PR: [rust-lang/rfcs#2700](https://github.com/rust-lang/rfcs/pull/2700) +- Rust Issue: [rust-lang/rust#68490](https://github.com/rust-lang/rust/issues/68490) # Summary [summary]: #summary