From b5307f5d95a03c55f9ebbf00d7c1c876848f5622 Mon Sep 17 00:00:00 2001 From: Tobias Bucher Date: Thu, 29 Feb 2024 11:58:13 +0100 Subject: [PATCH] Document the precision of `f64` methods --- library/std/src/f64.rs | 184 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) diff --git a/library/std/src/f64.rs b/library/std/src/f64.rs index 88f992b3957..7385576c337 100644 --- a/library/std/src/f64.rs +++ b/library/std/src/f64.rs @@ -31,6 +31,8 @@ impl f64 { /// Returns the largest integer less than or equal to `self`. /// + /// This function always returns the precise result. + /// /// # Examples /// /// ``` @@ -52,6 +54,8 @@ pub fn floor(self) -> f64 { /// Returns the smallest integer greater than or equal to `self`. /// + /// This function always returns the precise result. + /// /// # Examples /// /// ``` @@ -73,6 +77,8 @@ pub fn ceil(self) -> f64 { /// 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 @@ pub fn round(self) -> f64 { /// 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 @@ pub fn round_ties_even(self) -> f64 { /// 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 @@ pub fn trunc(self) -> f64 { /// Returns the fractional part of `self`. /// + /// This function always returns the precise result. + /// /// # Examples /// /// ``` @@ -166,6 +178,8 @@ pub fn fract(self) -> f64 { /// Computes the absolute value of `self`. /// + /// This function always returns the precise result. + /// /// # Examples /// /// ``` @@ -249,6 +263,12 @@ pub fn copysign(self, sign: f64) -> f64 { /// 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 @@ pub fn mul_add(self, a: f64, b: f64) -> f64 { /// 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 @@ pub fn div_euclid(self, rhs: f64) -> f64 { /// 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 @@ pub fn rem_euclid(self, rhs: f64) -> f64 { /// 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 @@ pub fn powi(self, n: i32) -> f64 { /// 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 @@ pub fn powf(self, n: f64) -> f64 { /// /// 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 @@ pub fn sqrt(self) -> f64 { /// 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 @@ pub fn exp(self) -> f64 { /// Returns `2^(self)`. /// + /// # Platform-specific precision + /// + /// The precision of this function varies by platform and Rust version. + /// /// # Examples /// /// ``` @@ -440,6 +492,10 @@ pub fn exp2(self) -> f64 { /// 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 @@ pub fn ln(self) -> f64 { /// `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 @@ pub fn log(self, base: f64) -> f64 { /// 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 @@ pub fn log2(self) -> f64 { /// 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 @@ pub fn log10(self) -> f64 { /// * 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 `fdim` from libc on Unix and + /// Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -561,6 +635,12 @@ pub fn abs_sub(self, other: f64) -> f64 { /// 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 `cbrt` from libc on Unix and + /// Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -584,6 +664,12 @@ pub fn cbrt(self) -> f64 { /// 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 `hypot` from libc on Unix + /// and Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -605,6 +691,10 @@ pub fn hypot(self, other: f64) -> f64 { /// 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 @@ pub fn sin(self) -> f64 { /// 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 @@ pub fn cos(self) -> f64 { /// 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 `tan` from libc on Unix and + /// Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -663,6 +763,12 @@ pub fn tan(self) -> f64 { /// 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 `asin` from libc on Unix and + /// Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -686,6 +792,12 @@ pub fn asin(self) -> f64 { /// 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 `acos` from libc on Unix and + /// Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -708,6 +820,12 @@ pub fn acos(self) -> f64 { /// 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 `atan` from libc on Unix and + /// Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -734,6 +852,12 @@ pub fn atan(self) -> f64 { /// * `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 `atan2` from libc on Unix + /// and Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -764,6 +888,12 @@ pub fn atan2(self, other: f64) -> f64 { /// 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 `(f64::sin(x), + /// f64::cos(x))`. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -787,6 +917,12 @@ pub fn sin_cos(self) -> (f64, f64) { /// 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 `expm1` from libc on Unix + /// and Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -809,6 +945,12 @@ pub fn exp_m1(self) -> f64 { /// 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 `log1p` from libc on Unix + /// and Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -831,6 +973,12 @@ pub fn ln_1p(self) -> f64 { /// Hyperbolic sine function. /// + /// # Platform-specific precision + /// + /// The precision of this function varies by platform and Rust version. + /// This function currently corresponds to the `sinh` from libc on Unix + /// and Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -854,6 +1002,12 @@ pub fn sinh(self) -> f64 { /// Hyperbolic cosine function. /// + /// # Platform-specific precision + /// + /// The precision of this function varies by platform and Rust version. + /// This function currently corresponds to the `cosh` from libc on Unix + /// and Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -877,6 +1031,12 @@ pub fn cosh(self) -> f64 { /// Hyperbolic tangent function. /// + /// # Platform-specific precision + /// + /// The precision of this function varies by platform and Rust version. + /// This function currently corresponds to the `tanh` from libc on Unix + /// and Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -900,6 +1060,10 @@ pub fn tanh(self) -> f64 { /// Inverse hyperbolic sine function. /// + /// # Platform-specific precision + /// + /// The precision of this function varies by platform and Rust version. + /// /// # Examples /// /// ``` @@ -923,6 +1087,10 @@ pub fn asinh(self) -> f64 { /// Inverse hyperbolic cosine function. /// + /// # Platform-specific precision + /// + /// The precision of this function varies by platform and Rust version. + /// /// # Examples /// /// ``` @@ -948,6 +1116,10 @@ pub fn acosh(self) -> f64 { /// Inverse hyperbolic tangent function. /// + /// # Platform-specific precision + /// + /// The precision of this function varies by platform and Rust version. + /// /// # Examples /// /// ``` @@ -969,6 +1141,12 @@ pub fn atanh(self) -> f64 { /// Gamma function. /// + /// # Platform-specific precision + /// + /// The precision of this function varies by platform and Rust version. + /// This function currently corresponds to the `tgamma` from libc on Unix + /// and Windows. Note that this might change in the future. + /// /// # Examples /// /// ``` @@ -991,6 +1169,12 @@ pub fn gamma(self) -> f64 { /// /// 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 /// /// ```