From 4b8bef3ffb4b1a090eee6a09edb428a434286f0c Mon Sep 17 00:00:00 2001
From: Jubilee Young <workingjubilee@gmail.com>
Date: Fri, 24 Sep 2021 16:59:46 -0700
Subject: [PATCH] deprecate f{32,64}::DIGITS

These constants are misleading: the number of significant digits
varies for each value that these floating point numbers may encode
but some programmers are taking them directly as an upper bound.
This is wrong and is leading to programmers creating applications
that directly mislead other users about their meaning, having
a negative ecosystem-wide impact on mathematical accuracy.

To contain the damage, deprecate them without replacement.
It is hoped this will force programmers to reevaluate their use.
---
 library/core/src/num/f32.rs | 25 +++++++++++++++++++------
 library/core/src/num/f64.rs | 26 ++++++++++++++++++++------
 2 files changed, 39 insertions(+), 12 deletions(-)

diff --git a/library/core/src/num/f32.rs b/library/core/src/num/f32.rs
index c47a2e8b05c4b..6df8732dd5afb 100644
--- a/library/core/src/num/f32.rs
+++ b/library/core/src/num/f32.rs
@@ -54,8 +54,9 @@ pub const RADIX: u32 = f32::RADIX;
 )]
 pub const MANTISSA_DIGITS: u32 = f32::MANTISSA_DIGITS;
 
-/// Approximate number of significant digits in base 10.
-/// Use [`f32::DIGITS`] instead.
+/// A minimum number of significant digits in base 10.
+/// This value is likely incorrect for usage,
+/// as it is not the upper limit of significant digits `f32` can contain.
 ///
 /// # Examples
 ///
@@ -63,12 +64,18 @@ pub const MANTISSA_DIGITS: u32 = f32::MANTISSA_DIGITS;
 /// // deprecated way
 /// # #[allow(deprecated, deprecated_in_future)]
 /// let d = std::f32::DIGITS;
-///
-/// // intended way
+/// // also deprecated
+/// # #[allow(deprecated, deprecated_in_future)]
 /// let d = f32::DIGITS;
+///
+/// // the intended way may vary by application
 /// ```
 #[stable(feature = "rust1", since = "1.0.0")]
-#[rustc_deprecated(since = "TBD", reason = "replaced by the `DIGITS` associated constant on `f32`")]
+#[rustc_deprecated(
+    since = "TBD",
+    reason = "this value is incorrect or misleading as it actually encompasses a range"
+)]
+#[allow(deprecated, deprecated_in_future)]
 pub const DIGITS: u32 = f32::DIGITS;
 
 /// [Machine epsilon] value for `f32`.
@@ -381,8 +388,14 @@ impl f32 {
     #[stable(feature = "assoc_int_consts", since = "1.43.0")]
     pub const MANTISSA_DIGITS: u32 = 24;
 
-    /// Approximate number of significant digits in base 10.
+    /// A minimum number of significant digits in base 10.
+    /// This value is likely incorrect for usage,
+    /// as it is not the upper limit of significant digits `f32` can contain.
     #[stable(feature = "assoc_int_consts", since = "1.43.0")]
+    #[rustc_deprecated(
+        since = "TBD",
+        reason = "this value is incorrect or misleading as it actually encompasses a range"
+    )]
     pub const DIGITS: u32 = 6;
 
     /// [Machine epsilon] value for `f32`.
diff --git a/library/core/src/num/f64.rs b/library/core/src/num/f64.rs
index cfcc08b9addeb..ec31a7a39a5b5 100644
--- a/library/core/src/num/f64.rs
+++ b/library/core/src/num/f64.rs
@@ -54,8 +54,9 @@ pub const RADIX: u32 = f64::RADIX;
 )]
 pub const MANTISSA_DIGITS: u32 = f64::MANTISSA_DIGITS;
 
-/// Approximate number of significant digits in base 10.
-/// Use [`f64::DIGITS`] instead.
+/// A minimum number of significant digits in base 10.
+/// This value is likely incorrect for usage,
+/// as it is not the upper limit of significant digits `f64` can contain.
 ///
 /// # Examples
 ///
@@ -63,12 +64,18 @@ pub const MANTISSA_DIGITS: u32 = f64::MANTISSA_DIGITS;
 /// // deprecated way
 /// # #[allow(deprecated, deprecated_in_future)]
 /// let d = std::f64::DIGITS;
-///
-/// // intended way
+/// // also deprecated
+/// # #[allow(deprecated, deprecated_in_future)]
 /// let d = f64::DIGITS;
+///
+/// // the intended way may vary by application
 /// ```
 #[stable(feature = "rust1", since = "1.0.0")]
-#[rustc_deprecated(since = "TBD", reason = "replaced by the `DIGITS` associated constant on `f64`")]
+#[rustc_deprecated(
+    since = "TBD",
+    reason = "this value is incorrect or misleading as it actually encompasses a range"
+)]
+#[allow(deprecated, deprecated_in_future)]
 pub const DIGITS: u32 = f64::DIGITS;
 
 /// [Machine epsilon] value for `f64`.
@@ -380,8 +387,15 @@ impl f64 {
     /// Number of significant digits in base 2.
     #[stable(feature = "assoc_int_consts", since = "1.43.0")]
     pub const MANTISSA_DIGITS: u32 = 53;
-    /// Approximate number of significant digits in base 10.
+
+    /// A minimum number of significant digits in base 10.
+    /// This value is likely incorrect for usage,
+    /// as it is not the upper limit of significant digits `f64` can contain.
     #[stable(feature = "assoc_int_consts", since = "1.43.0")]
+    #[rustc_deprecated(
+        since = "TBD",
+        reason = "this value is incorrect or misleading as it actually encompasses a range"
+    )]
     pub const DIGITS: u32 = 15;
 
     /// [Machine epsilon] value for `f64`.