diff --git a/library/core/src/num/f128.rs b/library/core/src/num/f128.rs index e7101537b298f..0f409c8bb08ac 100644 --- a/library/core/src/num/f128.rs +++ b/library/core/src/num/f128.rs @@ -1769,7 +1769,39 @@ impl f128 { /// let abs_difference = (x.powi(2) - (x * x)).abs(); /// assert!(abs_difference <= f128::EPSILON); /// - /// assert_eq!(f128::powi(f128::NAN, 0), 1.0); + /// // Special cases: + /// // pow(x, ±0) = 1 for any x + /// assert_eq!(f128::powi(3.0, 0), 1.0); + /// + /// // pow(1, y) = 1 for any y + /// assert_eq!(f128::powi(1.0, 2), 1.0); + /// + /// // pow(x, 1) = x for any x + /// assert_eq!(f128::powi(3.0, 1), 3.0); + /// + /// // pow(NaN, y) = NaN + /// assert!(f128::powi(f128::NAN, 2).is_nan()); + /// + /// // pow(±0, y) = ±Inf for y an odd integer < 0 + /// assert_eq!(f128::powi(0.0, -3), f128::INFINITY); + /// + /// // pow(±0, y) = +Inf for finite y < 0 and not an odd integer + /// assert_eq!(f128::powi(0.0, -2), f128::INFINITY); + /// + /// // pow(±0, y) = ±0 for y an odd integer > 0 + /// assert_eq!(f128::powi(-0.0, 3), -0.0); + /// + /// // pow(±0, y) = +0 for finite y > 0 and not an odd integer + /// assert_eq!(f128::powi(0.0, 2), 0.0); + /// + /// // pow(+Inf, y) = +Inf for y > 0 + /// assert_eq!(f128::powi(f128::INFINITY, 2), f128::INFINITY); + /// + /// // pow(+Inf, y) = +0 for y < 0 + /// assert_eq!(f128::powi(f128::INFINITY, -2), 0.0); + /// + /// // pow(-Inf, y) = pow(-0, -y) + /// assert_eq!(f128::powi(f128::NEG_INFINITY, 2), f128::powi(-0.0, -2)); /// # } /// ``` #[inline] diff --git a/library/core/src/num/f16.rs b/library/core/src/num/f16.rs index aa8342a22ad58..ade45d89e2f5a 100644 --- a/library/core/src/num/f16.rs +++ b/library/core/src/num/f16.rs @@ -1744,7 +1744,39 @@ impl f16 { /// let abs_difference = (x.powi(2) - (x * x)).abs(); /// assert!(abs_difference <= f16::EPSILON); /// - /// assert_eq!(f16::powi(f16::NAN, 0), 1.0); + /// // Special cases: + /// // pow(x, ±0) = 1 for any x + /// assert_eq!(f16::powi(3.0, 0), 1.0); + /// + /// // pow(1, y) = 1 for any y + /// assert_eq!(f16::powi(1.0, 2), 1.0); + /// + /// // pow(x, 1) = x for any x + /// assert_eq!(f16::powi(3.0, 1), 3.0); + /// + /// // pow(NaN, y) = NaN + /// assert!(f16::powi(f16::NAN, 2).is_nan()); + /// + /// // pow(±0, y) = ±Inf for y an odd integer < 0 + /// assert_eq!(f16::powi(0.0, -3), f16::INFINITY); + /// + /// // pow(±0, y) = +Inf for finite y < 0 and not an odd integer + /// assert_eq!(f16::powi(0.0, -2), f16::INFINITY); + /// + /// // pow(±0, y) = ±0 for y an odd integer > 0 + /// assert_eq!(f16::powi(-0.0, 3), -0.0); + /// + /// // pow(±0, y) = +0 for finite y > 0 and not an odd integer + /// assert_eq!(f16::powi(0.0, 2), 0.0); + /// + /// // pow(+Inf, y) = +Inf for y > 0 + /// assert_eq!(f16::powi(f16::INFINITY, 2), f16::INFINITY); + /// + /// // pow(+Inf, y) = +0 for y < 0 + /// assert_eq!(f16::powi(f16::INFINITY, -2), 0.0); + /// + /// // pow(-Inf, y) = pow(-0, -y) + /// assert_eq!(f16::powi(f16::NEG_INFINITY, 2), f16::powi(-0.0, -2)); /// # } /// ``` #[inline] diff --git a/library/core/src/num/int_macros.rs b/library/core/src/num/int_macros.rs index c3460a6409069..882e7f483bd04 100644 --- a/library/core/src/num/int_macros.rs +++ b/library/core/src/num/int_macros.rs @@ -1715,6 +1715,19 @@ macro_rules! int_impl { /// ``` #[doc = concat!("assert_eq!(8", stringify!($SelfT), ".checked_pow(2), Some(64));")] #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_pow(2), None);")] + /// + /// // Special cases: + /// // any `self` to the power of zero always returns 1. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".checked_pow(0), Some(1));")] + /// + /// // 1 to the power of any `exp` always returns 1. + #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".checked_pow(2), Some(1));")] + /// + /// // any `self` to the power of one always returns `self`. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".checked_pow(1), Some(3));")] + /// + /// // 0 to the power of any `exp` always returns 0. + #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".checked_pow(3), Some(0));")] /// ``` #[stable(feature = "no_panic_pow", since = "1.34.0")] @@ -1755,6 +1768,19 @@ macro_rules! int_impl { /// /// ``` #[doc = concat!("assert_eq!(8", stringify!($SelfT), ".strict_pow(2), 64);")] + /// + /// // Special cases: + /// // any `self` to the power of zero always returns 1. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".strict_pow(0), 1);")] + /// + /// // 1 to the power of any `exp` always returns 1. + #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".strict_pow(2), 1);")] + /// + /// // any `self` to the power of one always returns `self`. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".strict_pow(1), 3);")] + /// + /// // 0 to the power of any `exp` always returns 0. + #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".strict_pow(3), 0);")] /// ``` /// /// The following panics because of overflow: @@ -2029,6 +2055,19 @@ macro_rules! int_impl { #[doc = concat!("assert_eq!((-4", stringify!($SelfT), ").saturating_pow(3), -64);")] #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(2), ", stringify!($SelfT), "::MAX);")] #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(3), ", stringify!($SelfT), "::MIN);")] + /// + /// // Special cases: + /// // any `self` to the power of zero always returns 1. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".saturating_pow(0), 1);")] + /// + /// // 1 to the power of any `exp` always returns 1. + #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".saturating_pow(2), 1);")] + /// + /// // any `self` to the power of one always returns `self`. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".saturating_pow(1), 3);")] + /// + /// // 0 to the power of any `exp` always returns 0. + #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".saturating_pow(3), 0);")] /// ``` #[stable(feature = "no_panic_pow", since = "1.34.0")] #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] @@ -2371,6 +2410,19 @@ macro_rules! int_impl { #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_pow(4), 81);")] /// assert_eq!(3i8.wrapping_pow(5), -13); /// assert_eq!(3i8.wrapping_pow(6), -39); + /// + /// // Special cases: + /// // any `self` to the power of zero always returns 1. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".wrapping_pow(0), 1);")] + /// + /// // 1 to the power of any `exp` always returns 1. + #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".wrapping_pow(2), 1);")] + /// + /// // any `self` to the power of one always returns `self`. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".wrapping_pow(1), 3);")] + /// + /// // 0 to the power of any `exp` always returns 0. + #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".wrapping_pow(3), 0);")] /// ``` #[stable(feature = "no_panic_pow", since = "1.34.0")] #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] @@ -2962,6 +3014,19 @@ macro_rules! int_impl { /// ``` #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".overflowing_pow(4), (81, false));")] /// assert_eq!(3i8.overflowing_pow(5), (-13, true)); + /// + /// // Special cases: + /// // any `self` to the power of zero always returns 1. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".overflowing_pow(0), (1, false));")] + /// + /// // 1 to the power of any `exp` always returns 1. + #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".overflowing_pow(2), (1, false));")] + /// + /// // any `self` to the power of one always returns `self`. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".overflowing_pow(1), (3, false));")] + /// + /// // 0 to the power of any `exp` always returns 0. + #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".overflowing_pow(3), (0, false));")] /// ``` #[stable(feature = "no_panic_pow", since = "1.34.0")] #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] @@ -3004,6 +3069,19 @@ macro_rules! int_impl { #[doc = concat!("let x: ", stringify!($SelfT), " = 2; // or any other integer type")] /// /// assert_eq!(x.pow(5), 32); + /// + /// // Special cases: + /// // any `self` to the power of zero always returns 1. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".pow(0), 1);")] + /// + /// // 1 to the power of any `exp` always returns 1. + #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".pow(2), 1);")] + /// + /// // any `self` to the power of one always returns `self`. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".pow(1), 3);")] + /// + /// // 0 to the power of any `exp` always returns 0. + #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".pow(3), 0);")] /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] diff --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs index b5b768cf677aa..a682396885e97 100644 --- a/library/core/src/num/uint_macros.rs +++ b/library/core/src/num/uint_macros.rs @@ -2058,6 +2058,19 @@ macro_rules! uint_impl { /// ``` #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_pow(5), Some(32));")] #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_pow(2), None);")] + /// + /// // Special cases: + /// // any `self` to the power of zero always returns 1. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".checked_pow(0), Some(1));")] + /// + /// // 1 to the power of any `exp` always returns 1. + #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".checked_pow(2), Some(1));")] + /// + /// // any `self` to the power of one always returns `self`. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".checked_pow(1), Some(3));")] + /// + /// // 0 to the power of any `exp` always returns 0. + #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".checked_pow(3), Some(0));")] /// ``` #[stable(feature = "no_panic_pow", since = "1.34.0")] #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] @@ -2097,6 +2110,19 @@ macro_rules! uint_impl { /// /// ``` #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".strict_pow(5), 32);")] + /// + /// // Special cases: + /// // any `self` to the power of zero always returns 1. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".strict_pow(0), 1);")] + /// + /// // 1 to the power of any `exp` always returns 1. + #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".strict_pow(2), 1);")] + /// + /// // any `self` to the power of one always returns `self`. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".strict_pow(1), 3);")] + /// + /// // 0 to the power of any `exp` always returns 0. + #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".strict_pow(3), 0);")] /// ``` /// /// The following panics because of overflow: @@ -2272,6 +2298,19 @@ macro_rules! uint_impl { /// ``` #[doc = concat!("assert_eq!(4", stringify!($SelfT), ".saturating_pow(3), 64);")] #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_pow(2), ", stringify!($SelfT), "::MAX);")] + /// + /// // Special cases: + /// // any `self` to the power of zero always returns 1. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".saturating_pow(0), 1);")] + /// + /// // 1 to the power of any `exp` always returns 1. + #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".saturating_pow(2), 1);")] + /// + /// // any `self` to the power of one always returns `self`. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".saturating_pow(1), 3);")] + /// + /// // 0 to the power of any `exp` always returns 0. + #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".saturating_pow(3), 0);")] /// ``` #[stable(feature = "no_panic_pow", since = "1.34.0")] #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] @@ -2580,6 +2619,19 @@ macro_rules! uint_impl { /// ``` #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_pow(5), 243);")] /// assert_eq!(3u8.wrapping_pow(6), 217); + /// + /// // Special cases: + /// // any `self` to the power of zero always returns 1. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".wrapping_pow(0), 1);")] + /// + /// // 1 to the power of any `exp` always returns 1. + #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".wrapping_pow(2), 1);")] + /// + /// // any `self` to the power of one always returns `self`. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".wrapping_pow(1), 3);")] + /// + /// // 0 to the power of any `exp` always returns 0. + #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".wrapping_pow(3), 0);")] /// ``` #[stable(feature = "no_panic_pow", since = "1.34.0")] #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] @@ -3255,6 +3307,19 @@ macro_rules! uint_impl { /// ``` #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".overflowing_pow(5), (243, false));")] /// assert_eq!(3u8.overflowing_pow(6), (217, true)); + /// + /// // Special cases: + /// // any `self` to the power of zero always returns 1. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".overflowing_pow(0), (1, false));")] + /// + /// // 1 to the power of any `exp` always returns 1. + #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".overflowing_pow(2), (1, false));")] + /// + /// // any `self` to the power of one always returns `self`. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".overflowing_pow(1), (3, false));")] + /// + /// // 0 to the power of any `exp` always returns 0. + #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".overflowing_pow(3), (0, false));")] /// ``` #[stable(feature = "no_panic_pow", since = "1.34.0")] #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] @@ -3295,6 +3360,19 @@ macro_rules! uint_impl { /// /// ``` #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".pow(5), 32);")] + /// + /// // Special cases: + /// // any `self` to the power of zero always returns 1. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".pow(0), 1);")] + /// + /// // 1 to the power of any `exp` always returns 1. + #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".pow(2), 1);")] + /// + /// // any `self` to the power of one always returns `self`. + #[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".pow(1), 3);")] + /// + /// // 0 to the power of any `exp` always returns 0. + #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".pow(3), 0);")] /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] diff --git a/library/std/src/num/f128.rs b/library/std/src/num/f128.rs index 40061d089284b..5f7341e3f9c9b 100644 --- a/library/std/src/num/f128.rs +++ b/library/std/src/num/f128.rs @@ -35,8 +35,66 @@ impl f128 { /// let abs_difference = (x.powf(2.0) - (x * x)).abs(); /// assert!(abs_difference <= f128::EPSILON); /// - /// assert_eq!(f128::powf(1.0, f128::NAN), 1.0); - /// assert_eq!(f128::powf(f128::NAN, 0.0), 1.0); + /// // Special cases: + /// // pow(x, ±0) = 1 for any x + /// assert_eq!(f128::powf(3.0, 0.0), 1.0); + /// + /// // pow(1, y) = 1 for any y + /// assert_eq!(f128::powf(1.0, 2.0), 1.0); + /// + /// // pow(x, 1) = x for any x + /// assert_eq!(f128::powf(3.0, 1.0), 3.0); + /// + /// // pow(NaN, y) = NaN + /// assert!(f128::powf(f128::NAN, 2.0).is_nan()); + /// + /// // pow(x, NaN) = NaN + /// assert!(f128::powf(2.0, f128::NAN).is_nan()); + /// + /// // pow(±0, y) = ±Inf for y an odd integer < 0 + /// assert_eq!(f128::powf(0.0, -3.0), f128::INFINITY); + /// + /// // pow(±0, -Inf) = +Inf + /// assert_eq!(f128::powf(0.0, f128::NEG_INFINITY), f128::INFINITY); + /// + /// // pow(±0, +Inf) = +0 + /// assert_eq!(f128::powf(0.0, f128::INFINITY), 0.0); + /// + /// // pow(±0, y) = +Inf for finite y < 0 and not an odd integer + /// assert_eq!(f128::powf(0.0, -2.0), f128::INFINITY); + /// + /// // pow(±0, y) = ±0 for y an odd integer > 0 + /// assert_eq!(f128::powf(-0.0, 3.0), -0.0); + /// + /// // pow(±0, y) = +0 for finite y > 0 and not an odd integer + /// assert_eq!(f128::powf(0.0, 2.0), 0.0); + /// + /// // pow(-1, ±Inf) = 1 + /// assert_eq!(f128::powf(-1.0, f128::INFINITY), 1.0); + /// + /// // pow(x, +Inf) = +Inf for |x| > 1 + /// assert_eq!(f128::powf(2.0, f128::INFINITY), f128::INFINITY); + /// + /// // pow(x, -Inf) = +0 for |x| > 1 + /// assert_eq!(f128::powf(2.0, f128::NEG_INFINITY), 0.0); + /// + /// // pow(x, +Inf) = +0 for |x| < 1 + /// assert_eq!(f128::powf(0.5, f128::INFINITY), 0.0); + /// + /// // pow(x, -Inf) = +Inf for |x| < 1 + /// assert_eq!(f128::powf(0.5, f128::NEG_INFINITY), f128::INFINITY); + /// + /// // pow(+Inf, y) = +Inf for y > 0 + /// assert_eq!(f128::powf(f128::INFINITY, 2.0), f128::INFINITY); + /// + /// // pow(+Inf, y) = +0 for y < 0 + /// assert_eq!(f128::powf(f128::INFINITY, -2.0), 0.0); + /// + /// // pow(-Inf, y) = pow(-0, -y) + /// assert_eq!(f128::powf(f128::NEG_INFINITY, 2.0), f128::powf(-0.0, -2.0)); + /// + /// // pow(x, y) = NaN for finite x < 0 and finite non-integer y + /// assert!(f128::powf(-2.0, 0.5).is_nan()); /// # } /// ``` #[inline] diff --git a/library/std/src/num/f16.rs b/library/std/src/num/f16.rs index 0d43b60a62fea..2b0dcba905f5c 100644 --- a/library/std/src/num/f16.rs +++ b/library/std/src/num/f16.rs @@ -35,8 +35,66 @@ impl f16 { /// let abs_difference = (x.powf(2.0) - (x * x)).abs(); /// assert!(abs_difference <= f16::EPSILON); /// - /// assert_eq!(f16::powf(1.0, f16::NAN), 1.0); - /// assert_eq!(f16::powf(f16::NAN, 0.0), 1.0); + /// // Special cases: + /// // pow(x, ±0) = 1 for any x + /// assert_eq!(f16::powf(3.0, 0.0), 1.0); + /// + /// // pow(1, y) = 1 for any y + /// assert_eq!(f16::powf(1.0, 2.0), 1.0); + /// + /// // pow(x, 1) = x for any x + /// assert_eq!(f16::powf(3.0, 1.0), 3.0); + /// + /// // pow(NaN, y) = NaN + /// assert!(f16::powf(f16::NAN, 2.0).is_nan()); + /// + /// // pow(x, NaN) = NaN + /// assert!(f16::powf(2.0, f16::NAN).is_nan()); + /// + /// // pow(±0, y) = ±Inf for y an odd integer < 0 + /// assert_eq!(f16::powf(0.0, -3.0), f16::INFINITY); + /// + /// // pow(±0, -Inf) = +Inf + /// assert_eq!(f16::powf(0.0, f16::NEG_INFINITY), f16::INFINITY); + /// + /// // pow(±0, +Inf) = +0 + /// assert_eq!(f16::powf(0.0, f16::INFINITY), 0.0); + /// + /// // pow(±0, y) = +Inf for finite y < 0 and not an odd integer + /// assert_eq!(f16::powf(0.0, -2.0), f16::INFINITY); + /// + /// // pow(±0, y) = ±0 for y an odd integer > 0 + /// assert_eq!(f16::powf(-0.0, 3.0), -0.0); + /// + /// // pow(±0, y) = +0 for finite y > 0 and not an odd integer + /// assert_eq!(f16::powf(0.0, 2.0), 0.0); + /// + /// // pow(-1, ±Inf) = 1 + /// assert_eq!(f16::powf(-1.0, f16::INFINITY), 1.0); + /// + /// // pow(x, +Inf) = +Inf for |x| > 1 + /// assert_eq!(f16::powf(2.0, f16::INFINITY), f16::INFINITY); + /// + /// // pow(x, -Inf) = +0 for |x| > 1 + /// assert_eq!(f16::powf(2.0, f16::NEG_INFINITY), 0.0); + /// + /// // pow(x, +Inf) = +0 for |x| < 1 + /// assert_eq!(f16::powf(0.5, f16::INFINITY), 0.0); + /// + /// // pow(x, -Inf) = +Inf for |x| < 1 + /// assert_eq!(f16::powf(0.5, f16::NEG_INFINITY), f16::INFINITY); + /// + /// // pow(+Inf, y) = +Inf for y > 0 + /// assert_eq!(f16::powf(f16::INFINITY, 2.0), f16::INFINITY); + /// + /// // pow(+Inf, y) = +0 for y < 0 + /// assert_eq!(f16::powf(f16::INFINITY, -2.0), 0.0); + /// + /// // pow(-Inf, y) = pow(-0, -y) + /// assert_eq!(f16::powf(f16::NEG_INFINITY, 2.0), f16::powf(-0.0, -2.0)); + /// + /// // pow(x, y) = NaN for finite x < 0 and finite non-integer y + /// assert!(f16::powf(-2.0, 0.5).is_nan()); /// # } /// ``` #[inline] diff --git a/library/std/src/num/f32.rs b/library/std/src/num/f32.rs index c9e192201affc..fd3bf8c04d95b 100644 --- a/library/std/src/num/f32.rs +++ b/library/std/src/num/f32.rs @@ -307,7 +307,39 @@ impl f32 { /// let abs_difference = (x.powi(2) - (x * x)).abs(); /// assert!(abs_difference <= 1e-5); /// - /// assert_eq!(f32::powi(f32::NAN, 0), 1.0); + /// // Special cases: + /// // pow(x, ±0) = 1 for any x + /// assert_eq!(f32::powi(3.0, 0), 1.0); + /// + /// // pow(1, y) = 1 for any y + /// assert_eq!(f32::powi(1.0, 2), 1.0); + /// + /// // pow(x, 1) = x for any x + /// assert_eq!(f32::powi(3.0, 1), 3.0); + /// + /// // pow(NaN, y) = NaN + /// assert!(f32::powi(f32::NAN, 2).is_nan()); + /// + /// // pow(±0, y) = ±Inf for y an odd integer < 0 + /// assert_eq!(f32::powi(0.0, -3), f32::INFINITY); + /// + /// // pow(±0, y) = +Inf for finite y < 0 and not an odd integer + /// assert_eq!(f32::powi(0.0, -2), f32::INFINITY); + /// + /// // pow(±0, y) = ±0 for y an odd integer > 0 + /// assert_eq!(f32::powi(-0.0, 3), -0.0); + /// + /// // pow(±0, y) = +0 for finite y > 0 and not an odd integer + /// assert_eq!(f32::powi(0.0, 2), 0.0); + /// + /// // pow(+Inf, y) = +Inf for y > 0 + /// assert_eq!(f32::powi(f32::INFINITY, 2), f32::INFINITY); + /// + /// // pow(+Inf, y) = +0 for y < 0 + /// assert_eq!(f32::powi(f32::INFINITY, -2), 0.0); + /// + /// // pow(-Inf, y) = pow(-0, -y) + /// assert_eq!(f32::powi(f32::NEG_INFINITY, 2), f32::powi(-0.0, -2)); /// ``` #[rustc_allow_incoherent_impl] #[must_use = "method returns a new number and does not mutate the original value"] @@ -331,8 +363,66 @@ impl f32 { /// let abs_difference = (x.powf(2.0) - (x * x)).abs(); /// assert!(abs_difference <= 1e-5); /// - /// assert_eq!(f32::powf(1.0, f32::NAN), 1.0); - /// assert_eq!(f32::powf(f32::NAN, 0.0), 1.0); + /// // Special cases: + /// // pow(x, ±0) = 1 for any x + /// assert_eq!(f32::powf(3.0, 0.0), 1.0); + /// + /// // pow(1, y) = 1 for any y + /// assert_eq!(f32::powf(1.0, 2.0), 1.0); + /// + /// // pow(x, 1) = x for any x + /// assert_eq!(f32::powf(3.0, 1.0), 3.0); + /// + /// // pow(NaN, y) = NaN + /// assert!(f32::powf(f32::NAN, 2.0).is_nan()); + /// + /// // pow(x, NaN) = NaN + /// assert!(f32::powf(2.0, f32::NAN).is_nan()); + /// + /// // pow(±0, y) = ±Inf for y an odd integer < 0 + /// assert_eq!(f32::powf(0.0, -3.0), f32::INFINITY); + /// + /// // pow(±0, -Inf) = +Inf + /// assert_eq!(f32::powf(0.0, f32::NEG_INFINITY), f32::INFINITY); + /// + /// // pow(±0, +Inf) = +0 + /// assert_eq!(f32::powf(0.0, f32::INFINITY), 0.0); + /// + /// // pow(±0, y) = +Inf for finite y < 0 and not an odd integer + /// assert_eq!(f32::powf(0.0, -2.0), f32::INFINITY); + /// + /// // pow(±0, y) = ±0 for y an odd integer > 0 + /// assert_eq!(f32::powf(-0.0, 3.0), -0.0); + /// + /// // pow(±0, y) = +0 for finite y > 0 and not an odd integer + /// assert_eq!(f32::powf(0.0, 2.0), 0.0); + /// + /// // pow(-1, ±Inf) = 1 + /// assert_eq!(f32::powf(-1.0, f32::INFINITY), 1.0); + /// + /// // pow(x, +Inf) = +Inf for |x| > 1 + /// assert_eq!(f32::powf(2.0, f32::INFINITY), f32::INFINITY); + /// + /// // pow(x, -Inf) = +0 for |x| > 1 + /// assert_eq!(f32::powf(2.0, f32::NEG_INFINITY), 0.0); + /// + /// // pow(x, +Inf) = +0 for |x| < 1 + /// assert_eq!(f32::powf(0.5, f32::INFINITY), 0.0); + /// + /// // pow(x, -Inf) = +Inf for |x| < 1 + /// assert_eq!(f32::powf(0.5, f32::NEG_INFINITY), f32::INFINITY); + /// + /// // pow(+Inf, y) = +Inf for y > 0 + /// assert_eq!(f32::powf(f32::INFINITY, 2.0), f32::INFINITY); + /// + /// // pow(+Inf, y) = +0 for y < 0 + /// assert_eq!(f32::powf(f32::INFINITY, -2.0), 0.0); + /// + /// // pow(-Inf, y) = pow(-0, -y) + /// assert_eq!(f32::powf(f32::NEG_INFINITY, 2.0), f32::powf(-0.0, -2.0)); + /// + /// // pow(x, y) = NaN for finite x < 0 and finite non-integer y + /// assert!(f32::powf(-2.0, 0.5).is_nan()); /// ``` #[rustc_allow_incoherent_impl] #[must_use = "method returns a new number and does not mutate the original value"] diff --git a/library/std/src/num/f64.rs b/library/std/src/num/f64.rs index 11874f9280f02..85a637f1554c5 100644 --- a/library/std/src/num/f64.rs +++ b/library/std/src/num/f64.rs @@ -307,7 +307,39 @@ impl f64 { /// let abs_difference = (x.powi(2) - (x * x)).abs(); /// assert!(abs_difference <= 1e-14); /// - /// assert_eq!(f64::powi(f64::NAN, 0), 1.0); + /// // Special cases: + /// // pow(x, ±0) = 1 for any x + /// assert_eq!(f64::powi(3.0, 0), 1.0); + /// + /// // pow(1, y) = 1 for any y + /// assert_eq!(f64::powi(1.0, 2), 1.0); + /// + /// // pow(x, 1) = x for any x + /// assert_eq!(f64::powi(3.0, 1), 3.0); + /// + /// // pow(NaN, y) = NaN + /// assert!(f64::powi(f64::NAN, 2).is_nan()); + /// + /// // pow(±0, y) = ±Inf for y an odd integer < 0 + /// assert_eq!(f64::powi(0.0, -3), f64::INFINITY); + /// + /// // pow(±0, y) = +Inf for finite y < 0 and not an odd integer + /// assert_eq!(f64::powi(0.0, -2), f64::INFINITY); + /// + /// // pow(±0, y) = ±0 for y an odd integer > 0 + /// assert_eq!(f64::powi(-0.0, 3), -0.0); + /// + /// // pow(±0, y) = +0 for finite y > 0 and not an odd integer + /// assert_eq!(f64::powi(0.0, 2), 0.0); + /// + /// // pow(+Inf, y) = +Inf for y > 0 + /// assert_eq!(f64::powi(f64::INFINITY, 2), f64::INFINITY); + /// + /// // pow(+Inf, y) = +0 for y < 0 + /// assert_eq!(f64::powi(f64::INFINITY, -2), 0.0); + /// + /// // pow(-Inf, y) = pow(-0, -y) + /// assert_eq!(f64::powi(f64::NEG_INFINITY, 2), f64::powi(-0.0, -2)); /// ``` #[rustc_allow_incoherent_impl] #[must_use = "method returns a new number and does not mutate the original value"] @@ -331,8 +363,66 @@ impl f64 { /// let abs_difference = (x.powf(2.0) - (x * x)).abs(); /// assert!(abs_difference <= 1e-14); /// - /// assert_eq!(f64::powf(1.0, f64::NAN), 1.0); - /// assert_eq!(f64::powf(f64::NAN, 0.0), 1.0); + /// // Special cases: + /// // pow(x, ±0) = 1 for any x + /// assert_eq!(f64::powf(3.0, 0.0), 1.0); + /// + /// // pow(1, y) = 1 for any y + /// assert_eq!(f64::powf(1.0, 2.0), 1.0); + /// + /// // pow(x, 1) = x for any x + /// assert_eq!(f64::powf(3.0, 1.0), 3.0); + /// + /// // pow(NaN, y) = NaN + /// assert!(f64::powf(f64::NAN, 2.0).is_nan()); + /// + /// // pow(x, NaN) = NaN + /// assert!(f64::powf(2.0, f64::NAN).is_nan()); + /// + /// // pow(±0, y) = ±Inf for y an odd integer < 0 + /// assert_eq!(f64::powf(0.0, -3.0), f64::INFINITY); + /// + /// // pow(±0, -Inf) = +Inf + /// assert_eq!(f64::powf(0.0, f64::NEG_INFINITY), f64::INFINITY); + /// + /// // pow(±0, +Inf) = +0 + /// assert_eq!(f64::powf(0.0, f64::INFINITY), 0.0); + /// + /// // pow(±0, y) = +Inf for finite y < 0 and not an odd integer + /// assert_eq!(f64::powf(0.0, -2.0), f64::INFINITY); + /// + /// // pow(±0, y) = ±0 for y an odd integer > 0 + /// assert_eq!(f64::powf(-0.0, 3.0), -0.0); + /// + /// // pow(±0, y) = +0 for finite y > 0 and not an odd integer + /// assert_eq!(f64::powf(0.0, 2.0), 0.0); + /// + /// // pow(-1, ±Inf) = 1 + /// assert_eq!(f64::powf(-1.0, f64::INFINITY), 1.0); + /// + /// // pow(x, +Inf) = +Inf for |x| > 1 + /// assert_eq!(f64::powf(2.0, f64::INFINITY), f64::INFINITY); + /// + /// // pow(x, -Inf) = +0 for |x| > 1 + /// assert_eq!(f64::powf(2.0, f64::NEG_INFINITY), 0.0); + /// + /// // pow(x, +Inf) = +0 for |x| < 1 + /// assert_eq!(f64::powf(0.5, f64::INFINITY), 0.0); + /// + /// // pow(x, -Inf) = +Inf for |x| < 1 + /// assert_eq!(f64::powf(0.5, f64::NEG_INFINITY), f64::INFINITY); + /// + /// // pow(+Inf, y) = +Inf for y > 0 + /// assert_eq!(f64::powf(f64::INFINITY, 2.0), f64::INFINITY); + /// + /// // pow(+Inf, y) = +0 for y < 0 + /// assert_eq!(f64::powf(f64::INFINITY, -2.0), 0.0); + /// + /// // pow(-Inf, y) = pow(-0, -y) + /// assert_eq!(f64::powf(f64::NEG_INFINITY, 2.0), f64::powf(-0.0, -2.0)); + /// + /// // pow(x, y) = NaN for finite x < 0 and finite non-integer y + /// assert!(f64::powf(-2.0, 0.5).is_nan()); /// ``` #[rustc_allow_incoherent_impl] #[must_use = "method returns a new number and does not mutate the original value"]