Skip to content

Commit dc4cfcc

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

File tree

6 files changed

+372
-12
lines changed

6 files changed

+372
-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/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]

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

Lines changed: 93 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -307,7 +307,39 @@ impl f32 {
307307
/// let abs_difference = (x.powi(2) - (x * x)).abs();
308308
/// assert!(abs_difference <= 1e-5);
309309
///
310-
/// assert_eq!(f32::powi(f32::NAN, 0), 1.0);
310+
/// // Special cases:
311+
/// // pow(x, +-0) = 1 for any x
312+
/// assert_eq!(f32::powi(3.0, 0), 1.0);
313+
///
314+
/// // pow(1, y) = 1 for any y
315+
/// assert_eq!(f32::powi(1.0, 2), 1.0);
316+
///
317+
/// // pow(x, 1) = x for any x
318+
/// assert_eq!(f32::powi(3.0, 1), 3.0);
319+
///
320+
/// // pow(nan, y) = nan
321+
/// assert!(f32::powi(f32::NAN, 2).is_nan());
322+
///
323+
/// // pow(+-0, y) = +-inf for y an odd integer < 0
324+
/// assert_eq!(f32::powi(0.0, -3), f32::INFINITY);
325+
///
326+
/// // pow(+-0, y) = +inf for finite y < 0 and not an odd integer
327+
/// assert_eq!(f32::powi(0.0, -2), f32::INFINITY);
328+
///
329+
/// // pow(+-0, y) = +-0 for y an odd integer > 0
330+
/// assert_eq!(f32::powi(-0.0, 3), -0.0);
331+
///
332+
/// // pow(+-0, y) = +0 for finite y > 0 and not an odd integer
333+
/// assert_eq!(f32::powi(0.0, 2), 0.0);
334+
///
335+
/// // pow(+inf, y) = +inf for y > 0
336+
/// assert_eq!(f32::powi(f32::INFINITY, 2), f32::INFINITY);
337+
///
338+
/// // pow(+inf, y) = +0 for y < 0
339+
/// assert_eq!(f32::powi(f32::INFINITY, -2), 0.0);
340+
///
341+
/// // pow(-inf, y) = pow(-0, -y)
342+
/// assert_eq!(f32::powi(f32::NEG_INFINITY, 2), f32::powi(-0.0, -2));
311343
/// ```
312344
#[rustc_allow_incoherent_impl]
313345
#[must_use = "method returns a new number and does not mutate the original value"]
@@ -331,8 +363,66 @@ impl f32 {
331363
/// let abs_difference = (x.powf(2.0) - (x * x)).abs();
332364
/// assert!(abs_difference <= 1e-5);
333365
///
334-
/// assert_eq!(f32::powf(1.0, f32::NAN), 1.0);
335-
/// assert_eq!(f32::powf(f32::NAN, 0.0), 1.0);
366+
/// // Special cases:
367+
/// // pow(x, +-0) = 1 for any x
368+
/// assert_eq!(f32::powf(3.0, 0.0), 1.0);
369+
///
370+
/// // pow(1, y) = 1 for any y
371+
/// assert_eq!(f32::powf(1.0, 2.0), 1.0);
372+
///
373+
/// // pow(x, 1) = x for any x
374+
/// assert_eq!(f32::powf(3.0, 1.0), 3.0);
375+
///
376+
/// // pow(nan, y) = nan
377+
/// assert!(f32::powf(f32::NAN, 2.0).is_nan());
378+
///
379+
/// // pow(x, nan) = nan
380+
/// assert!(f32::powf(2.0, f32::NAN).is_nan());
381+
///
382+
/// // pow(+-0, y) = +-inf for y an odd integer < 0
383+
/// assert_eq!(f32::powf(0.0, -3.0), f32::INFINITY);
384+
///
385+
/// // pow(+-0, -inf) = +inf
386+
/// assert_eq!(f32::powf(0.0, f32::NEG_INFINITY), f32::INFINITY);
387+
///
388+
/// // pow(+-0, +inf) = +0
389+
/// assert_eq!(f32::powf(0.0, f32::INFINITY), 0.0);
390+
///
391+
/// // pow(+-0, y) = +inf for finite y < 0 and not an odd integer
392+
/// assert_eq!(f32::powf(0.0, -2.0), f32::INFINITY);
393+
///
394+
/// // pow(+-0, y) = +-0 for y an odd integer > 0
395+
/// assert_eq!(f32::powf(-0.0, 3.0), -0.0);
396+
///
397+
/// // pow(+-0, y) = +0 for finite y > 0 and not an odd integer
398+
/// assert_eq!(f32::powf(0.0, 2.0), 0.0);
399+
///
400+
/// // pow(-1, +-inf) = 1
401+
/// assert_eq!(f32::powf(-1.0, f32::INFINITY), 1.0);
402+
///
403+
/// // pow(x, +inf) = +inf for |x| > 1
404+
/// assert_eq!(f32::powf(2.0, f32::INFINITY), f32::INFINITY);
405+
///
406+
/// // pow(x, -inf) = +0 for |x| > 1
407+
/// assert_eq!(f32::powf(2.0, f32::NEG_INFINITY), 0.0);
408+
///
409+
/// // pow(x, +inf) = +0 for |x| < 1
410+
/// assert_eq!(f32::powf(0.5, f32::INFINITY), 0.0);
411+
///
412+
/// // pow(x, -inf) = +inf for |x| < 1
413+
/// assert_eq!(f32::powf(0.5, f32::NEG_INFINITY), f32::INFINITY);
414+
///
415+
/// // pow(+inf, y) = +inf for y > 0
416+
/// assert_eq!(f32::powf(f32::INFINITY, 2.0), f32::INFINITY);
417+
///
418+
/// // pow(+inf, y) = +0 for y < 0
419+
/// assert_eq!(f32::powf(f32::INFINITY, -2.0), 0.0);
420+
///
421+
/// // pow(-inf, y) = pow(-0, -y)
422+
/// assert_eq!(f32::powf(f32::NEG_INFINITY, 2.0), f32::powf(-0.0, -2.0));
423+
///
424+
/// // pow(x, y) = nan for finite x < 0 and finite non-integer y
425+
/// assert!(f32::powf(-2.0, 0.5).is_nan());
336426
/// ```
337427
#[rustc_allow_incoherent_impl]
338428
#[must_use = "method returns a new number and does not mutate the original value"]

0 commit comments

Comments
 (0)