mathieu/os-rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rollup merge of #118217 - tbu-:pr_floating_point, r=Amanieu

Browse source 
Document which methods on `f64` are precise
This commit is contained in:
Guillaume Gomez 2024-02-29 14:33:49 +01:00 • committed by GitHub
commit 0c2cb39f95
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 184 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

184
library/std/src/f64.rs
View file

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