Rust: Tracking issue for RFC 2700: numeric constants as associated consts

[LukasKalbertodt]

This is a tracking issue for the RFC 2700 (rust-lang/rfcs#2700): "Deprecate stdlib modules dedicated to numeric constants and move those constants to associated consts".

Steps:

• [x] Add new constants (see #68325)
• [x] Stabilize new constants (see instructions on rustc-guide)
• [ ] Update test suite to use new constants (#78380)
• [ ] Fix error messages using old symbols (#78382)
• [ ] [Optional?] Support for indeterminate deprecation dates (#78381)
• [ ] Potentially deprecate old items (see unresolved questions below)
• [ ] Adjust documentation (see instructions on rustc-guide)

Unresolved questions:

• [ ] Should the old items be deprecated? See the RFC thread as well as "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.
• [ ] Should constants from std::{f32, f64}::consts also be made associated consts? From the alternative question of the RFC:
  > 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 (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.

[agausmann]

Add new constants (see #68123)

68325 is the relevant PR.

[faern]

I have implemented the stabilization and documentation changes needed to show people which constant is the preferred one now. I will submit this as a PR in a few days when the unstable version has been out for a bit over a week.

You can find the code here: https://github.com/rust-lang/rust/compare/master...faern:stabilize-assoc-int-consts?expand=1

What parts of it I don't think will be controversial at all:

• Stabilizing the unstable constants
• Updating the documentation on the old constants to indicate there are now better alternatives
• Update the integer/float documentation examples to actually use the new constants (the docs should reflect the preferred way)

Other changes that possibly might create some discussion:

• Exactly how to formulate the documentation telling people to not use the old constants any longer.
• Moved the min_value, max_value methods to the very bottom of the integer impl block, so they are not taking up the best spots in the documentation, but is rather moved away a bit. The MIN/MAX constants took their place. They can still of course easily be found, but they are not at the very top.

I opted for doing what Error::description() did with the documentation. Saying something like this:

//! **this module is soft-deprecated.**
//!
//! Although using these constants won’t cause compilation warnings,
//! new code should use the associated constants directly on
//! the [`i128` primitive type](../../std/primitive.i128.html) instead. 

I added soft deprecation notices to:

• Module level documentation of core and std modules for all integer and float types
• The old free standing MIN/MAX constants in the integer modules.
• The min_value/max_value methods on the integer types.

[faern]

The code/docs were changed a bit after I wrote that last comment just above. But the stabilization PR is live now.

[faern]

One thing that remains is to improve the compiler error that mentions the MIN and MAX constants. Try this code on nightly:

fn main() {
    match 5i32 {
        5 => (),
    }
}

It gives the following error:

error[E0004]: non-exhaustive patterns: `std::i32::MIN..=4i32` and `6i32..=std::i32::MAX` not covered

Now when the associated constants are the preferred ones the error should be

error[E0004]: non-exhaustive patterns: `i32::MIN..=4i32` and `6i32..=i32::MAX` not covered

[bstrie]

As the original author of RFC 2700, I propose the following resolution to the two currently-listed unresolved questions:

1. "Should the old items be deprecated?" I propose yes. I have a PR here for further discussion: https://github.com/rust-lang/rust/pull/78335

2. "Should constants from std::{f32, f64}::consts also be made associated consts?" I propose no. As mentioned in the RFC, the majority of the benefit of this change concerns the integer types, which have no analogue to the consts module on the float types. While it remains my opinion that having a stdlib type shadowing a primitive type is undesirable, I think it's reasonable to leave this topic to a future RFC.

[Lokathor]

if I can't just write f32::NAN then what the heck is the point of any of this.

[bstrie]

Unsure if that was meant to be sarcasm, but if you take the time to read the original RFC you will see that the point of all this is that std::u8::MAX and u8::max_value() are both substandard alternatives to u8::MAX that only exist because of extremely temporary historical technical limitations. When fixing this for the integral types it was natural to preserve symmetry with the floating point types as well. Some people objected to all the constants defined for the floating point types being given this treatment. Since the point of the RFC was to fix the integral types, we conceded so as to avoid gridlock over tangential concerns. The libs team could, of course, decide to change this policy (it would not be out of the realm of possibility to simply amend the existing RFC), but I am not on the libs team. My PR fully deprecates the constants that were superseded in https://github.com/rust-lang/rust/pull/68952 . I'm content to take this one step at a time.

[Lokathor]

I was not being sarcastic at all.

If floating types don't get the same design fixes applied them, then that's dumb for all the reasons that std::u8::MAX is dumb.

[bstrie]

You're preaching to the choir; as mentioned in the accepted RFC, the original RFC text had proposed this treatment for all the float constants. I'd be happy if the libs team decided to deprecate the float shadow modules as well, but in the absence of that decision there's no need to put off deprecating the integral shadow modules any longer. This RFC has gone on for quite long already.

[bstrie]

(It's also worth noting that your specific example of f32::NAN does indeed already exist as a result of this RFC, and the alternative std::f32::NAN would be deprecated by my PR. It's things like std::f32::consts::PI that wouldn't be.)

[bstrie]

In my deprecation PR I ran into some obstacles and have updated the issue here with references to new issues and PRs. I'll hold off on proposing deprecation until those are addressed.