Add a `copysign` function to f32 and f64

This patch adds a `copysign` function to the float primitive types.
It is an exceptionally useful function for writing efficient numeric
code, as it often avoids branches, is auto-vectorizable, and there
are efficient intrinsics for most platforms.

I think this might work as-is, as the relevant `copysign` intrinsic
is already used internally for the implementation of `signum`. It's
possible that an implementation might be needed in japaric/libm for
portability across all platforms, in which case I'll do that also.

Part of the work towards #55107

diff --git a/src/libstd/f32.rs b/src/libstd/f32.rs
index 8e8340b3ed901b557e23e7111bb54e236060cbc7..4ae8d2dcf16b09ca2432da8bf3dd948e9875ddab 100644 (file)
--- a/src/libstd/f32.rs
+++ b/src/libstd/f32.rs
@@ -198,6 +198,34 @@ pub fn signum(self) -> f32 {
         }
     }
 
+    /// Returns a number composed of the magnitude of one number and the sign of
+    /// another.
+    ///
+    /// Equal to `self` if the sign of `self` and `y` are the same, otherwise
+    /// equal to `-y`. If `self` is a `NAN`, then a `NAN` with the sign of `y`
+    /// is returned.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(copysign)]
+    /// use std::f32;
+    ///
+    /// let f = 3.5_f32;
+    ///
+    /// assert_eq!(f.copysign(0.42), 3.5_f32);
+    /// assert_eq!(f.copysign(-0.42), -3.5_f32);
+    /// assert_eq!((-f).copysign(0.42), 3.5_f32);
+    /// assert_eq!((-f).copysign(-0.42), -3.5_f32);
+    ///
+    /// assert!(f32::NAN.copysign(1.0).is_nan());
+    /// ```
+    #[inline]
+    #[unstable(feature="copysign", issue="0")]
+    pub fn copysign(self, y: f32) -> f32 {
+        unsafe { intrinsics::copysignf32(self, y) }
+    }
+
     /// Fused multiply-add. Computes `(self * a) + b` with only one rounding
     /// error, yielding a more accurate result than an unfused multiply-add.
     ///

diff --git a/src/libstd/f64.rs b/src/libstd/f64.rs
index 6880294afcaafd4f41c40f6d0ef448f3b5bd14fd..3b805d6fa42a61e5ee37ab973bdb6500ba99a60c 100644 (file)
--- a/src/libstd/f64.rs
+++ b/src/libstd/f64.rs
@@ -176,6 +176,33 @@ pub fn signum(self) -> f64 {
         }
     }
 
+    /// Returns a number composed of the magnitude of one number and the sign of
+    /// another, or `NAN` if the number is `NAN`.
+    ///
+    /// Equal to `self` if the sign of `self` and `y` are the same, otherwise
+    /// equal to `-y`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(copysign)]
+    /// use std::f64;
+    ///
+    /// let f = 3.5_f64;
+    ///
+    /// assert_eq!(f.copysign(0.42), 3.5_f64);
+    /// assert_eq!(f.copysign(-0.42), -3.5_f64);
+    /// assert_eq!((-f).copysign(0.42), 3.5_f64);
+    /// assert_eq!((-f).copysign(-0.42), -3.5_f64);
+    ///
+    /// assert!(f64::NAN.copysign(1.0).is_nan());
+    /// ```
+    #[inline]
+    #[unstable(feature="copysign", issue="0")]
+    pub fn copysign(self, y: f64) -> f64 {
+        unsafe { intrinsics::copysignf64(self, y) }
+    }
+
     /// Fused multiply-add. Computes `(self * a) + b` with only one rounding
     /// error, yielding a more accurate result than an unfused multiply-add.
     ///