From 0bb36a2f90358c5eb647655e9a891d26f9499bec Mon Sep 17 00:00:00 2001 From: Tobias Bucher Date: Mon, 25 Mar 2019 12:52:42 +0100 Subject: Clarify `{Ord,f32,f64}::clamp` docs a little Explicitly call out when it returns NaN, adhere to the panic doc guidelines. --- src/libstd/f32.rs | 22 ++++++++++++++++------ src/libstd/f64.rs | 21 +++++++++++++++------ 2 files changed, 31 insertions(+), 12 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/f32.rs b/src/libstd/f32.rs index 688d9c1aabb..796908b0df9 100644 --- a/src/libstd/f32.rs +++ b/src/libstd/f32.rs @@ -960,17 +960,27 @@ impl f32 { pub fn atanh(self) -> f32 { 0.5 * ((2.0 * self) / (1.0 - self)).ln_1p() } - /// Returns max if self is greater than max, and min if self is less than min. - /// Otherwise this returns self. Panics if min > max, min equals NaN, or max equals NaN. + + /// Restrict a value to a certain interval unless it is NaN. + /// + /// Returns `max` if `self` is greater than `max`, and `min` if `self` is + /// less than `min`. Otherwise this returns `self`. + /// + /// Not that this function returns NaN if the initial value was NaN as + /// well. + /// + /// # Panics + /// + /// Panics if `min > max`, `min` is NaN, or `max` is NaN. /// /// # Examples /// /// ``` /// #![feature(clamp)] - /// assert!((-3.0f32).clamp(-2.0f32, 1.0f32) == -2.0f32); - /// assert!((0.0f32).clamp(-2.0f32, 1.0f32) == 0.0f32); - /// assert!((2.0f32).clamp(-2.0f32, 1.0f32) == 1.0f32); - /// assert!((std::f32::NAN).clamp(-2.0f32, 1.0f32).is_nan()); + /// assert!((-3.0f32).clamp(-2.0, 1.0) == -2.0); + /// assert!((0.0f32).clamp(-2.0, 1.0) == 0.0); + /// assert!((2.0f32).clamp(-2.0, 1.0) == 1.0); + /// assert!((std::f32::NAN).clamp(-2.0, 1.0).is_nan()); /// ``` #[unstable(feature = "clamp", issue = "44095")] #[inline] diff --git a/src/libstd/f64.rs b/src/libstd/f64.rs index b171e1c7ac9..e679a7d2e8c 100644 --- a/src/libstd/f64.rs +++ b/src/libstd/f64.rs @@ -882,17 +882,26 @@ impl f64 { 0.5 * ((2.0 * self) / (1.0 - self)).ln_1p() } - /// Returns max if self is greater than max, and min if self is less than min. - /// Otherwise this returns self. Panics if min > max, min equals NaN, or max equals NaN. + /// Restrict a value to a certain interval unless it is NaN. + /// + /// Returns `max` if `self` is greater than `max`, and `min` if `self` is + /// less than `min`. Otherwise this returns `self`. + /// + /// Not that this function returns NaN if the initial value was NaN as + /// well. + /// + /// # Panics + /// + /// Panics if `min > max`, `min` is NaN, or `max` is NaN. /// /// # Examples /// /// ``` /// #![feature(clamp)] - /// assert!((-3.0f64).clamp(-2.0f64, 1.0f64) == -2.0f64); - /// assert!((0.0f64).clamp(-2.0f64, 1.0f64) == 0.0f64); - /// assert!((2.0f64).clamp(-2.0f64, 1.0f64) == 1.0f64); - /// assert!((std::f64::NAN).clamp(-2.0f64, 1.0f64).is_nan()); + /// assert!((-3.0f64).clamp(-2.0, 1.0) == -2.0); + /// assert!((0.0f64).clamp(-2.0, 1.0) == 0.0); + /// assert!((2.0f64).clamp(-2.0, 1.0) == 1.0); + /// assert!((std::f64::NAN).clamp(-2.0, 1.0).is_nan()); /// ``` #[unstable(feature = "clamp", issue = "44095")] #[inline] -- cgit 1.4.1-3-g733a5