Skip to content

Commit 4ec5877

Browse files
author
Ben Striegel
committed
Shuffle guide-level steps and deprecation question
1 parent 5352bf9 commit 4ec5877

File tree

1 file changed

+40
-35
lines changed

1 file changed

+40
-35
lines changed

‎text/0000-associated-constants-on-ints.md

Lines changed: 40 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -102,35 +102,7 @@ By removing these artifacts we can make the experience of using Rust more univer
102102
# Guide-level explanation
103103
[guide-level-explanation]: #guide-level-explanation
104104

105-
1. Deprecate the following items in the standard library:
106-
- 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)}
107-
- std::i8::{[MIN](https://doc.rust-lang.org/std/i8/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i8/constant.MIN.html)}
108-
- 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)}
109-
- std::i16::{[MIN](https://doc.rust-lang.org/std/i16/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i16/constant.MIN.html)}
110-
- 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)}
111-
- std::i32::{[MIN](https://doc.rust-lang.org/std/i32/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i32/constant.MIN.html)}
112-
- 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)}
113-
- std::i64::{[MIN](https://doc.rust-lang.org/std/i64/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i64/constant.MIN.html)}
114-
- 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)}
115-
- std::i128::{[MIN](https://doc.rust-lang.org/std/i128/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i128/constant.MIN.html)}
116-
- 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)}
117-
- std::isize::{[MIN](https://doc.rust-lang.org/std/isize/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/isize/constant.MIN.html)}
118-
- 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)}
119-
- std::u8::{[MIN](https://doc.rust-lang.org/std/u8/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u8/constant.MIN.html)}
120-
- 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)}
121-
- std::u16::{[MIN](https://doc.rust-lang.org/std/u16/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u16/constant.MIN.html)}
122-
- 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)}
123-
- std::u32::{[MIN](https://doc.rust-lang.org/std/u32/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u32/constant.MIN.html)}
124-
- 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)}
125-
- std::u64::{[MIN](https://doc.rust-lang.org/std/u64/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u64/constant.MIN.html)}
126-
- 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)}
127-
- std::u128::{[MIN](https://doc.rust-lang.org/std/u128/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u128/constant.MIN.html)}
128-
- 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)}
129-
- std::usize::{[MIN](https://doc.rust-lang.org/std/usize/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/usize/constant.MIN.html)}
130-
- 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)}
131-
- 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)}
132-
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)
133-
3. Add the following associated constants corresponding to the above deprecated module-level constants:
105+
1. Add the following associated constants to the relevant types in standard library, with their definitions taken from the corresponding legacy module-level constants:
134106
- i8::{MAX, MIN}
135107
- i16::{MAX, MIN}
136108
- i32::{MAX, MIN}
@@ -146,19 +118,52 @@ By removing these artifacts we can make the experience of using Rust more univer
146118
- f32::{DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_10_EXP, MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX}
147119
- f64::{DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_10_EXP, MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX}
148120

149-
Future editions of Rust will additionally have the option of making these deprecated items
150-
no longer accessible to users of the new edition.
121+
2. Redefine the following module-level constants in terms of the associated constants added in step 1:
122+
- std::i8::{[MIN](https://doc.rust-lang.org/std/i8/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i8/constant.MIN.html)}
123+
- std::i16::{[MIN](https://doc.rust-lang.org/std/i16/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i16/constant.MIN.html)}
124+
- std::i32::{[MIN](https://doc.rust-lang.org/std/i32/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i32/constant.MIN.html)}
125+
- std::i64::{[MIN](https://doc.rust-lang.org/std/i64/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i64/constant.MIN.html)}
126+
- std::i128::{[MIN](https://doc.rust-lang.org/std/i128/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/i128/constant.MIN.html)}
127+
- std::isize::{[MIN](https://doc.rust-lang.org/std/isize/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/isize/constant.MIN.html)}
128+
- std::u8::{[MIN](https://doc.rust-lang.org/std/u8/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u8/constant.MIN.html)}
129+
- std::u16::{[MIN](https://doc.rust-lang.org/std/u16/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u16/constant.MIN.html)}
130+
- std::u32::{[MIN](https://doc.rust-lang.org/std/u32/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u32/constant.MIN.html)}
131+
- std::u64::{[MIN](https://doc.rust-lang.org/std/u64/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u64/constant.MIN.html)}
132+
- std::u128::{[MIN](https://doc.rust-lang.org/std/u128/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/u128/constant.MIN.html)}
133+
- std::usize::{[MIN](https://doc.rust-lang.org/std/usize/constant.MIN.html), [MAX](https://doc.rust-lang.org/std/usize/constant.MIN.html)}
134+
- 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)}
135+
- 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)}
136+
137+
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:
138+
- 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)}
139+
- 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)}
140+
- 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)}
141+
- 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)}
142+
- 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)}
143+
- 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)}
144+
- 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)}
145+
- 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)}
146+
- 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)}
147+
- 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)}
148+
- 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)}
149+
- 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)}
150+
151+
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)
151152

152153
# Drawbacks
153154
[drawbacks]: #drawbacks
154155

155-
1. Deprecation warnings, although these can be trivially addressed.
156-
2. Because associated items cannot be directly imported, code of the form `use i32::MAX; foo(MAX, MAX);`
157-
will most likely be changed to `foo(i32::MAX, i32::MAX)`, which is slightly more verbose.
156+
1. Deprecation warnings, although these can be easily addressed.
157+
2. Because associated items cannot be directly imported, code of the form `use std::i32::MAX; foo(MAX, MAX);`
158+
will most likely be changed to `foo(i32::MAX, i32::MAX)`, which may be marginally more verbose.
158159
However, given how many `MAX` and `MIN` constants there are in the stdlib,
159160
it is easy to argue that such unprefixed constants in the wild would be confusing,
160161
and ought to be avoided in the first place. In any case, users desperate for such behavior
161-
will be trivially capable of doing `const MAX: i32 = i32::MAX; foo(MAX, MAX);`
162+
will be trivially capable of replacing `use std::i32::MAX;` with `const MAX: i32 = i32::MAX;`.
163+
164+
# Unresolved questions
165+
166+
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.
162167

163168
# Alternatives
164169
[alternatives]: #alternatives

0 commit comments

Comments
 (0)