Document powf and powi calls that always return 1.0

4 files changed, 44 insertions, 6 deletions

diff --git a/library/std/src/f128.rs b/library/std/src/f128.rs
index 4f37e18a8cd..d65f5ed61cf 100644
--- a/library/std/src/f128.rs
+++ b/library/std/src/f128.rs
@@ -324,6 +324,20 @@ impl f128 {
     ///
     /// The precision of this function is non-deterministic. This means it varies by platform,
     /// Rust version, and can even differ within the same execution from one invocation to the next.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(f128)]
+    /// # #[cfg(reliable_f128_math)] {
+    ///
+    /// let x = 2.0_f128;
+    /// let abs_difference = (x.powi(2) - (x * x)).abs();
+    /// assert!(abs_difference <= f128::EPSILON);
+    ///
+    /// assert_eq!(f128::powi(f128::NAN, 0), 1.0);
+    /// # }
+    /// ```
     #[inline]
     #[rustc_allow_incoherent_impl]
     #[unstable(feature = "f128", issue = "116909")]
@@ -347,8 +361,10 @@ impl f128 {
     ///
     /// let x = 2.0_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);
     /// # }
     /// ```
     #[inline]
diff --git a/library/std/src/f16.rs b/library/std/src/f16.rs
index 42cd6e3fe2a..5b0903bceab 100644
--- a/library/std/src/f16.rs
+++ b/library/std/src/f16.rs
@@ -324,6 +324,20 @@ impl f16 {
     ///
     /// The precision of this function is non-deterministic. This means it varies by platform,
     /// Rust version, and can even differ within the same execution from one invocation to the next.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(f16)]
+    /// # #[cfg(reliable_f16_math)] {
+    ///
+    /// let x = 2.0_f16;
+    /// let abs_difference = (x.powi(2) - (x * x)).abs();
+    /// assert!(abs_difference <= f16::EPSILON);
+    ///
+    /// assert_eq!(f16::powi(f16::NAN, 0), 1.0);
+    /// # }
+    /// ```
     #[inline]
     #[rustc_allow_incoherent_impl]
     #[unstable(feature = "f16", issue = "116909")]
@@ -347,8 +361,10 @@ impl f16 {
     ///
     /// let x = 2.0_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);
     /// # }
     /// ```
     #[inline]
diff --git a/library/std/src/f32.rs b/library/std/src/f32.rs
index 438d77b1626..f9b6723788a 100644
--- a/library/std/src/f32.rs
+++ b/library/std/src/f32.rs
@@ -306,8 +306,9 @@ impl f32 {
     /// ```
     /// let x = 2.0_f32;
     /// let abs_difference = (x.powi(2) - (x * x)).abs();
-    ///
     /// assert!(abs_difference <= f32::EPSILON);
+    ///
+    /// assert_eq!(f32::powi(f32::NAN, 0), 1.0);
     /// ```
     #[rustc_allow_incoherent_impl]
     #[must_use = "method returns a new number and does not mutate the original value"]
@@ -329,8 +330,10 @@ impl f32 {
     /// ```
     /// let x = 2.0_f32;
     /// let abs_difference = (x.powf(2.0) - (x * x)).abs();
-    ///
     /// assert!(abs_difference <= f32::EPSILON);
+    ///
+    /// assert_eq!(f32::powf(1.0, f32::NAN), 1.0);
+    /// assert_eq!(f32::powf(f32::NAN, 0.0), 1.0);
     /// ```
     #[rustc_allow_incoherent_impl]
     #[must_use = "method returns a new number and does not mutate the original value"]
diff --git a/library/std/src/f64.rs b/library/std/src/f64.rs
index 9bb4bfbab2a..0de55a15d48 100644
--- a/library/std/src/f64.rs
+++ b/library/std/src/f64.rs
@@ -306,8 +306,9 @@ impl f64 {
     /// ```
     /// let x = 2.0_f64;
     /// let abs_difference = (x.powi(2) - (x * x)).abs();
+    /// assert!(abs_difference <= f64::EPSILON);
     ///
-    /// assert!(abs_difference < 1e-10);
+    /// assert_eq!(f64::powi(f64::NAN, 0), 1.0);
     /// ```
     #[rustc_allow_incoherent_impl]
     #[must_use = "method returns a new number and does not mutate the original value"]
@@ -329,8 +330,10 @@ impl f64 {
     /// ```
     /// let x = 2.0_f64;
     /// let abs_difference = (x.powf(2.0) - (x * x)).abs();
+    /// assert!(abs_difference <= f64::EPSILON);
     ///
-    /// assert!(abs_difference < 1e-10);
+    /// assert_eq!(f64::powf(1.0, f64::NAN), 1.0);
+    /// assert_eq!(f64::powf(f64::NAN, 0.0), 1.0);
     /// ```
     #[rustc_allow_incoherent_impl]
     #[must_use = "method returns a new number and does not mutate the original value"]