Skip to content

Commit 8d3ae1b

Browse files
reddevilmidzyreddevilmidzy
committed
Expand pow docs with special-case tests
1 parent e124355 commit 8d3ae1b

File tree

7 files changed

+451
-12
lines changed

7 files changed

+451
-12
lines changed

‎library/core/src/num/f128.rs‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1769,7 +1769,39 @@ impl f128 {
17691769
/// let abs_difference = (x.powi(2) - (x * x)).abs();
17701770
/// assert!(abs_difference <= f128::EPSILON);
17711771
///
1772-
/// assert_eq!(f128::powi(f128::NAN, 0), 1.0);
1772+
/// // Special cases:
1773+
/// // pow(x, +-0) = 1 for any x
1774+
/// assert_eq!(f128::powi(3.0, 0), 1.0);
1775+
///
1776+
/// // pow(1, y) = 1 for any y
1777+
/// assert_eq!(f128::powi(1.0, 2), 1.0);
1778+
///
1779+
/// // pow(x, 1) = x for any x
1780+
/// assert_eq!(f128::powi(3.0, 1), 3.0);
1781+
///
1782+
/// // pow(nan, y) = nan
1783+
/// assert!(f128::powi(f128::NAN, 2).is_nan());
1784+
///
1785+
/// // pow(+-0, y) = +-inf for y an odd integer < 0
1786+
/// assert_eq!(f128::powi(0.0, -3), f128::INFINITY);
1787+
///
1788+
/// // pow(+-0, y) = +inf for finite y < 0 and not an odd integer
1789+
/// assert_eq!(f128::powi(0.0, -2), f128::INFINITY);
1790+
///
1791+
/// // pow(+-0, y) = +-0 for y an odd integer > 0
1792+
/// assert_eq!(f128::powi(-0.0, 3), -0.0);
1793+
///
1794+
/// // pow(+-0, y) = +0 for finite y > 0 and not an odd integer
1795+
/// assert_eq!(f128::powi(0.0, 2), 0.0);
1796+
///
1797+
/// // pow(+inf, y) = +inf for y > 0
1798+
/// assert_eq!(f128::powi(f128::INFINITY, 2), f128::INFINITY);
1799+
///
1800+
/// // pow(+inf, y) = +0 for y < 0
1801+
/// assert_eq!(f128::powi(f128::INFINITY, -2), 0.0);
1802+
///
1803+
/// // pow(-inf, y) = pow(-0, -y)
1804+
/// assert_eq!(f128::powi(f128::NEG_INFINITY, 2), f128::powi(-0.0, -2));
17731805
/// # }
17741806
/// ```
17751807
#[inline]

‎library/core/src/num/f16.rs‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1744,7 +1744,39 @@ impl f16 {
17441744
/// let abs_difference = (x.powi(2) - (x * x)).abs();
17451745
/// assert!(abs_difference <= f16::EPSILON);
17461746
///
1747-
/// assert_eq!(f16::powi(f16::NAN, 0), 1.0);
1747+
/// // Special cases:
1748+
/// // pow(x, +-0) = 1 for any x
1749+
/// assert_eq!(f16::powi(3.0, 0), 1.0);
1750+
///
1751+
/// // pow(1, y) = 1 for any y
1752+
/// assert_eq!(f16::powi(1.0, 2), 1.0);
1753+
///
1754+
/// // pow(x, 1) = x for any x
1755+
/// assert_eq!(f16::powi(3.0, 1), 3.0);
1756+
///
1757+
/// // pow(nan, y) = nan
1758+
/// assert!(f16::powi(f16::NAN, 2).is_nan());
1759+
///
1760+
/// // pow(+-0, y) = +-inf for y an odd integer < 0
1761+
/// assert_eq!(f16::powi(0.0, -3), f16::INFINITY);
1762+
///
1763+
/// // pow(+-0, y) = +inf for finite y < 0 and not an odd integer
1764+
/// assert_eq!(f16::powi(0.0, -2), f16::INFINITY);
1765+
///
1766+
/// // pow(+-0, y) = +-0 for y an odd integer > 0
1767+
/// assert_eq!(f16::powi(-0.0, 3), -0.0);
1768+
///
1769+
/// // pow(+-0, y) = +0 for finite y > 0 and not an odd integer
1770+
/// assert_eq!(f16::powi(0.0, 2), 0.0);
1771+
///
1772+
/// // pow(+inf, y) = +inf for y > 0
1773+
/// assert_eq!(f16::powi(f16::INFINITY, 2), f16::INFINITY);
1774+
///
1775+
/// // pow(+inf, y) = +0 for y < 0
1776+
/// assert_eq!(f16::powi(f16::INFINITY, -2), 0.0);
1777+
///
1778+
/// // pow(-inf, y) = pow(-0, -y)
1779+
/// assert_eq!(f16::powi(f16::NEG_INFINITY, 2), f16::powi(-0.0, -2));
17481780
/// # }
17491781
/// ```
17501782
#[inline]

‎library/core/src/num/int_macros.rs‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1715,6 +1715,19 @@ macro_rules! int_impl {
17151715
/// ```
17161716
#[doc = concat!("assert_eq!(8", stringify!($SelfT), ".checked_pow(2), Some(64));")]
17171717
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_pow(2), None);")]
1718+
///
1719+
/// // Special cases:
1720+
/// // any `self` to the power of zero always returns 1.
1721+
#[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".checked_pow(0), Some(1));")]
1722+
///
1723+
/// // 1 to the power of any `exp` always returns 1.
1724+
#[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".checked_pow(2), Some(1));")]
1725+
///
1726+
/// // any `self` to the power of one always returns `self`.
1727+
#[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".checked_pow(1), Some(3));")]
1728+
///
1729+
/// // 0 to the power of any `exp` always returns 0.
1730+
#[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".checked_pow(3), Some(0));")]
17181731
/// ```
17191732
17201733
#[stable(feature = "no_panic_pow", since = "1.34.0")]
@@ -1755,6 +1768,19 @@ macro_rules! int_impl {
17551768
///
17561769
/// ```
17571770
#[doc = concat!("assert_eq!(8", stringify!($SelfT), ".strict_pow(2), 64);")]
1771+
///
1772+
/// // Special cases:
1773+
/// // any `self` to the power of zero always returns 1.
1774+
#[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".strict_pow(0), 1);")]
1775+
///
1776+
/// // 1 to the power of any `exp` always returns 1.
1777+
#[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".strict_pow(2), 1);")]
1778+
///
1779+
/// // any `self` to the power of one always returns `self`.
1780+
#[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".strict_pow(1), 3);")]
1781+
///
1782+
/// // 0 to the power of any `exp` always returns 0.
1783+
#[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".strict_pow(3), 0);")]
17581784
/// ```
17591785
///
17601786
/// The following panics because of overflow:
@@ -2029,6 +2055,19 @@ macro_rules! int_impl {
20292055
#[doc = concat!("assert_eq!((-4", stringify!($SelfT), ").saturating_pow(3), -64);")]
20302056
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(2), ", stringify!($SelfT), "::MAX);")]
20312057
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(3), ", stringify!($SelfT), "::MIN);")]
2058+
///
2059+
/// // Special cases:
2060+
/// // any `self` to the power of zero always returns 1.
2061+
#[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".saturating_pow(0), 1);")]
2062+
///
2063+
/// // 1 to the power of any `exp` always returns 1.
2064+
#[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".saturating_pow(2), 1);")]
2065+
///
2066+
/// // any `self` to the power of one always returns `self`.
2067+
#[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".saturating_pow(1), 3);")]
2068+
///
2069+
/// // 0 to the power of any `exp` always returns 0.
2070+
#[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".saturating_pow(3), 0);")]
20322071
/// ```
20332072
#[stable(feature = "no_panic_pow", since = "1.34.0")]
20342073
#[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
@@ -2371,6 +2410,19 @@ macro_rules! int_impl {
23712410
#[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_pow(4), 81);")]
23722411
/// assert_eq!(3i8.wrapping_pow(5), -13);
23732412
/// assert_eq!(3i8.wrapping_pow(6), -39);
2413+
///
2414+
/// // Special cases:
2415+
/// // any `self` to the power of zero always returns 1.
2416+
#[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".wrapping_pow(0), 1);")]
2417+
///
2418+
/// // 1 to the power of any `exp` always returns 1.
2419+
#[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".wrapping_pow(2), 1);")]
2420+
///
2421+
/// // any `self` to the power of one always returns `self`.
2422+
#[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".wrapping_pow(1), 3);")]
2423+
///
2424+
/// // 0 to the power of any `exp` always returns 0.
2425+
#[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".wrapping_pow(3), 0);")]
23742426
/// ```
23752427
#[stable(feature = "no_panic_pow", since = "1.34.0")]
23762428
#[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
@@ -2962,6 +3014,20 @@ macro_rules! int_impl {
29623014
/// ```
29633015
#[doc = concat!("assert_eq!(3", stringify!($SelfT), ".overflowing_pow(4), (81, false));")]
29643016
/// assert_eq!(3i8.overflowing_pow(5), (-13, true));
3017+
///
3018+
/// // Special cases:
3019+
/// // any `self` to the power of zero always returns 1.
3020+
#[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".overflowing_pow(0), (1, false));")]
3021+
///
3022+
/// // 1 to the power of any `exp` always returns 1.
3023+
#[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".overflowing_pow(2), (1, false));")]
3024+
///
3025+
/// // any `self` to the power of one always returns `self`.
3026+
#[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".overflowing_pow(1), (3, false));")]
3027+
///
3028+
/// // 0 to the power of any `exp` always returns 0.
3029+
#[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".overflowing_pow(3), (0, false));")]
3030+
29653031
/// ```
29663032
#[stable(feature = "no_panic_pow", since = "1.34.0")]
29673033
#[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
@@ -3004,6 +3070,19 @@ macro_rules! int_impl {
30043070
#[doc = concat!("let x: ", stringify!($SelfT), " = 2; // or any other integer type")]
30053071
///
30063072
/// assert_eq!(x.pow(5), 32);
3073+
///
3074+
/// // Special cases:
3075+
/// // any `self` to the power of zero always returns 1.
3076+
#[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".pow(0), 1);")]
3077+
///
3078+
/// // 1 to the power of any `exp` always returns 1.
3079+
#[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".pow(2), 1);")]
3080+
///
3081+
/// // any `self` to the power of one always returns `self`.
3082+
#[doc = concat!("assert_eq!(3_", stringify!($SelfT), ".pow(1), 3);")]
3083+
///
3084+
/// // 0 to the power of any `exp` always returns 0.
3085+
#[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".pow(3), 0);")]
30073086
/// ```
30083087
#[stable(feature = "rust1", since = "1.0.0")]
30093088
#[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]

‎library/std/src/num/f128.rs‎

Lines changed: 60 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,66 @@ impl f128 {
3535
/// let abs_difference = (x.powf(2.0) - (x * x)).abs();
3636
/// assert!(abs_difference <= f128::EPSILON);
3737
///
38-
/// assert_eq!(f128::powf(1.0, f128::NAN), 1.0);
39-
/// assert_eq!(f128::powf(f128::NAN, 0.0), 1.0);
38+
/// // Special cases:
39+
/// // pow(x, +-0) = 1 for any x
40+
/// assert_eq!(f128::powf(3.0, 0.0), 1.0);
41+
///
42+
/// // pow(1, y) = 1 for any y
43+
/// assert_eq!(f128::powf(1.0, 2.0), 1.0);
44+
///
45+
/// // pow(x, 1) = x for any x
46+
/// assert_eq!(f128::powf(3.0, 1.0), 3.0);
47+
///
48+
/// // pow(nan, y) = nan
49+
/// assert!(f128::powf(f128::NAN, 2.0).is_nan());
50+
///
51+
/// // pow(x, nan) = nan
52+
/// assert!(f128::powf(2.0, f128::NAN).is_nan());
53+
///
54+
/// // pow(+-0, y) = +-inf for y an odd integer < 0
55+
/// assert_eq!(f128::powf(0.0, -3.0), f128::INFINITY);
56+
///
57+
/// // pow(+-0, -inf) = +inf
58+
/// assert_eq!(f128::powf(0.0, f128::NEG_INFINITY), f128::INFINITY);
59+
///
60+
/// // pow(+-0, +inf) = +0
61+
/// assert_eq!(f128::powf(0.0, f128::INFINITY), 0.0);
62+
///
63+
/// // pow(+-0, y) = +inf for finite y < 0 and not an odd integer
64+
/// assert_eq!(f128::powf(0.0, -2.0), f128::INFINITY);
65+
///
66+
/// // pow(+-0, y) = +-0 for y an odd integer > 0
67+
/// assert_eq!(f128::powf(-0.0, 3.0), -0.0);
68+
///
69+
/// // pow(+-0, y) = +0 for finite y > 0 and not an odd integer
70+
/// assert_eq!(f128::powf(0.0, 2.0), 0.0);
71+
///
72+
/// // pow(-1, +-inf) = 1
73+
/// assert_eq!(f128::powf(-1.0, f128::INFINITY), 1.0);
74+
///
75+
/// // pow(x, +inf) = +inf for |x| > 1
76+
/// assert_eq!(f128::powf(2.0, f128::INFINITY), f128::INFINITY);
77+
///
78+
/// // pow(x, -inf) = +0 for |x| > 1
79+
/// assert_eq!(f128::powf(2.0, f128::NEG_INFINITY), 0.0);
80+
///
81+
/// // pow(x, +inf) = +0 for |x| < 1
82+
/// assert_eq!(f128::powf(0.5, f128::INFINITY), 0.0);
83+
///
84+
/// // pow(x, -inf) = +inf for |x| < 1
85+
/// assert_eq!(f128::powf(0.5, f128::NEG_INFINITY), f128::INFINITY);
86+
///
87+
/// // pow(+inf, y) = +inf for y > 0
88+
/// assert_eq!(f128::powf(f128::INFINITY, 2.0), f128::INFINITY);
89+
///
90+
/// // pow(+inf, y) = +0 for y < 0
91+
/// assert_eq!(f128::powf(f128::INFINITY, -2.0), 0.0);
92+
///
93+
/// // pow(-inf, y) = pow(-0, -y)
94+
/// assert_eq!(f128::powf(f128::NEG_INFINITY, 2.0), f128::powf(-0.0, -2.0));
95+
///
96+
/// // pow(x, y) = nan for finite x < 0 and finite non-integer y
97+
/// assert!(f128::powf(-2.0, 0.5).is_nan());
4098
/// # }
4199
/// ```
42100
#[inline]

‎library/std/src/num/f16.rs‎

Lines changed: 60 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,66 @@ impl f16 {
3535
/// let abs_difference = (x.powf(2.0) - (x * x)).abs();
3636
/// assert!(abs_difference <= f16::EPSILON);
3737
///
38-
/// assert_eq!(f16::powf(1.0, f16::NAN), 1.0);
39-
/// assert_eq!(f16::powf(f16::NAN, 0.0), 1.0);
38+
/// // Special cases:
39+
/// // pow(x, +-0) = 1 for any x
40+
/// assert_eq!(f16::powf(3.0, 0.0), 1.0);
41+
///
42+
/// // pow(1, y) = 1 for any y
43+
/// assert_eq!(f16::powf(1.0, 2.0), 1.0);
44+
///
45+
/// // pow(x, 1) = x for any x
46+
/// assert_eq!(f16::powf(3.0, 1.0), 3.0);
47+
///
48+
/// // pow(nan, y) = nan
49+
/// assert!(f16::powf(f16::NAN, 2.0).is_nan());
50+
///
51+
/// // pow(x, nan) = nan
52+
/// assert!(f16::powf(2.0, f16::NAN).is_nan());
53+
///
54+
/// // pow(+-0, y) = +-inf for y an odd integer < 0
55+
/// assert_eq!(f16::powf(0.0, -3.0), f16::INFINITY);
56+
///
57+
/// // pow(+-0, -inf) = +inf
58+
/// assert_eq!(f16::powf(0.0, f16::NEG_INFINITY), f16::INFINITY);
59+
///
60+
/// // pow(+-0, +inf) = +0
61+
/// assert_eq!(f16::powf(0.0, f16::INFINITY), 0.0);
62+
///
63+
/// // pow(+-0, y) = +inf for finite y < 0 and not an odd integer
64+
/// assert_eq!(f16::powf(0.0, -2.0), f16::INFINITY);
65+
///
66+
/// // pow(+-0, y) = +-0 for y an odd integer > 0
67+
/// assert_eq!(f16::powf(-0.0, 3.0), -0.0);
68+
///
69+
/// // pow(+-0, y) = +0 for finite y > 0 and not an odd integer
70+
/// assert_eq!(f16::powf(0.0, 2.0), 0.0);
71+
///
72+
/// // pow(-1, +-inf) = 1
73+
/// assert_eq!(f16::powf(-1.0, f16::INFINITY), 1.0);
74+
///
75+
/// // pow(x, +inf) = +inf for |x| > 1
76+
/// assert_eq!(f16::powf(2.0, f16::INFINITY), f16::INFINITY);
77+
///
78+
/// // pow(x, -inf) = +0 for |x| > 1
79+
/// assert_eq!(f16::powf(2.0, f16::NEG_INFINITY), 0.0);
80+
///
81+
/// // pow(x, +inf) = +0 for |x| < 1
82+
/// assert_eq!(f16::powf(0.5, f16::INFINITY), 0.0);
83+
///
84+
/// // pow(x, -inf) = +inf for |x| < 1
85+
/// assert_eq!(f16::powf(0.5, f16::NEG_INFINITY), f16::INFINITY);
86+
///
87+
/// // pow(+inf, y) = +inf for y > 0
88+
/// assert_eq!(f16::powf(f16::INFINITY, 2.0), f16::INFINITY);
89+
///
90+
/// // pow(+inf, y) = +0 for y < 0
91+
/// assert_eq!(f16::powf(f16::INFINITY, -2.0), 0.0);
92+
///
93+
/// // pow(-inf, y) = pow(-0, -y)
94+
/// assert_eq!(f16::powf(f16::NEG_INFINITY, 2.0), f16::powf(-0.0, -2.0));
95+
///
96+
/// // pow(x, y) = nan for finite x < 0 and finite non-integer y
97+
/// assert!(f16::powf(-2.0, 0.5).is_nan());
4098
/// # }
4199
/// ```
42100
#[inline]

0 commit comments

Comments
 (0)