f32.rs - source
Description: Source of the Rust file `library/std/src/num/f32.rs`.

#
std/num/
f32.rs

    1//! Constants for the `f32` single-precision floating point type.
    2//!
    3//! *[See also the `f32` primitive type](primitive@f32).*
    4//!
    5//! Mathematically significant numbers are provided in the `consts` sub-module.
    6//!
    7//! For the constants defined directly in this module
    8//! (as distinct from those defined in the `consts` sub-module),
    9//! new code should instead use the associated constants
    10//! defined directly on the `f32` type.
    11
    12#![stable(feature = "rust1", since = "1.0.0")]
    13#![allow(missing_docs)]
    14
    15#[stable(feature = "rust1", since = "1.0.0")]
    16#[allow(deprecated, deprecated_in_future)]
    17pub use core::f32::{
    18    DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_10_EXP, MIN_EXP,
    19    MIN_POSITIVE, NAN, NEG_INFINITY, RADIX, consts,
    20};
    21
    22#[cfg(not(test))]
    23use crate::intrinsics;
    24#[cfg(not(test))]
    25use crate::sys::cmath;
    26
    27#[cfg(not(test))]
    28impl f32 {
    29    /// Returns the largest integer less than or equal to `self`.
    30    ///
    31    /// This function always returns the precise result.
    32    ///
    33    /// # Examples
    34    ///
    35    /// ```
    36    /// let f = 3.7_f32;
    37    /// let g = 3.0_f32;
    38    /// let h = -3.7_f32;
    39    ///
    40    /// assert_eq!(f.floor(), 3.0);
    41    /// assert_eq!(g.floor(), 3.0);
    42    /// assert_eq!(h.floor(), -4.0);
    43    /// ```
    44    #[rustc_allow_incoherent_impl]
    45    #[must_use = "method returns a new number and does not mutate the original value"]
    46    #[stable(feature = "rust1", since = "1.0.0")]
    47    #[rustc_const_stable(feature = "const_float_round_methods", since = "1.90.0")]
    48    #[inline]
    49    pub const fn floor(self) -> f32 {
    50        core::f32::math::floor(self)
    51    }
    52
    53    /// Returns the smallest integer greater than or equal to `self`.
    54    ///
    55    /// This function always returns the precise result.
    56    ///
    57    /// # Examples
    58    ///
    59    /// ```
    60    /// let f = 3.01_f32;
    61    /// let g = 4.0_f32;
    62    ///
    63    /// assert_eq!(f.ceil(), 4.0);
    64    /// assert_eq!(g.ceil(), 4.0);
    65    /// ```
    66    #[doc(alias = "ceiling")]
    67    #[rustc_allow_incoherent_impl]
    68    #[must_use = "method returns a new number and does not mutate the original value"]
    69    #[stable(feature = "rust1", since = "1.0.0")]
    70    #[rustc_const_stable(feature = "const_float_round_methods", since = "1.90.0")]
    71    #[inline]
    72    pub const fn ceil(self) -> f32 {
    73        core::f32::math::ceil(self)
    74    }
    75
    76    /// Returns the nearest integer to `self`. If a value is half-way between two
    77    /// integers, round away from `0.0`.
    78    ///
    79    /// This function always returns the precise result.
    80    ///
    81    /// # Examples
    82    ///
    83    /// ```
    84    /// let f = 3.3_f32;
    85    /// let g = -3.3_f32;
    86    /// let h = -3.7_f32;
    87    /// let i = 3.5_f32;
    88    /// let j = 4.5_f32;
    89    ///
    90    /// assert_eq!(f.round(), 3.0);
    91    /// assert_eq!(g.round(), -3.0);
    92    /// assert_eq!(h.round(), -4.0);
    93    /// assert_eq!(i.round(), 4.0);
    94    /// assert_eq!(j.round(), 5.0);
    95    /// ```
    96    #[rustc_allow_incoherent_impl]
    97    #[must_use = "method returns a new number and does not mutate the original value"]
    98    #[stable(feature = "rust1", since = "1.0.0")]
    99    #[rustc_const_stable(feature = "const_float_round_methods", since = "1.90.0")]
    100    #[inline]
    101    pub const fn round(self) -> f32 {
    102        core::f32::math::round(self)
    103    }
    104
    105    /// Returns the nearest integer to a number. Rounds half-way cases to the number
    106    /// with an even least significant digit.
    107    ///
    108    /// This function always returns the precise result.
    109    ///
    110    /// # Examples
    111    ///
    112    /// ```
    113    /// let f = 3.3_f32;
    114    /// let g = -3.3_f32;
    115    /// let h = 3.5_f32;
    116    /// let i = 4.5_f32;
    117    ///
    118    /// assert_eq!(f.round_ties_even(), 3.0);
    119    /// assert_eq!(g.round_ties_even(), -3.0);
    120    /// assert_eq!(h.round_ties_even(), 4.0);
    121    /// assert_eq!(i.round_ties_even(), 4.0);
    122    /// ```
    123    #[rustc_allow_incoherent_impl]
    124    #[must_use = "method returns a new number and does not mutate the original value"]
    125    #[stable(feature = "round_ties_even", since = "1.77.0")]
    126    #[rustc_const_stable(feature = "const_float_round_methods", since = "1.90.0")]
    127    #[inline]
    128    pub const fn round_ties_even(self) -> f32 {
    129        core::f32::math::round_ties_even(self)
    130    }
    131
    132    /// Returns the integer part of `self`.
    133    /// This means that non-integer numbers are always truncated towards zero.
    134    ///
    135    /// This function always returns the precise result.
    136    ///
    137    /// # Examples
    138    ///
    139    /// ```
    140    /// let f = 3.7_f32;
    141    /// let g = 3.0_f32;
    142    /// let h = -3.7_f32;
    143    ///
    144    /// assert_eq!(f.trunc(), 3.0);
    145    /// assert_eq!(g.trunc(), 3.0);
    146    /// assert_eq!(h.trunc(), -3.0);
    147    /// ```
    148    #[doc(alias = "truncate")]
    149    #[rustc_allow_incoherent_impl]
    150    #[must_use = "method returns a new number and does not mutate the original value"]
    151    #[stable(feature = "rust1", since = "1.0.0")]
    152    #[rustc_const_stable(feature = "const_float_round_methods", since = "1.90.0")]
    153    #[inline]
    154    pub const fn trunc(self) -> f32 {
    155        core::f32::math::trunc(self)
    156    }
    157
    158    /// Returns the fractional part of `self`.
    159    ///
    160    /// This function always returns the precise result.
    161    ///
    162    /// # Examples
    163    ///
    164    /// ```
    165    /// let x = 3.6_f32;
    166    /// let y = -3.6_f32;
    167    /// let abs_difference_x = (x.fract() - 0.6).abs();
    168    /// let abs_difference_y = (y.fract() - (-0.6)).abs();
    169    ///
    170    /// assert!(abs_difference_x <= f32::EPSILON);
    171    /// assert!(abs_difference_y <= f32::EPSILON);
    172    /// ```
    173    #[rustc_allow_incoherent_impl]
    174    #[must_use = "method returns a new number and does not mutate the original value"]
    175    #[stable(feature = "rust1", since = "1.0.0")]
    176    #[rustc_const_stable(feature = "const_float_round_methods", since = "1.90.0")]
    177    #[inline]
    178    pub const fn fract(self) -> f32 {
    179        core::f32::math::fract(self)
    180    }
    181
    182    /// Fused multiply-add. Computes `(self * a) + b` with only one rounding
    183    /// error, yielding a more accurate result than an unfused multiply-add.
    184    ///
    185    /// Using `mul_add` *may* be more performant than an unfused multiply-add if
    186    /// the target architecture has a dedicated `fma` CPU instruction. However,
    187    /// this is not always true, and will be heavily dependant on designing
    188    /// algorithms with specific target hardware in mind.
    189    ///
    190    /// # Precision
    191    ///
    192    /// The result of this operation is guaranteed to be the rounded
    193    /// infinite-precision result. It is specified by IEEE 754 as
    194    /// `fusedMultiplyAdd` and guaranteed not to change.
    195    ///
    196    /// # Examples
    197    ///
    198    /// ```
    199    /// let m = 10.0_f32;
    200    /// let x = 4.0_f32;
    201    /// let b = 60.0_f32;
    202    ///
    203    /// assert_eq!(m.mul_add(x, b), 100.0);
    204    /// assert_eq!(m * x + b, 100.0);
    205    ///
    206    /// let one_plus_eps = 1.0_f32 + f32::EPSILON;
    207    /// let one_minus_eps = 1.0_f32 - f32::EPSILON;
    208    /// let minus_one = -1.0_f32;
    209    ///
    210    /// // The exact result (1 + eps) * (1 - eps) = 1 - eps * eps.
    211    /// assert_eq!(one_plus_eps.mul_add(one_minus_eps, minus_one), -f32::EPSILON * f32::EPSILON);
    212    /// // Different rounding with the non-fused multiply and add.
    213    /// assert_eq!(one_plus_eps * one_minus_eps + minus_one, 0.0);
    214    /// ```
    215    #[rustc_allow_incoherent_impl]
    216    #[doc(alias = "fmaf", alias = "fusedMultiplyAdd")]
    217    #[must_use = "method returns a new number and does not mutate the original value"]
    218    #[stable(feature = "rust1", since = "1.0.0")]
    219    #[inline]
    220    #[rustc_const_stable(feature = "const_mul_add", since = "1.94.0")]
    221    pub const fn mul_add(self, a: f32, b: f32) -> f32 {
    222        core::f32::math::mul_add(self, a, b)
    223    }
    224
    225    /// Calculates Euclidean division, the matching method for `rem_euclid`.
    226    ///
    227    /// This computes the integer `n` such that
    228    /// `self = n * rhs + self.rem_euclid(rhs)`.
    229    /// In other words, the result is `self / rhs` rounded to the integer `n`
    230    /// such that `self >= n * rhs`.
    231    ///
    232    /// # Precision
    233    ///
    234    /// The result of this operation is guaranteed to be the rounded
    235    /// infinite-precision result.
    236    ///
    237    /// # Examples
    238    ///
    239    /// ```
    240    /// let a: f32 = 7.0;
    241    /// let b = 4.0;
    242    /// assert_eq!(a.div_euclid(b), 1.0); // 7.0 > 4.0 * 1.0
    243    /// assert_eq!((-a).div_euclid(b), -2.0); // -7.0 >= 4.0 * -2.0
    244    /// assert_eq!(a.div_euclid(-b), -1.0); // 7.0 >= -4.0 * -1.0
    245    /// assert_eq!((-a).div_euclid(-b), 2.0); // -7.0 >= -4.0 * 2.0
    246    /// ```
    247    #[rustc_allow_incoherent_impl]
    248    #[must_use = "method returns a new number and does not mutate the original value"]
    249    #[inline]
    250    #[stable(feature = "euclidean_division", since = "1.38.0")]
    251    pub fn div_euclid(self, rhs: f32) -> f32 {
    252        core::f32::math::div_euclid(self, rhs)
    253    }
    254
    255    /// Calculates the least nonnegative remainder of `self` when divided by
    256    /// `rhs`.
    257    ///
    258    /// In particular, the return value `r` satisfies `0.0 <= r < rhs.abs()` in
    259    /// most cases. However, due to a floating point round-off error it can
    260    /// result in `r == rhs.abs()`, violating the mathematical definition, if
    261    /// `self` is much smaller than `rhs.abs()` in magnitude and `self < 0.0`.
    262    /// This result is not an element of the function's codomain, but it is the
    263    /// closest floating point number in the real numbers and thus fulfills the
    264    /// property `self == self.div_euclid(rhs) * rhs + self.rem_euclid(rhs)`
    265    /// approximately.
    266    ///
    267    /// # Precision
    268    ///
    269    /// The result of this operation is guaranteed to be the rounded
    270    /// infinite-precision result.
    271    ///
    272    /// # Examples
    273    ///
    274    /// ```
    275    /// let a: f32 = 7.0;
    276    /// let b = 4.0;
    277    /// assert_eq!(a.rem_euclid(b), 3.0);
    278    /// assert_eq!((-a).rem_euclid(b), 1.0);
    279    /// assert_eq!(a.rem_euclid(-b), 3.0);
    280    /// assert_eq!((-a).rem_euclid(-b), 1.0);
    281    /// // limitation due to round-off error
    282    /// assert!((-f32::EPSILON).rem_euclid(3.0) != 0.0);
    283    /// ```
    284    #[doc(alias = "modulo", alias = "mod")]
    285    #[rustc_allow_incoherent_impl]
    286    #[must_use = "method returns a new number and does not mutate the original value"]
    287    #[inline]
    288    #[stable(feature = "euclidean_division", since = "1.38.0")]
    289    pub fn rem_euclid(self, rhs: f32) -> f32 {
    290        core::f32::math::rem_euclid(self, rhs)
    291    }
    292
    293    /// Raises a number to an integer power.
    294    ///
    295    /// Using this function is generally faster than using `powf`.
    296    /// It might have a different sequence of rounding operations than `powf`,
    297    /// so the results are not guaranteed to agree.
    298    ///
    299    /// Note that this function is special in that it can return non-NaN results for NaN inputs. For
    300    /// example, `f32::powi(f32::NAN, 0)` returns `1.0`. However, if an input is a *signaling*
    301    /// NaN, then the result is non-deterministically either a NaN or the result that the
    302    /// corresponding quiet NaN would produce.
    303    ///
    304    /// # Unspecified precision
    305    ///
    306    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    307    /// can even differ within the same execution from one invocation to the next.
    308    ///
    309    /// # Examples
    310    ///
    311    /// ```
    312    /// let x = 2.0_f32;
    313    /// let abs_difference = (x.powi(2) - (x * x)).abs();
    314    /// assert!(abs_difference <= 1e-5);
    315    ///
    316    /// assert_eq!(f32::powi(f32::NAN, 0), 1.0);
    317    /// assert_eq!(f32::powi(0.0, 0), 1.0);
    318    /// ```
    319    #[rustc_allow_incoherent_impl]
    320    #[must_use = "method returns a new number and does not mutate the original value"]
    321    #[stable(feature = "rust1", since = "1.0.0")]
    322    #[inline]
    323    pub fn powi(self, n: i32) -> f32 {
    324        core::f32::math::powi(self, n)
    325    }
    326
    327    /// Raises a number to a floating point power.
    328    ///
    329    /// Note that this function is special in that it can return non-NaN results for NaN inputs. For
    330    /// example, `f32::powf(f32::NAN, 0.0)` returns `1.0`. However, if an input is a *signaling*
    331    /// NaN, then the result is non-deterministically either a NaN or the result that the
    332    /// corresponding quiet NaN would produce.
    333    ///
    334    /// # Unspecified precision
    335    ///
    336    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    337    /// can even differ within the same execution from one invocation to the next.
    338    ///
    339    /// # Examples
    340    ///
    341    /// ```
    342    /// let x = 2.0_f32;
    343    /// let abs_difference = (x.powf(2.0) - (x * x)).abs();
    344    /// assert!(abs_difference <= 1e-5);
    345    ///
    346    /// assert_eq!(f32::powf(1.0, f32::NAN), 1.0);
    347    /// assert_eq!(f32::powf(f32::NAN, 0.0), 1.0);
    348    /// assert_eq!(f32::powf(0.0, 0.0), 1.0);
    349    /// ```
    350    #[rustc_allow_incoherent_impl]
    351    #[must_use = "method returns a new number and does not mutate the original value"]
    352    #[stable(feature = "rust1", since = "1.0.0")]
    353    #[inline]
    354    pub fn powf(self, n: f32) -> f32 {
    355        intrinsics::powf32(self, n)
    356    }
    357
    358    /// Returns the square root of a number.
    359    ///
    360    /// Returns NaN if `self` is a negative number other than `-0.0`.
    361    ///
    362    /// # Precision
    363    ///
    364    /// The result of this operation is guaranteed to be the rounded
    365    /// infinite-precision result. It is specified by IEEE 754 as `squareRoot`
    366    /// and guaranteed not to change.
    367    ///
    368    /// # Examples
    369    ///
    370    /// ```
    371    /// let positive = 4.0_f32;
    372    /// let negative = -4.0_f32;
    373    /// let negative_zero = -0.0_f32;
    374    ///
    375    /// assert_eq!(positive.sqrt(), 2.0);
    376    /// assert!(negative.sqrt().is_nan());
    377    /// assert!(negative_zero.sqrt() == negative_zero);
    378    /// ```
    379    #[doc(alias = "squareRoot")]
    380    #[rustc_allow_incoherent_impl]
    381    #[must_use = "method returns a new number and does not mutate the original value"]
    382    #[stable(feature = "rust1", since = "1.0.0")]
    383    #[inline]
    384    pub fn sqrt(self) -> f32 {
    385        core::f32::math::sqrt(self)
    386    }
    387
    388    /// Returns `e^(self)`, (the exponential function).
    389    ///
    390    /// # Unspecified precision
    391    ///
    392    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    393    /// can even differ within the same execution from one invocation to the next.
    394    ///
    395    /// # Examples
    396    ///
    397    /// ```
    398    /// let one = 1.0f32;
    399    /// // e^1
    400    /// let e = one.exp();
    401    ///
    402    /// // ln(e) - 1 == 0
    403    /// let abs_difference = (e.ln() - 1.0).abs();
    404    ///
    405    /// assert!(abs_difference <= 1e-6);
    406    /// ```
    407    #[rustc_allow_incoherent_impl]
    408    #[must_use = "method returns a new number and does not mutate the original value"]
    409    #[stable(feature = "rust1", since = "1.0.0")]
    410    #[inline]
    411    pub fn exp(self) -> f32 {
    412        intrinsics::expf32(self)
    413    }
    414
    415    /// Returns `2^(self)`.
    416    ///
    417    /// # Unspecified precision
    418    ///
    419    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    420    /// can even differ within the same execution from one invocation to the next.
    421    ///
    422    /// # Examples
    423    ///
    424    /// ```
    425    /// let f = 2.0f32;
    426    ///
    427    /// // 2^2 - 4 == 0
    428    /// let abs_difference = (f.exp2() - 4.0).abs();
    429    ///
    430    /// assert!(abs_difference <= 1e-5);
    431    /// ```
    432    #[rustc_allow_incoherent_impl]
    433    #[must_use = "method returns a new number and does not mutate the original value"]
    434    #[stable(feature = "rust1", since = "1.0.0")]
    435    #[inline]
    436    pub fn exp2(self) -> f32 {
    437        intrinsics::exp2f32(self)
    438    }
    439
    440    /// Returns the natural logarithm of the number.
    441    ///
    442    /// This returns NaN when the number is negative, and negative infinity when number is zero.
    443    ///
    444    /// # Unspecified precision
    445    ///
    446    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    447    /// can even differ within the same execution from one invocation to the next.
    448    ///
    449    /// # Examples
    450    ///
    451    /// ```
    452    /// let one = 1.0f32;
    453    /// // e^1
    454    /// let e = one.exp();
    455    ///
    456    /// // ln(e) - 1 == 0
    457    /// let abs_difference = (e.ln() - 1.0).abs();
    458    ///
    459    /// assert!(abs_difference <= 1e-6);
    460    /// ```
    461    ///
    462    /// Non-positive values:
    463    /// ```
    464    /// assert_eq!(0_f32.ln(), f32::NEG_INFINITY);
    465    /// assert!((-42_f32).ln().is_nan());
    466    /// ```
    467    #[rustc_allow_incoherent_impl]
    468    #[must_use = "method returns a new number and does not mutate the original value"]
    469    #[stable(feature = "rust1", since = "1.0.0")]
    470    #[inline]
    471    pub fn ln(self) -> f32 {
    472        intrinsics::logf32(self)
    473    }
    474
    475    /// Returns the logarithm of the number with respect to an arbitrary base.
    476    ///
    477    /// This returns NaN when the number is negative, and negative infinity when number is zero.
    478    ///
    479    /// The result might not be correctly rounded owing to implementation details;
    480    /// `self.log2()` can produce more accurate results for base 2, and
    481    /// `self.log10()` can produce more accurate results for base 10.
    482    ///
    483    /// # Unspecified precision
    484    ///
    485    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    486    /// can even differ within the same execution from one invocation to the next.
    487    ///
    488    /// # Examples
    489    ///
    490    /// ```
    491    /// let five = 5.0f32;
    492    ///
    493    /// // log5(5) - 1 == 0
    494    /// let abs_difference = (five.log(5.0) - 1.0).abs();
    495    ///
    496    /// assert!(abs_difference <= 1e-6);
    497    /// ```
    498    ///
    499    /// Non-positive values:
    500    /// ```
    501    /// assert_eq!(0_f32.log(10.0), f32::NEG_INFINITY);
    502    /// assert!((-42_f32).log(10.0).is_nan());
    503    /// ```
    504    #[rustc_allow_incoherent_impl]
    505    #[must_use = "method returns a new number and does not mutate the original value"]
    506    #[stable(feature = "rust1", since = "1.0.0")]
    507    #[inline]
    508    pub fn log(self, base: f32) -> f32 {
    509        self.ln() / base.ln()
    510    }
    511
    512    /// Returns the base 2 logarithm of the number.
    513    ///
    514    /// This returns NaN when the number is negative, and negative infinity when number is zero.
    515    ///
    516    /// # Unspecified precision
    517    ///
    518    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    519    /// can even differ within the same execution from one invocation to the next.
    520    ///
    521    /// # Examples
    522    ///
    523    /// ```
    524    /// let two = 2.0f32;
    525    ///
    526    /// // log2(2) - 1 == 0
    527    /// let abs_difference = (two.log2() - 1.0).abs();
    528    ///
    529    /// assert!(abs_difference <= 1e-6);
    530    /// ```
    531    ///
    532    /// Non-positive values:
    533    /// ```
    534    /// assert_eq!(0_f32.log2(), f32::NEG_INFINITY);
    535    /// assert!((-42_f32).log2().is_nan());
    536    /// ```
    537    #[rustc_allow_incoherent_impl]
    538    #[must_use = "method returns a new number and does not mutate the original value"]
    539    #[stable(feature = "rust1", since = "1.0.0")]
    540    #[inline]
    541    pub fn log2(self) -> f32 {
    542        intrinsics::log2f32(self)
    543    }
    544
    545    /// Returns the base 10 logarithm of the number.
    546    ///
    547    /// This returns NaN when the number is negative, and negative infinity when number is zero.
    548    ///
    549    /// # Unspecified precision
    550    ///
    551    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    552    /// can even differ within the same execution from one invocation to the next.
    553    ///
    554    /// # Examples
    555    ///
    556    /// ```
    557    /// let ten = 10.0f32;
    558    ///
    559    /// // log10(10) - 1 == 0
    560    /// let abs_difference = (ten.log10() - 1.0).abs();
    561    ///
    562    /// assert!(abs_difference <= 1e-6);
    563    /// ```
    564    ///
    565    /// Non-positive values:
    566    /// ```
    567    /// assert_eq!(0_f32.log10(), f32::NEG_INFINITY);
    568    /// assert!((-42_f32).log10().is_nan());
    569    /// ```
    570    #[rustc_allow_incoherent_impl]
    571    #[must_use = "method returns a new number and does not mutate the original value"]
    572    #[stable(feature = "rust1", since = "1.0.0")]
    573    #[inline]
    574    pub fn log10(self) -> f32 {
    575        intrinsics::log10f32(self)
    576    }
    577
    578    /// The positive difference of two numbers.
    579    ///
    580    /// * If `self <= other`: `0.0`
    581    /// * Else: `self - other`
    582    ///
    583    /// # Unspecified precision
    584    ///
    585    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    586    /// can even differ within the same execution from one invocation to the next.
    587    /// This function currently corresponds to the `fdimf` from libc on Unix
    588    /// and Windows. Note that this might change in the future.
    589    ///
    590    /// # Examples
    591    ///
    592    /// ```
    593    /// let x = 3.0f32;
    594    /// let y = -3.0f32;
    595    ///
    596    /// let abs_difference_x = (x.abs_sub(1.0) - 2.0).abs();
    597    /// let abs_difference_y = (y.abs_sub(1.0) - 0.0).abs();
    598    ///
    599    /// assert!(abs_difference_x <= 1e-6);
    600    /// assert!(abs_difference_y <= 1e-6);
    601    /// ```
    602    #[rustc_allow_incoherent_impl]
    603    #[must_use = "method returns a new number and does not mutate the original value"]
    604    #[stable(feature = "rust1", since = "1.0.0")]
    605    #[inline]
    606    #[deprecated(
    607        since = "1.10.0",
    608        note = "you probably meant `(self - other).abs()`: \
    609                this operation is `(self - other).max(0.0)` \
    610                except that `abs_sub` also propagates NaNs (also \
    611                known as `fdimf` in C). If you truly need the positive \
    612                difference, consider using that expression or the C function \
    613                `fdimf`, depending on how you wish to handle NaN (please consider \
    614                filing an issue describing your use-case too)."
    615    )]
    616    pub fn abs_sub(self, other: f32) -> f32 {
    617        #[allow(deprecated)]
    618        core::f32::math::abs_sub(self, other)
    619    }
    620
    621    /// Returns the cube root of a number.
    622    ///
    623    /// # Unspecified precision
    624    ///
    625    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    626    /// can even differ within the same execution from one invocation to the next.
    627    /// This function currently corresponds to the `cbrtf` from libc on Unix
    628    /// and Windows. Note that this might change in the future.
    629    ///
    630    /// # Examples
    631    ///
    632    /// ```
    633    /// let x = 8.0f32;
    634    ///
    635    /// // x^(1/3) - 2 == 0
    636    /// let abs_difference = (x.cbrt() - 2.0).abs();
    637    ///
    638    /// assert!(abs_difference <= 1e-6);
    639    /// ```
    640    #[rustc_allow_incoherent_impl]
    641    #[must_use = "method returns a new number and does not mutate the original value"]
    642    #[stable(feature = "rust1", since = "1.0.0")]
    643    #[inline]
    644    pub fn cbrt(self) -> f32 {
    645        core::f32::math::cbrt(self)
    646    }
    647
    648    /// Compute the distance between the origin and a point (`x`, `y`) on the
    649    /// Euclidean plane. Equivalently, compute the length of the hypotenuse of a
    650    /// right-angle triangle with other sides having length `x.abs()` and
    651    /// `y.abs()`.
    652    ///
    653    /// # Unspecified precision
    654    ///
    655    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    656    /// can even differ within the same execution from one invocation to the next.
    657    /// This function currently corresponds to the `hypotf` from libc on Unix
    658    /// and Windows. Note that this might change in the future.
    659    ///
    660    /// # Examples
    661    ///
    662    /// ```
    663    /// let x = 2.0f32;
    664    /// let y = 3.0f32;
    665    ///
    666    /// // sqrt(x^2 + y^2)
    667    /// let abs_difference = (x.hypot(y) - (x.powi(2) + y.powi(2)).sqrt()).abs();
    668    ///
    669    /// assert!(abs_difference <= 1e-5);
    670    /// ```
    671    #[rustc_allow_incoherent_impl]
    672    #[must_use = "method returns a new number and does not mutate the original value"]
    673    #[stable(feature = "rust1", since = "1.0.0")]
    674    #[inline]
    675    pub fn hypot(self, other: f32) -> f32 {
    676        cmath::hypotf(self, other)
    677    }
    678
    679    /// Computes the sine of a number (in radians).
    680    ///
    681    /// # Unspecified precision
    682    ///
    683    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    684    /// can even differ within the same execution from one invocation to the next.
    685    ///
    686    /// # Examples
    687    ///
    688    /// ```
    689    /// let x = std::f32::consts::FRAC_PI_2;
    690    ///
    691    /// let abs_difference = (x.sin() - 1.0).abs();
    692    ///
    693    /// assert!(abs_difference <= 1e-6);
    694    /// ```
    695    #[rustc_allow_incoherent_impl]
    696    #[must_use = "method returns a new number and does not mutate the original value"]
    697    #[stable(feature = "rust1", since = "1.0.0")]
    698    #[inline]
    699    pub fn sin(self) -> f32 {
    700        intrinsics::sinf32(self)
    701    }
    702
    703    /// Computes the cosine of a number (in radians).
    704    ///
    705    /// # Unspecified precision
    706    ///
    707    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    708    /// can even differ within the same execution from one invocation to the next.
    709    ///
    710    /// # Examples
    711    ///
    712    /// ```
    713    /// let x = 2.0 * std::f32::consts::PI;
    714    ///
    715    /// let abs_difference = (x.cos() - 1.0).abs();
    716    ///
    717    /// assert!(abs_difference <= 1e-6);
    718    /// ```
    719    #[rustc_allow_incoherent_impl]
    720    #[must_use = "method returns a new number and does not mutate the original value"]
    721    #[stable(feature = "rust1", since = "1.0.0")]
    722    #[inline]
    723    pub fn cos(self) -> f32 {
    724        intrinsics::cosf32(self)
    725    }
    726
    727    /// Computes the tangent of a number (in radians).
    728    ///
    729    /// # Unspecified precision
    730    ///
    731    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    732    /// can even differ within the same execution from one invocation to the next.
    733    /// This function currently corresponds to the `tanf` from libc on Unix and
    734    /// Windows. Note that this might change in the future.
    735    ///
    736    /// # Examples
    737    ///
    738    /// ```
    739    /// let x = std::f32::consts::FRAC_PI_4;
    740    /// let abs_difference = (x.tan() - 1.0).abs();
    741    ///
    742    /// assert!(abs_difference <= 1e-6);
    743    /// ```
    744    #[rustc_allow_incoherent_impl]
    745    #[must_use = "method returns a new number and does not mutate the original value"]
    746    #[stable(feature = "rust1", since = "1.0.0")]
    747    #[inline]
    748    pub fn tan(self) -> f32 {
    749        cmath::tanf(self)
    750    }
    751
    752    /// Computes the arcsine of a number. Return value is in radians in
    753    /// the range [-pi/2, pi/2] or NaN if the number is outside the range
    754    /// [-1, 1].
    755    ///
    756    /// # Unspecified precision
    757    ///
    758    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    759    /// can even differ within the same execution from one invocation to the next.
    760    /// This function currently corresponds to the `asinf` from libc on Unix
    761    /// and Windows. Note that this might change in the future.
    762    ///
    763    /// # Examples
    764    ///
    765    /// ```
    766    /// let f = std::f32::consts::FRAC_PI_4;
    767    ///
    768    /// // asin(sin(pi/2))
    769    /// let abs_difference = (f.sin().asin() - f).abs();
    770    ///
    771    /// assert!(abs_difference <= 1e-6);
    772    /// ```
    773    #[doc(alias = "arcsin")]
    774    #[rustc_allow_incoherent_impl]
    775    #[must_use = "method returns a new number and does not mutate the original value"]
    776    #[stable(feature = "rust1", since = "1.0.0")]
    777    #[inline]
    778    pub fn asin(self) -> f32 {
    779        cmath::asinf(self)
    780    }
    781
    782    /// Computes the arccosine of a number. Return value is in radians in
    783    /// the range [0, pi] or NaN if the number is outside the range
    784    /// [-1, 1].
    785    ///
    786    /// # Unspecified precision
    787    ///
    788    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    789    /// can even differ within the same execution from one invocation to the next.
    790    /// This function currently corresponds to the `acosf` from libc on Unix
    791    /// and Windows. Note that this might change in the future.
    792    ///
    793    /// # Examples
    794    ///
    795    /// ```
    796    /// let f = std::f32::consts::FRAC_PI_4;
    797    ///
    798    /// // acos(cos(pi/4))
    799    /// let abs_difference = (f.cos().acos() - std::f32::consts::FRAC_PI_4).abs();
    800    ///
    801    /// assert!(abs_difference <= 1e-6);
    802    /// ```
    803    #[doc(alias = "arccos")]
    804    #[rustc_allow_incoherent_impl]
    805    #[must_use = "method returns a new number and does not mutate the original value"]
    806    #[stable(feature = "rust1", since = "1.0.0")]
    807    #[inline]
    808    pub fn acos(self) -> f32 {
    809        cmath::acosf(self)
    810    }
    811
    812    /// Computes the arctangent of a number. Return value is in radians in the
    813    /// range [-pi/2, pi/2];
    814    ///
    815    /// # Unspecified precision
    816    ///
    817    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    818    /// can even differ within the same execution from one invocation to the next.
    819    /// This function currently corresponds to the `atanf` from libc on Unix
    820    /// and Windows. Note that this might change in the future.
    821    ///
    822    /// # Examples
    823    ///
    824    /// ```
    825    /// let f = 1.0f32;
    826    ///
    827    /// // atan(tan(1))
    828    /// let abs_difference = (f.tan().atan() - 1.0).abs();
    829    ///
    830    /// assert!(abs_difference <= 1e-6);
    831    /// ```
    832    #[doc(alias = "arctan")]
    833    #[rustc_allow_incoherent_impl]
    834    #[must_use = "method returns a new number and does not mutate the original value"]
    835    #[stable(feature = "rust1", since = "1.0.0")]
    836    #[inline]
    837    pub fn atan(self) -> f32 {
    838        cmath::atanf(self)
    839    }
    840
    841    /// Computes the four quadrant arctangent of `self` (`y`) and `other` (`x`) in radians.
    842    ///
    843    ///  | `x`     | `y`     | Piecewise Definition | Range         |
    844    ///  |---------|---------|----------------------|---------------|
    845    ///  | `>= +0` | `>= +0` | `arctan(y/x)`        | `[+0, +pi/2]` |
    846    ///  | `>= +0` | `<= -0` | `arctan(y/x)`        | `[-pi/2, -0]` |
    847    ///  | `<= -0` | `>= +0` | `arctan(y/x) + pi`   | `[+pi/2, +pi]`|
    848    ///  | `<= -0` | `<= -0` | `arctan(y/x) - pi`   | `[-pi, -pi/2]`|
    849    ///
    850    /// # Unspecified precision
    851    ///
    852    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    853    /// can even differ within the same execution from one invocation to the next.
    854    /// This function currently corresponds to the `atan2f` from libc on Unix
    855    /// and Windows. Note that this might change in the future.
    856    ///
    857    /// # Examples
    858    ///
    859    /// ```
    860    /// // Positive angles measured counter-clockwise
    861    /// // from positive x axis
    862    /// // -pi/4 radians (45 deg clockwise)
    863    /// let x1 = 3.0f32;
    864    /// let y1 = -3.0f32;
    865    ///
    866    /// // 3pi/4 radians (135 deg counter-clockwise)
    867    /// let x2 = -3.0f32;
    868    /// let y2 = 3.0f32;
    869    ///
    870    /// let abs_difference_1 = (y1.atan2(x1) - (-std::f32::consts::FRAC_PI_4)).abs();
    871    /// let abs_difference_2 = (y2.atan2(x2) - (3.0 * std::f32::consts::FRAC_PI_4)).abs();
    872    ///
    873    /// assert!(abs_difference_1 <= 1e-5);
    874    /// assert!(abs_difference_2 <= 1e-5);
    875    /// ```
    876    #[rustc_allow_incoherent_impl]
    877    #[must_use = "method returns a new number and does not mutate the original value"]
    878    #[stable(feature = "rust1", since = "1.0.0")]
    879    #[inline]
    880    pub fn atan2(self, other: f32) -> f32 {
    881        cmath::atan2f(self, other)
    882    }
    883
    884    /// Simultaneously computes the sine and cosine of the number, `x`. Returns
    885    /// `(sin(x), cos(x))`.
    886    ///
    887    /// # Unspecified precision
    888    ///
    889    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    890    /// can even differ within the same execution from one invocation to the next.
    891    /// This function currently corresponds to the `(f32::sin(x),
    892    /// f32::cos(x))`. Note that this might change in the future.
    893    ///
    894    /// # Examples
    895    ///
    896    /// ```
    897    /// let x = std::f32::consts::FRAC_PI_4;
    898    /// let f = x.sin_cos();
    899    ///
    900    /// let abs_difference_0 = (f.0 - x.sin()).abs();
    901    /// let abs_difference_1 = (f.1 - x.cos()).abs();
    902    ///
    903    /// assert!(abs_difference_0 <= 1e-4);
    904    /// assert!(abs_difference_1 <= 1e-4);
    905    /// ```
    906    #[doc(alias = "sincos")]
    907    #[rustc_allow_incoherent_impl]
    908    #[stable(feature = "rust1", since = "1.0.0")]
    909    #[inline]
    910    pub fn sin_cos(self) -> (f32, f32) {
    911        (self.sin(), self.cos())
    912    }
    913
    914    /// Returns `e^(self) - 1` in a way that is accurate even if the
    915    /// number is close to zero.
    916    ///
    917    /// # Unspecified precision
    918    ///
    919    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    920    /// can even differ within the same execution from one invocation to the next.
    921    /// This function currently corresponds to the `expm1f` from libc on Unix
    922    /// and Windows. Note that this might change in the future.
    923    ///
    924    /// # Examples
    925    ///
    926    /// ```
    927    /// let x = 1e-8_f32;
    928    ///
    929    /// // for very small x, e^x is approximately 1 + x + x^2 / 2
    930    /// let approx = x + x * x / 2.0;
    931    /// let abs_difference = (x.exp_m1() - approx).abs();
    932    ///
    933    /// assert!(abs_difference < 1e-10);
    934    /// ```
    935    #[rustc_allow_incoherent_impl]
    936    #[must_use = "method returns a new number and does not mutate the original value"]
    937    #[stable(feature = "rust1", since = "1.0.0")]
    938    #[inline]
    939    pub fn exp_m1(self) -> f32 {
    940        cmath::expm1f(self)
    941    }
    942
    943    /// Returns `ln(1+n)` (natural logarithm) more accurately than if
    944    /// the operations were performed separately.
    945    ///
    946    /// This returns NaN when `n < -1.0`, and negative infinity when `n == -1.0`.
    947    ///
    948    /// # Unspecified precision
    949    ///
    950    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    951    /// can even differ within the same execution from one invocation to the next.
    952    /// This function currently corresponds to the `log1pf` from libc on Unix
    953    /// and Windows. Note that this might change in the future.
    954    ///
    955    /// # Examples
    956    ///
    957    /// ```
    958    /// let x = 1e-8_f32;
    959    ///
    960    /// // for very small x, ln(1 + x) is approximately x - x^2 / 2
    961    /// let approx = x - x * x / 2.0;
    962    /// let abs_difference = (x.ln_1p() - approx).abs();
    963    ///
    964    /// assert!(abs_difference < 1e-10);
    965    /// ```
    966    ///
    967    /// Out-of-range values:
    968    /// ```
    969    /// assert_eq!((-1.0_f32).ln_1p(), f32::NEG_INFINITY);
    970    /// assert!((-2.0_f32).ln_1p().is_nan());
    971    /// ```
    972    #[doc(alias = "log1p")]
    973    #[rustc_allow_incoherent_impl]
    974    #[must_use = "method returns a new number and does not mutate the original value"]
    975    #[stable(feature = "rust1", since = "1.0.0")]
    976    #[inline]
    977    pub fn ln_1p(self) -> f32 {
    978        cmath::log1pf(self)
    979    }
    980
    981    /// Hyperbolic sine function.
    982    ///
    983    /// # Unspecified precision
    984    ///
    985    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    986    /// can even differ within the same execution from one invocation to the next.
    987    /// This function currently corresponds to the `sinhf` from libc on Unix
    988    /// and Windows. Note that this might change in the future.
    989    ///
    990    /// # Examples
    991    ///
    992    /// ```
    993    /// let e = std::f32::consts::E;
    994    /// let x = 1.0f32;
    995    ///
    996    /// let f = x.sinh();
    997    /// // Solving sinh() at 1 gives `(e^2-1)/(2e)`
    998    /// let g = ((e * e) - 1.0) / (2.0 * e);
    999    /// let abs_difference = (f - g).abs();
    1000    ///
    1001    /// assert!(abs_difference <= 1e-6);
    1002    /// ```
    1003    #[rustc_allow_incoherent_impl]
    1004    #[must_use = "method returns a new number and does not mutate the original value"]
    1005    #[stable(feature = "rust1", since = "1.0.0")]
    1006    #[inline]
    1007    pub fn sinh(self) -> f32 {
    1008        cmath::sinhf(self)
    1009    }
    1010
    1011    /// Hyperbolic cosine function.
    1012    ///
    1013    /// # Unspecified precision
    1014    ///
    1015    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    1016    /// can even differ within the same execution from one invocation to the next.
    1017    /// This function currently corresponds to the `coshf` from libc on Unix
    1018    /// and Windows. Note that this might change in the future.
    1019    ///
    1020    /// # Examples
    1021    ///
    1022    /// ```
    1023    /// let e = std::f32::consts::E;
    1024    /// let x = 1.0f32;
    1025    /// let f = x.cosh();
    1026    /// // Solving cosh() at 1 gives this result
    1027    /// let g = ((e * e) + 1.0) / (2.0 * e);
    1028    /// let abs_difference = (f - g).abs();
    1029    ///
    1030    /// // Same result
    1031    /// assert!(abs_difference <= 1e-6);
    1032    /// ```
    1033    #[rustc_allow_incoherent_impl]
    1034    #[must_use = "method returns a new number and does not mutate the original value"]
    1035    #[stable(feature = "rust1", since = "1.0.0")]
    1036    #[inline]
    1037    pub fn cosh(self) -> f32 {
    1038        cmath::coshf(self)
    1039    }
    1040
    1041    /// Hyperbolic tangent function.
    1042    ///
    1043    /// # Unspecified precision
    1044    ///
    1045    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    1046    /// can even differ within the same execution from one invocation to the next.
    1047    /// This function currently corresponds to the `tanhf` from libc on Unix
    1048    /// and Windows. Note that this might change in the future.
    1049    ///
    1050    /// # Examples
    1051    ///
    1052    /// ```
    1053    /// let e = std::f32::consts::E;
    1054    /// let x = 1.0f32;
    1055    ///
    1056    /// let f = x.tanh();
    1057    /// // Solving tanh() at 1 gives `(1 - e^(-2))/(1 + e^(-2))`
    1058    /// let g = (1.0 - e.powi(-2)) / (1.0 + e.powi(-2));
    1059    /// let abs_difference = (f - g).abs();
    1060    ///
    1061    /// assert!(abs_difference <= 1e-6);
    1062    /// ```
    1063    #[rustc_allow_incoherent_impl]
    1064    #[must_use = "method returns a new number and does not mutate the original value"]
    1065    #[stable(feature = "rust1", since = "1.0.0")]
    1066    #[inline]
    1067    pub fn tanh(self) -> f32 {
    1068        cmath::tanhf(self)
    1069    }
    1070
    1071    /// Inverse hyperbolic sine function.
    1072    ///
    1073    /// # Unspecified precision
    1074    ///
    1075    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    1076    /// can even differ within the same execution from one invocation to the next.
    1077    ///
    1078    /// # Examples
    1079    ///
    1080    /// ```
    1081    /// let x = 1.0f32;
    1082    /// let f = x.sinh().asinh();
    1083    ///
    1084    /// let abs_difference = (f - x).abs();
    1085    ///
    1086    /// assert!(abs_difference <= 1e-6);
    1087    /// ```
    1088    #[doc(alias = "arcsinh")]
    1089    #[rustc_allow_incoherent_impl]
    1090    #[must_use = "method returns a new number and does not mutate the original value"]
    1091    #[stable(feature = "rust1", since = "1.0.0")]
    1092    #[inline]
    1093    pub fn asinh(self) -> f32 {
    1094        let ax = self.abs();
    1095        let ix = 1.0 / ax;
    1096        (ax + (ax / (Self::hypot(1.0, ix) + ix))).ln_1p().copysign(self)
    1097    }
    1098
    1099    /// Inverse hyperbolic cosine function.
    1100    ///
    1101    /// # Unspecified precision
    1102    ///
    1103    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    1104    /// can even differ within the same execution from one invocation to the next.
    1105    ///
    1106    /// # Examples
    1107    ///
    1108    /// ```
    1109    /// let x = 1.0f32;
    1110    /// let f = x.cosh().acosh();
    1111    ///
    1112    /// let abs_difference = (f - x).abs();
    1113    ///
    1114    /// assert!(abs_difference <= 1e-6);
    1115    /// ```
    1116    #[doc(alias = "arccosh")]
    1117    #[rustc_allow_incoherent_impl]
    1118    #[must_use = "method returns a new number and does not mutate the original value"]
    1119    #[stable(feature = "rust1", since = "1.0.0")]
    1120    #[inline]
    1121    pub fn acosh(self) -> f32 {
    1122        if self < 1.0 {
    1123            Self::NAN
    1124        } else {
    1125            (self + ((self - 1.0).sqrt() * (self + 1.0).sqrt())).ln()
    1126        }
    1127    }
    1128
    1129    /// Inverse hyperbolic tangent function.
    1130    ///
    1131    /// # Unspecified precision
    1132    ///
    1133    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    1134    /// can even differ within the same execution from one invocation to the next.
    1135    ///
    1136    /// # Examples
    1137    ///
    1138    /// ```
    1139    /// let x = std::f32::consts::FRAC_PI_6;
    1140    /// let f = x.tanh().atanh();
    1141    ///
    1142    /// let abs_difference = (f - x).abs();
    1143    ///
    1144    /// assert!(abs_difference <= 1e-5);
    1145    /// ```
    1146    #[doc(alias = "arctanh")]
    1147    #[rustc_allow_incoherent_impl]
    1148    #[must_use = "method returns a new number and does not mutate the original value"]
    1149    #[stable(feature = "rust1", since = "1.0.0")]
    1150    #[inline]
    1151    pub fn atanh(self) -> f32 {
    1152        0.5 * ((2.0 * self) / (1.0 - self)).ln_1p()
    1153    }
    1154
    1155    /// Gamma function.
    1156    ///
    1157    /// # Unspecified precision
    1158    ///
    1159    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    1160    /// can even differ within the same execution from one invocation to the next.
    1161    /// This function currently corresponds to the `tgammaf` from libc on Unix
    1162    /// and Windows. Note that this might change in the future.
    1163    ///
    1164    /// # Examples
    1165    ///
    1166    /// ```
    1167    /// #![feature(float_gamma)]
    1168    /// let x = 5.0f32;
    1169    ///
    1170    /// let abs_difference = (x.gamma() - 24.0).abs();
    1171    ///
    1172    /// assert!(abs_difference <= 1e-5);
    1173    /// ```
    1174    #[rustc_allow_incoherent_impl]
    1175    #[must_use = "method returns a new number and does not mutate the original value"]
    1176    #[unstable(feature = "float_gamma", issue = "99842")]
    1177    #[inline]
    1178    pub fn gamma(self) -> f32 {
    1179        cmath::tgammaf(self)
    1180    }
    1181
    1182    /// Natural logarithm of the absolute value of the gamma function
    1183    ///
    1184    /// The integer part of the tuple indicates the sign of the gamma function.
    1185    ///
    1186    /// # Unspecified precision
    1187    ///
    1188    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    1189    /// can even differ within the same execution from one invocation to the next.
    1190    /// This function currently corresponds to the `lgamma_r` from libc on Unix
    1191    /// and Windows. Note that this might change in the future.
    1192    ///
    1193    /// # Examples
    1194    ///
    1195    /// ```
    1196    /// #![feature(float_gamma)]
    1197    /// let x = 2.0f32;
    1198    ///
    1199    /// let abs_difference = (x.ln_gamma().0 - 0.0).abs();
    1200    ///
    1201    /// assert!(abs_difference <= f32::EPSILON);
    1202    /// ```
    1203    #[rustc_allow_incoherent_impl]
    1204    #[must_use = "method returns a new number and does not mutate the original value"]
    1205    #[unstable(feature = "float_gamma", issue = "99842")]
    1206    #[inline]
    1207    pub fn ln_gamma(self) -> (f32, i32) {
    1208        let mut signgamp: i32 = 0;
    1209        let x = cmath::lgammaf_r(self, &mut signgamp);
    1210        (x, signgamp)
    1211    }
    1212
    1213    /// Error function.
    1214    ///
    1215    /// # Unspecified precision
    1216    ///
    1217    /// The precision of this function is non-deterministic. This means it varies by platform,
    1218    /// Rust version, and can even differ within the same execution from one invocation to the next.
    1219    ///
    1220    /// This function currently corresponds to the `erff` from libc on Unix
    1221    /// and Windows. Note that this might change in the future.
    1222    ///
    1223    /// # Examples
    1224    ///
    1225    /// ```
    1226    /// #![feature(float_erf)]
    1227    /// /// The error function relates what percent of a normal distribution lies
    1228    /// /// within `x` standard deviations (scaled by `1/sqrt(2)`).
    1229    /// fn within_standard_deviations(x: f32) -> f32 {
    1230    ///     (x * std::f32::consts::FRAC_1_SQRT_2).erf() * 100.0
    1231    /// }
    1232    ///
    1233    /// // 68% of a normal distribution is within one standard deviation
    1234    /// assert!((within_standard_deviations(1.0) - 68.269).abs() < 0.01);
    1235    /// // 95% of a normal distribution is within two standard deviations
    1236    /// assert!((within_standard_deviations(2.0) - 95.450).abs() < 0.01);
    1237    /// // 99.7% of a normal distribution is within three standard deviations
    1238    /// assert!((within_standard_deviations(3.0) - 99.730).abs() < 0.01);
    1239    /// ```
    1240    #[rustc_allow_incoherent_impl]
    1241    #[must_use = "method returns a new number and does not mutate the original value"]
    1242    #[unstable(feature = "float_erf", issue = "136321")]
    1243    #[inline]
    1244    pub fn erf(self) -> f32 {
    1245        cmath::erff(self)
    1246    }
    1247
    1248    /// Complementary error function.
    1249    ///
    1250    /// # Unspecified precision
    1251    ///
    1252    /// The precision of this function is non-deterministic. This means it varies by platform,
    1253    /// Rust version, and can even differ within the same execution from one invocation to the next.
    1254    ///
    1255    /// This function currently corresponds to the `erfcf` from libc on Unix
    1256    /// and Windows. Note that this might change in the future.
    1257    ///
    1258    /// # Examples
    1259    ///
    1260    /// ```
    1261    /// #![feature(float_erf)]
    1262    /// let x: f32 = 0.123;
    1263    ///
    1264    /// let one = x.erf() + x.erfc();
    1265    /// let abs_difference = (one - 1.0).abs();
    1266    ///
    1267    /// assert!(abs_difference <= 1e-6);
    1268    /// ```
    1269    #[rustc_allow_incoherent_impl]
    1270    #[must_use = "method returns a new number and does not mutate the original value"]
    1271    #[unstable(feature = "float_erf", issue = "136321")]
    1272    #[inline]
    1273    pub fn erfc(self) -> f32 {
    1274        cmath::erfcf(self)
    1275    }
    1276}