From 0e6c3f29be98176c91aa77eb71c04cca18c51115 Mon Sep 17 00:00:00 2001 From: Raph Levien Date: Wed, 17 Oct 2018 18:15:00 -0700 Subject: [PATCH 1/3] 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 --- src/libstd/f32.rs | 28 ++++++++++++++++++++++++++++ src/libstd/f64.rs | 27 +++++++++++++++++++++++++++ 2 files changed, 55 insertions(+) diff --git a/src/libstd/f32.rs b/src/libstd/f32.rs index 8e8340b3ed901..4ae8d2dcf16b0 100644 --- a/src/libstd/f32.rs +++ b/src/libstd/f32.rs @@ -198,6 +198,34 @@ impl 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 6880294afcaaf..3b805d6fa42a6 100644 --- a/src/libstd/f64.rs +++ b/src/libstd/f64.rs @@ -176,6 +176,33 @@ impl 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. /// From 9a2e7026dcbd84641b05334b5b4b0a4d647944f4 Mon Sep 17 00:00:00 2001 From: Raph Levien Date: Wed, 17 Oct 2018 21:09:55 -0700 Subject: [PATCH 2/3] Fix inconsistent documentation I improved the f32 version and made a copy-paste error for f64. --- src/libstd/f32.rs | 2 +- src/libstd/f64.rs | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/src/libstd/f32.rs b/src/libstd/f32.rs index 4ae8d2dcf16b0..369745d818946 100644 --- a/src/libstd/f32.rs +++ b/src/libstd/f32.rs @@ -221,7 +221,7 @@ impl f32 { /// assert!(f32::NAN.copysign(1.0).is_nan()); /// ``` #[inline] - #[unstable(feature="copysign", issue="0")] + #[unstable(feature="copysign", issue="55169")] pub fn copysign(self, y: f32) -> f32 { unsafe { intrinsics::copysignf32(self, y) } } diff --git a/src/libstd/f64.rs b/src/libstd/f64.rs index 3b805d6fa42a6..df23d62ecfd6b 100644 --- a/src/libstd/f64.rs +++ b/src/libstd/f64.rs @@ -177,10 +177,11 @@ impl f64 { } /// Returns a number composed of the magnitude of one number and the sign of - /// another, or `NAN` if the number is `NAN`. + /// another. /// /// Equal to `self` if the sign of `self` and `y` are the same, otherwise - /// equal to `-y`. + /// equal to `-y`. If `self` is a `NAN`, then a `NAN` with the sign of `y` + /// is returned. /// /// # Examples /// @@ -198,7 +199,7 @@ impl f64 { /// assert!(f64::NAN.copysign(1.0).is_nan()); /// ``` #[inline] - #[unstable(feature="copysign", issue="0")] + #[unstable(feature="copysign", issue="55169")] pub fn copysign(self, y: f64) -> f64 { unsafe { intrinsics::copysignf64(self, y) } } From f08db6bf1ee44dd1bc8c4d3ddcea1425fcd8d118 Mon Sep 17 00:00:00 2001 From: Raph Levien Date: Thu, 18 Oct 2018 08:35:09 -0700 Subject: [PATCH 3/3] Add must_use on copysign Added a #[must_use] annotation on copysign, per review feedback. --- src/libstd/f32.rs | 1 + src/libstd/f64.rs | 1 + 2 files changed, 2 insertions(+) diff --git a/src/libstd/f32.rs b/src/libstd/f32.rs index 369745d818946..c3f225d1eb013 100644 --- a/src/libstd/f32.rs +++ b/src/libstd/f32.rs @@ -221,6 +221,7 @@ impl f32 { /// assert!(f32::NAN.copysign(1.0).is_nan()); /// ``` #[inline] + #[must_use] #[unstable(feature="copysign", issue="55169")] pub fn copysign(self, y: f32) -> f32 { unsafe { intrinsics::copysignf32(self, y) } diff --git a/src/libstd/f64.rs b/src/libstd/f64.rs index df23d62ecfd6b..da062dda77a47 100644 --- a/src/libstd/f64.rs +++ b/src/libstd/f64.rs @@ -199,6 +199,7 @@ impl f64 { /// assert!(f64::NAN.copysign(1.0).is_nan()); /// ``` #[inline] + #[must_use] #[unstable(feature="copysign", issue="55169")] pub fn copysign(self, y: f64) -> f64 { unsafe { intrinsics::copysignf64(self, y) }