Rollup merge of #121793 - tbu-:pr_floating_point_32, r=Amanieu

Document which methods on `f32` are precise

Same as #118217 but for `f32`.

1 files changed, 184 insertions, 0 deletions

diff --git a/library/std/src/f32.rs b/library/std/src/f32.rs
index b60d7a72411..6ec389400ae 100644
--- a/library/std/src/f32.rs
+++ b/library/std/src/f32.rs
@@ -31,6 +31,8 @@ pub use core::f32::{
 impl f32 {
     /// Returns the largest integer less than or equal to `self`.
     ///
+    /// This function always returns the precise result.
+    ///
     /// # Examples
     ///
     /// ```
@@ -52,6 +54,8 @@ impl f32 {
 
     /// Returns the smallest integer greater than or equal to `self`.
     ///
+    /// This function always returns the precise result.
+    ///
     /// # Examples
     ///
     /// ```
@@ -73,6 +77,8 @@ impl f32 {
     /// Returns the nearest integer to `self`. If a value is half-way between two
     /// integers, round away from `0.0`.
     ///
+    /// This function always returns the precise result.
+    ///
     /// # Examples
     ///
     /// ```
@@ -99,6 +105,8 @@ impl f32 {
     /// Returns the nearest integer to a number. Rounds half-way cases to the number
     /// with an even least significant digit.
     ///
+    /// This function always returns the precise result.
+    ///
     /// # Examples
     ///
     /// ```
@@ -123,6 +131,8 @@ impl f32 {
     /// Returns the integer part of `self`.
     /// This means that non-integer numbers are always truncated towards zero.
     ///
+    /// This function always returns the precise result.
+    ///
     /// # Examples
     ///
     /// ```
@@ -145,6 +155,8 @@ impl f32 {
 
     /// Returns the fractional part of `self`.
     ///
+    /// This function always returns the precise result.
+    ///
     /// # Examples
     ///
     /// ```
@@ -166,6 +178,8 @@ impl f32 {
 
     /// Computes the absolute value of `self`.
     ///
+    /// This function always returns the precise result.
+    ///
     /// # Examples
     ///
     /// ```
@@ -249,6 +263,12 @@ impl f32 {
     /// this is not always true, and will be heavily dependant on designing
     /// algorithms with specific target hardware in mind.
     ///
+    /// # Precision
+    ///
+    /// The result of this operation is guaranteed to be the rounded
+    /// infinite-precision result. It is specified by IEEE 754 as
+    /// `fusedMultiplyAdd` and guaranteed not to change.
+    ///
     /// # Examples
     ///
     /// ```
@@ -276,6 +296,11 @@ impl f32 {
     /// In other words, the result is `self / rhs` rounded to the integer `n`
     /// such that `self >= n * rhs`.
     ///
+    /// # Precision
+    ///
+    /// The result of this operation is guaranteed to be the rounded
+    /// infinite-precision result.
+    ///
     /// # Examples
     ///
     /// ```
@@ -309,6 +334,11 @@ impl f32 {
     /// property `self == self.div_euclid(rhs) * rhs + self.rem_euclid(rhs)`
     /// approximately.
     ///
+    /// # Precision
+    ///
+    /// The result of this operation is guaranteed to be the rounded
+    /// infinite-precision result.
+    ///
     /// # Examples
     ///
     /// ```
@@ -337,6 +367,10 @@ impl f32 {
     /// It might have a different sequence of rounding operations than `powf`,
     /// so the results are not guaranteed to agree.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    ///
     /// # Examples
     ///
     /// ```
@@ -355,6 +389,10 @@ impl f32 {
 
     /// Raises a number to a floating point power.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    ///
     /// # Examples
     ///
     /// ```
@@ -375,6 +413,12 @@ impl f32 {
     ///
     /// Returns NaN if `self` is a negative number other than `-0.0`.
     ///
+    /// # Precision
+    ///
+    /// The result of this operation is guaranteed to be the rounded
+    /// infinite-precision result. It is specified by IEEE 754 as `squareRoot`
+    /// and guaranteed not to change.
+    ///
     /// # Examples
     ///
     /// ```
@@ -398,6 +442,10 @@ impl f32 {
 
     /// Returns `e^(self)`, (the exponential function).
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    ///
     /// # Examples
     ///
     /// ```
@@ -420,6 +468,10 @@ impl f32 {
 
     /// Returns `2^(self)`.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    ///
     /// # Examples
     ///
     /// ```
@@ -440,6 +492,10 @@ impl f32 {
 
     /// Returns the natural logarithm of the number.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    ///
     /// # Examples
     ///
     /// ```
@@ -466,6 +522,10 @@ impl f32 {
     /// `self.log2()` can produce more accurate results for base 2, and
     /// `self.log10()` can produce more accurate results for base 10.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    ///
     /// # Examples
     ///
     /// ```
@@ -486,6 +546,10 @@ impl f32 {
 
     /// Returns the base 2 logarithm of the number.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    ///
     /// # Examples
     ///
     /// ```
@@ -506,6 +570,10 @@ impl f32 {
 
     /// Returns the base 10 logarithm of the number.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    ///
     /// # Examples
     ///
     /// ```
@@ -529,6 +597,12 @@ impl f32 {
     /// * If `self <= other`: `0.0`
     /// * Else: `self - other`
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `fdimf` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -561,6 +635,12 @@ impl f32 {
 
     /// Returns the cube root of a number.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `cbrtf` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -584,6 +664,12 @@ impl f32 {
     /// right-angle triangle with other sides having length `x.abs()` and
     /// `y.abs()`.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `hypotf` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -605,6 +691,10 @@ impl f32 {
 
     /// Computes the sine of a number (in radians).
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    ///
     /// # Examples
     ///
     /// ```
@@ -624,6 +714,10 @@ impl f32 {
 
     /// Computes the cosine of a number (in radians).
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    ///
     /// # Examples
     ///
     /// ```
@@ -643,6 +737,12 @@ impl f32 {
 
     /// Computes the tangent of a number (in radians).
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `tanf` from libc on Unix and
+    /// Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -663,6 +763,12 @@ impl f32 {
     /// the range [-pi/2, pi/2] or NaN if the number is outside the range
     /// [-1, 1].
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `asinf` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -686,6 +792,12 @@ impl f32 {
     /// the range [0, pi] or NaN if the number is outside the range
     /// [-1, 1].
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `acosf` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -708,6 +820,12 @@ impl f32 {
     /// Computes the arctangent of a number. Return value is in radians in the
     /// range [-pi/2, pi/2];
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `atanf` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -734,6 +852,12 @@ impl f32 {
     /// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]`
     /// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)`
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `atan2f` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -764,6 +888,12 @@ impl f32 {
     /// Simultaneously computes the sine and cosine of the number, `x`. Returns
     /// `(sin(x), cos(x))`.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `(f32::sin(x),
+    /// f32::cos(x))`. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -787,6 +917,12 @@ impl f32 {
     /// Returns `e^(self) - 1` in a way that is accurate even if the
     /// number is close to zero.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `expm1f` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -809,6 +945,12 @@ impl f32 {
     /// Returns `ln(1+n)` (natural logarithm) more accurately than if
     /// the operations were performed separately.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `log1pf` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -831,6 +973,12 @@ impl f32 {
 
     /// Hyperbolic sine function.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `sinhf` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -854,6 +1002,12 @@ impl f32 {
 
     /// Hyperbolic cosine function.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `coshf` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -877,6 +1031,12 @@ impl f32 {
 
     /// Hyperbolic tangent function.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `tanhf` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -900,6 +1060,10 @@ impl f32 {
 
     /// Inverse hyperbolic sine function.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    ///
     /// # Examples
     ///
     /// ```
@@ -923,6 +1087,10 @@ impl f32 {
 
     /// Inverse hyperbolic cosine function.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    ///
     /// # Examples
     ///
     /// ```
@@ -948,6 +1116,10 @@ impl f32 {
 
     /// Inverse hyperbolic tangent function.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    ///
     /// # Examples
     ///
     /// ```
@@ -969,6 +1141,12 @@ impl f32 {
 
     /// Gamma function.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `tgammaf` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```
@@ -991,6 +1169,12 @@ impl f32 {
     ///
     /// The integer part of the tuple indicates the sign of the gamma function.
     ///
+    /// # Platform-specific precision
+    ///
+    /// The precision of this function varies by platform and Rust version.
+    /// This function currently corresponds to the `lgamma_r` from libc on Unix
+    /// and Windows. Note that this might change in the future.
+    ///
     /// # Examples
     ///
     /// ```