Linear interpolation

library/std/src/f32.rs

@@ -876,4 +876,32 @@ impl f32 {
     pub fn atanh(self) -> f32 {
         0.5 * ((2.0 * self) / (1.0 - self)).ln_1p()
     }
+
+    /// Linear interpolation between `start` and `end`.
+    ///
+    /// This enables the calculation of a "smooth" transition between `start` and `end`,
+    /// where start is represented by `self == 0.0` and `end` is represented by `self == 1.0`.
+    ///
+    /// Values below 0.0 or above 1.0 are allowed, and in general this function closely
+    /// resembles the value of `start + self * (end - start)`, plus additional guarantees.
+    ///
+    /// Those guarantees are, assuming that all values are [`finite`]:
+    ///
+    /// * The value at 0.0 is always `start` and the value at 1.0 is always `end` (exactness)
+    /// * If `start == end`, the value at any point will always be `start == end` (consistency)
+    /// * The values will always move in the direction from `start` to `end` (monotonicity)
+    ///
+    /// [`finite`]: #method.is_finite
+    #[must_use = "method returns a new number and does not mutate the original value"]
+    #[unstable(feature = "float_interpolation", issue = "71015")]
+    pub fn lerp(self, start: f32, end: f32) -> f32 {
+        // consistent
+        if start == end {
+            start
+
+        // exact/monotonic
+        } else {
+            self.mul_add(end, (-self).mul_add(start, start))
+        }
+    }
 }

library/std/src/f32/tests.rs

@@ -757,3 +757,24 @@ fn test_total_cmp() {
     assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&f32::INFINITY));
     assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&s_nan()));
 }
+
+#[test]
+fn test_lerp_exact() {
+    assert_eq!(f32::lerp(0.0, 2.0, 4.0), 2.0);
+    assert_eq!(f32::lerp(1.0, 2.0, 4.0), 4.0);
+    assert_eq!(f32::lerp(0.0, f32::MIN, f32::MAX), f32::MIN);
+    assert_eq!(f32::lerp(1.0, f32::MIN, f32::MAX), f32::MAX);
+}
+
+#[test]
+fn test_lerp_consistent() {
+    assert_eq!(f32::lerp(f32::MAX, f32::MIN, f32::MIN), f32::MIN);
+    assert_eq!(f32::lerp(f32::MIN, f32::MAX, f32::MAX), f32::MAX);
+}
+
+#[test]
+fn test_lerp_values() {
+    assert_eq!(f32::lerp(0.25, 1.0, 2.0), 1.25);
+    assert_eq!(f32::lerp(0.50, 1.0, 2.0), 1.50);
+    assert_eq!(f32::lerp(0.75, 1.0, 2.0), 1.75);
+}

library/std/src/f64.rs

@@ -879,6 +879,34 @@ impl f64 {
         0.5 * ((2.0 * self) / (1.0 - self)).ln_1p()
     }
 
+    /// Linear interpolation between `start` and `end`.
+    ///
+    /// This enables the calculation of a "smooth" transition between `start` and `end`,
+    /// where start is represented by `self == 0.0` and `end` is represented by `self == 1.0`.
+    ///
+    /// Values below 0.0 or above 1.0 are allowed, and in general this function closely
+    /// resembles the value of `start + self * (end - start)`, plus additional guarantees.
+    ///
+    /// Those guarantees are, assuming that all values are [`finite`]:
+    ///
+    /// * The value at 0.0 is always `start` and the value at 1.0 is always `end` (exactness)
+    /// * If `start == end`, the value at any point will always be `start == end` (consistency)
+    /// * The values will always move in the direction from `start` to `end` (monotonicity)
+    ///
+    /// [`finite`]: #method.is_finite
+    #[must_use = "method returns a new number and does not mutate the original value"]
+    #[unstable(feature = "float_interpolation", issue = "71015")]
+    pub fn lerp(self, start: f64, end: f64) -> f64 {
+        // consistent
+        if start == end {
+            start
+
+        // exact/monotonic
+        } else {
+            self.mul_add(end, (-self).mul_add(start, start))
+        }
+    }
+
     // Solaris/Illumos requires a wrapper around log, log2, and log10 functions
     // because of their non-standard behavior (e.g., log(-n) returns -Inf instead
     // of expected NaN).

library/std/src/f64/tests.rs

@@ -753,3 +753,24 @@ fn test_total_cmp() {
     assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&f64::INFINITY));
     assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&s_nan()));
 }
+
+#[test]
+fn test_lerp_exact() {
+    assert_eq!(f64::lerp(0.0, 2.0, 4.0), 2.0);
+    assert_eq!(f64::lerp(1.0, 2.0, 4.0), 4.0);
+    assert_eq!(f64::lerp(0.0, f64::MIN, f64::MAX), f64::MIN);
+    assert_eq!(f64::lerp(1.0, f64::MIN, f64::MAX), f64::MAX);
+}
+
+#[test]
+fn test_lerp_consistent() {
+    assert_eq!(f64::lerp(f64::MAX, f64::MIN, f64::MIN), f64::MIN);
+    assert_eq!(f64::lerp(f64::MIN, f64::MAX, f64::MAX), f64::MAX);
+}
+
+#[test]
+fn test_lerp_values() {
+    assert_eq!(f64::lerp(0.25, 1.0, 2.0), 1.25);
+    assert_eq!(f64::lerp(0.50, 1.0, 2.0), 1.50);
+    assert_eq!(f64::lerp(0.75, 1.0, 2.0), 1.75);
+}

library/std/src/lib.rs

@@ -268,6 +268,7 @@
 #![feature(exhaustive_patterns)]
 #![feature(extend_one)]
 #![cfg_attr(bootstrap, feature(extended_key_value_attributes))]
+#![feature(float_interpolation)]
 #![feature(fn_traits)]
 #![feature(format_args_nl)]
 #![feature(gen_future)]