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

#
core/num/
f32.rs

    1//! Constants for the `f32` single-precision floating point type.
    2//!
    3//! *[See also the `f32` primitive type][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
    14use crate::convert::FloatToInt;
    15use crate::num::FpCategory;
    16use crate::panic::const_assert;
    17use crate::{cfg_select, intrinsics, mem};
    18
    19/// The radix or base of the internal representation of `f32`.
    20/// Use [`f32::RADIX`] instead.
    21///
    22/// # Examples
    23///
    24/// ```rust
    25/// // deprecated way
    26/// # #[allow(deprecated, deprecated_in_future)]
    27/// let r = std::f32::RADIX;
    28///
    29/// // intended way
    30/// let r = f32::RADIX;
    31/// ```
    32#[stable(feature = "rust1", since = "1.0.0")]
    33#[deprecated(since = "TBD", note = "replaced by the `RADIX` associated constant on `f32`")]
    34#[rustc_diagnostic_item = "f32_legacy_const_radix"]
    35pub const RADIX: u32 = f32::RADIX;
    36
    37/// Number of significant digits in base 2.
    38/// Use [`f32::MANTISSA_DIGITS`] instead.
    39///
    40/// # Examples
    41///
    42/// ```rust
    43/// // deprecated way
    44/// # #[allow(deprecated, deprecated_in_future)]
    45/// let d = std::f32::MANTISSA_DIGITS;
    46///
    47/// // intended way
    48/// let d = f32::MANTISSA_DIGITS;
    49/// ```
    50#[stable(feature = "rust1", since = "1.0.0")]
    51#[deprecated(
    52    since = "TBD",
    53    note = "replaced by the `MANTISSA_DIGITS` associated constant on `f32`"
    54)]
    55#[rustc_diagnostic_item = "f32_legacy_const_mantissa_dig"]
    56pub const MANTISSA_DIGITS: u32 = f32::MANTISSA_DIGITS;
    57
    58/// Approximate number of significant digits in base 10.
    59/// Use [`f32::DIGITS`] instead.
    60///
    61/// # Examples
    62///
    63/// ```rust
    64/// // deprecated way
    65/// # #[allow(deprecated, deprecated_in_future)]
    66/// let d = std::f32::DIGITS;
    67///
    68/// // intended way
    69/// let d = f32::DIGITS;
    70/// ```
    71#[stable(feature = "rust1", since = "1.0.0")]
    72#[deprecated(since = "TBD", note = "replaced by the `DIGITS` associated constant on `f32`")]
    73#[rustc_diagnostic_item = "f32_legacy_const_digits"]
    74pub const DIGITS: u32 = f32::DIGITS;
    75
    76/// [Machine epsilon] value for `f32`.
    77/// Use [`f32::EPSILON`] instead.
    78///
    79/// This is the difference between `1.0` and the next larger representable number.
    80///
    81/// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon
    82///
    83/// # Examples
    84///
    85/// ```rust
    86/// // deprecated way
    87/// # #[allow(deprecated, deprecated_in_future)]
    88/// let e = std::f32::EPSILON;
    89///
    90/// // intended way
    91/// let e = f32::EPSILON;
    92/// ```
    93#[stable(feature = "rust1", since = "1.0.0")]
    94#[deprecated(since = "TBD", note = "replaced by the `EPSILON` associated constant on `f32`")]
    95#[rustc_diagnostic_item = "f32_legacy_const_epsilon"]
    96pub const EPSILON: f32 = f32::EPSILON;
    97
    98/// Smallest finite `f32` value.
    99/// Use [`f32::MIN`] instead.
    100///
    101/// # Examples
    102///
    103/// ```rust
    104/// // deprecated way
    105/// # #[allow(deprecated, deprecated_in_future)]
    106/// let min = std::f32::MIN;
    107///
    108/// // intended way
    109/// let min = f32::MIN;
    110/// ```
    111#[stable(feature = "rust1", since = "1.0.0")]
    112#[deprecated(since = "TBD", note = "replaced by the `MIN` associated constant on `f32`")]
    113#[rustc_diagnostic_item = "f32_legacy_const_min"]
    114pub const MIN: f32 = f32::MIN;
    115
    116/// Smallest positive normal `f32` value.
    117/// Use [`f32::MIN_POSITIVE`] instead.
    118///
    119/// # Examples
    120///
    121/// ```rust
    122/// // deprecated way
    123/// # #[allow(deprecated, deprecated_in_future)]
    124/// let min = std::f32::MIN_POSITIVE;
    125///
    126/// // intended way
    127/// let min = f32::MIN_POSITIVE;
    128/// ```
    129#[stable(feature = "rust1", since = "1.0.0")]
    130#[deprecated(since = "TBD", note = "replaced by the `MIN_POSITIVE` associated constant on `f32`")]
    131#[rustc_diagnostic_item = "f32_legacy_const_min_positive"]
    132pub const MIN_POSITIVE: f32 = f32::MIN_POSITIVE;
    133
    134/// Largest finite `f32` value.
    135/// Use [`f32::MAX`] instead.
    136///
    137/// # Examples
    138///
    139/// ```rust
    140/// // deprecated way
    141/// # #[allow(deprecated, deprecated_in_future)]
    142/// let max = std::f32::MAX;
    143///
    144/// // intended way
    145/// let max = f32::MAX;
    146/// ```
    147#[stable(feature = "rust1", since = "1.0.0")]
    148#[deprecated(since = "TBD", note = "replaced by the `MAX` associated constant on `f32`")]
    149#[rustc_diagnostic_item = "f32_legacy_const_max"]
    150pub const MAX: f32 = f32::MAX;
    151
    152/// One greater than the minimum possible normal power of 2 exponent.
    153/// Use [`f32::MIN_EXP`] instead.
    154///
    155/// # Examples
    156///
    157/// ```rust
    158/// // deprecated way
    159/// # #[allow(deprecated, deprecated_in_future)]
    160/// let min = std::f32::MIN_EXP;
    161///
    162/// // intended way
    163/// let min = f32::MIN_EXP;
    164/// ```
    165#[stable(feature = "rust1", since = "1.0.0")]
    166#[deprecated(since = "TBD", note = "replaced by the `MIN_EXP` associated constant on `f32`")]
    167#[rustc_diagnostic_item = "f32_legacy_const_min_exp"]
    168pub const MIN_EXP: i32 = f32::MIN_EXP;
    169
    170/// Maximum possible power of 2 exponent.
    171/// Use [`f32::MAX_EXP`] instead.
    172///
    173/// # Examples
    174///
    175/// ```rust
    176/// // deprecated way
    177/// # #[allow(deprecated, deprecated_in_future)]
    178/// let max = std::f32::MAX_EXP;
    179///
    180/// // intended way
    181/// let max = f32::MAX_EXP;
    182/// ```
    183#[stable(feature = "rust1", since = "1.0.0")]
    184#[deprecated(since = "TBD", note = "replaced by the `MAX_EXP` associated constant on `f32`")]
    185#[rustc_diagnostic_item = "f32_legacy_const_max_exp"]
    186pub const MAX_EXP: i32 = f32::MAX_EXP;
    187
    188/// Minimum possible normal power of 10 exponent.
    189/// Use [`f32::MIN_10_EXP`] instead.
    190///
    191/// # Examples
    192///
    193/// ```rust
    194/// // deprecated way
    195/// # #[allow(deprecated, deprecated_in_future)]
    196/// let min = std::f32::MIN_10_EXP;
    197///
    198/// // intended way
    199/// let min = f32::MIN_10_EXP;
    200/// ```
    201#[stable(feature = "rust1", since = "1.0.0")]
    202#[deprecated(since = "TBD", note = "replaced by the `MIN_10_EXP` associated constant on `f32`")]
    203#[rustc_diagnostic_item = "f32_legacy_const_min_10_exp"]
    204pub const MIN_10_EXP: i32 = f32::MIN_10_EXP;
    205
    206/// Maximum possible power of 10 exponent.
    207/// Use [`f32::MAX_10_EXP`] instead.
    208///
    209/// # Examples
    210///
    211/// ```rust
    212/// // deprecated way
    213/// # #[allow(deprecated, deprecated_in_future)]
    214/// let max = std::f32::MAX_10_EXP;
    215///
    216/// // intended way
    217/// let max = f32::MAX_10_EXP;
    218/// ```
    219#[stable(feature = "rust1", since = "1.0.0")]
    220#[deprecated(since = "TBD", note = "replaced by the `MAX_10_EXP` associated constant on `f32`")]
    221#[rustc_diagnostic_item = "f32_legacy_const_max_10_exp"]
    222pub const MAX_10_EXP: i32 = f32::MAX_10_EXP;
    223
    224/// Not a Number (NaN).
    225/// Use [`f32::NAN`] instead.
    226///
    227/// # Examples
    228///
    229/// ```rust
    230/// // deprecated way
    231/// # #[allow(deprecated, deprecated_in_future)]
    232/// let nan = std::f32::NAN;
    233///
    234/// // intended way
    235/// let nan = f32::NAN;
    236/// ```
    237#[stable(feature = "rust1", since = "1.0.0")]
    238#[deprecated(since = "TBD", note = "replaced by the `NAN` associated constant on `f32`")]
    239#[rustc_diagnostic_item = "f32_legacy_const_nan"]
    240pub const NAN: f32 = f32::NAN;
    241
    242/// Infinity (∞).
    243/// Use [`f32::INFINITY`] instead.
    244///
    245/// # Examples
    246///
    247/// ```rust
    248/// // deprecated way
    249/// # #[allow(deprecated, deprecated_in_future)]
    250/// let inf = std::f32::INFINITY;
    251///
    252/// // intended way
    253/// let inf = f32::INFINITY;
    254/// ```
    255#[stable(feature = "rust1", since = "1.0.0")]
    256#[deprecated(since = "TBD", note = "replaced by the `INFINITY` associated constant on `f32`")]
    257#[rustc_diagnostic_item = "f32_legacy_const_infinity"]
    258pub const INFINITY: f32 = f32::INFINITY;
    259
    260/// Negative infinity (−∞).
    261/// Use [`f32::NEG_INFINITY`] instead.
    262///
    263/// # Examples
    264///
    265/// ```rust
    266/// // deprecated way
    267/// # #[allow(deprecated, deprecated_in_future)]
    268/// let ninf = std::f32::NEG_INFINITY;
    269///
    270/// // intended way
    271/// let ninf = f32::NEG_INFINITY;
    272/// ```
    273#[stable(feature = "rust1", since = "1.0.0")]
    274#[deprecated(since = "TBD", note = "replaced by the `NEG_INFINITY` associated constant on `f32`")]
    275#[rustc_diagnostic_item = "f32_legacy_const_neg_infinity"]
    276pub const NEG_INFINITY: f32 = f32::NEG_INFINITY;
    277
    278/// Basic mathematical constants.
    279#[stable(feature = "rust1", since = "1.0.0")]
    280#[rustc_diagnostic_item = "f32_consts_mod"]
    281pub mod consts {
    282    // FIXME: replace with mathematical constants from cmath.
    283
    284    /// Archimedes' constant (π)
    285    #[stable(feature = "rust1", since = "1.0.0")]
    286    pub const PI: f32 = 3.14159265358979323846264338327950288_f32;
    287
    288    /// The full circle constant (τ)
    289    ///
    290    /// Equal to 2π.
    291    #[stable(feature = "tau_constant", since = "1.47.0")]
    292    pub const TAU: f32 = 6.28318530717958647692528676655900577_f32;
    293
    294    /// The golden ratio (φ)
    295    #[stable(feature = "euler_gamma_golden_ratio", since = "1.94.0")]
    296    pub const GOLDEN_RATIO: f32 = 1.618033988749894848204586834365638118_f32;
    297
    298    /// The Euler-Mascheroni constant (γ)
    299    #[stable(feature = "euler_gamma_golden_ratio", since = "1.94.0")]
    300    pub const EULER_GAMMA: f32 = 0.577215664901532860606512090082402431_f32;
    301
    302    /// π/2
    303    #[stable(feature = "rust1", since = "1.0.0")]
    304    pub const FRAC_PI_2: f32 = 1.57079632679489661923132169163975144_f32;
    305
    306    /// π/3
    307    #[stable(feature = "rust1", since = "1.0.0")]
    308    pub const FRAC_PI_3: f32 = 1.04719755119659774615421446109316763_f32;
    309
    310    /// π/4
    311    #[stable(feature = "rust1", since = "1.0.0")]
    312    pub const FRAC_PI_4: f32 = 0.785398163397448309615660845819875721_f32;
    313
    314    /// π/6
    315    #[stable(feature = "rust1", since = "1.0.0")]
    316    pub const FRAC_PI_6: f32 = 0.52359877559829887307710723054658381_f32;
    317
    318    /// π/8
    319    #[stable(feature = "rust1", since = "1.0.0")]
    320    pub const FRAC_PI_8: f32 = 0.39269908169872415480783042290993786_f32;
    321
    322    /// 1/π
    323    #[stable(feature = "rust1", since = "1.0.0")]
    324    pub const FRAC_1_PI: f32 = 0.318309886183790671537767526745028724_f32;
    325
    326    /// 1/sqrt(π)
    327    #[unstable(feature = "more_float_constants", issue = "146939")]
    328    pub const FRAC_1_SQRT_PI: f32 = 0.564189583547756286948079451560772586_f32;
    329
    330    /// 1/sqrt(2π)
    331    #[doc(alias = "FRAC_1_SQRT_TAU")]
    332    #[unstable(feature = "more_float_constants", issue = "146939")]
    333    pub const FRAC_1_SQRT_2PI: f32 = 0.398942280401432677939946059934381868_f32;
    334
    335    /// 2/π
    336    #[stable(feature = "rust1", since = "1.0.0")]
    337    pub const FRAC_2_PI: f32 = 0.636619772367581343075535053490057448_f32;
    338
    339    /// 2/sqrt(π)
    340    #[stable(feature = "rust1", since = "1.0.0")]
    341    pub const FRAC_2_SQRT_PI: f32 = 1.12837916709551257389615890312154517_f32;
    342
    343    /// sqrt(2)
    344    #[stable(feature = "rust1", since = "1.0.0")]
    345    pub const SQRT_2: f32 = 1.41421356237309504880168872420969808_f32;
    346
    347    /// 1/sqrt(2)
    348    #[stable(feature = "rust1", since = "1.0.0")]
    349    pub const FRAC_1_SQRT_2: f32 = 0.707106781186547524400844362104849039_f32;
    350
    351    /// sqrt(3)
    352    #[unstable(feature = "more_float_constants", issue = "146939")]
    353    pub const SQRT_3: f32 = 1.732050807568877293527446341505872367_f32;
    354
    355    /// 1/sqrt(3)
    356    #[unstable(feature = "more_float_constants", issue = "146939")]
    357    pub const FRAC_1_SQRT_3: f32 = 0.577350269189625764509148780501957456_f32;
    358
    359    /// Euler's number (e)
    360    #[stable(feature = "rust1", since = "1.0.0")]
    361    pub const E: f32 = 2.71828182845904523536028747135266250_f32;
    362
    363    /// log<sub>2</sub>(e)
    364    #[stable(feature = "rust1", since = "1.0.0")]
    365    pub const LOG2_E: f32 = 1.44269504088896340735992468100189214_f32;
    366
    367    /// log<sub>2</sub>(10)
    368    #[stable(feature = "extra_log_consts", since = "1.43.0")]
    369    pub const LOG2_10: f32 = 3.32192809488736234787031942948939018_f32;
    370
    371    /// log<sub>10</sub>(e)
    372    #[stable(feature = "rust1", since = "1.0.0")]
    373    pub const LOG10_E: f32 = 0.434294481903251827651128918916605082_f32;
    374
    375    /// log<sub>10</sub>(2)
    376    #[stable(feature = "extra_log_consts", since = "1.43.0")]
    377    pub const LOG10_2: f32 = 0.301029995663981195213738894724493027_f32;
    378
    379    /// ln(2)
    380    #[stable(feature = "rust1", since = "1.0.0")]
    381    pub const LN_2: f32 = 0.693147180559945309417232121458176568_f32;
    382
    383    /// ln(10)
    384    #[stable(feature = "rust1", since = "1.0.0")]
    385    pub const LN_10: f32 = 2.30258509299404568401799145468436421_f32;
    386}
    387
    388impl f32 {
    389    /// The radix or base of the internal representation of `f32`.
    390    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    391    pub const RADIX: u32 = 2;
    392
    393    /// Number of significant digits in base 2.
    394    ///
    395    /// Note that the size of the mantissa in the bitwise representation is one
    396    /// smaller than this since the leading 1 is not stored explicitly.
    397    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    398    pub const MANTISSA_DIGITS: u32 = 24;
    399
    400    /// Approximate number of significant digits in base 10.
    401    ///
    402    /// This is the maximum <i>x</i> such that any decimal number with <i>x</i>
    403    /// significant digits can be converted to `f32` and back without loss.
    404    ///
    405    /// Equal to floor(log<sub>10</sub>&nbsp;2<sup>[`MANTISSA_DIGITS`]&nbsp;&minus;&nbsp;1</sup>).
    406    ///
    407    /// [`MANTISSA_DIGITS`]: f32::MANTISSA_DIGITS
    408    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    409    pub const DIGITS: u32 = 6;
    410
    411    /// [Machine epsilon] value for `f32`.
    412    ///
    413    /// This is the difference between `1.0` and the next larger representable number.
    414    ///
    415    /// Equal to 2<sup>1&nbsp;&minus;&nbsp;[`MANTISSA_DIGITS`]</sup>.
    416    ///
    417    /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon
    418    /// [`MANTISSA_DIGITS`]: f32::MANTISSA_DIGITS
    419    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    420    #[rustc_diagnostic_item = "f32_epsilon"]
    421    pub const EPSILON: f32 = 1.19209290e-07_f32;
    422
    423    /// Smallest finite `f32` value.
    424    ///
    425    /// Equal to &minus;[`MAX`].
    426    ///
    427    /// [`MAX`]: f32::MAX
    428    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    429    pub const MIN: f32 = -3.40282347e+38_f32;
    430    /// Smallest positive normal `f32` value.
    431    ///
    432    /// Equal to 2<sup>[`MIN_EXP`]&nbsp;&minus;&nbsp;1</sup>.
    433    ///
    434    /// [`MIN_EXP`]: f32::MIN_EXP
    435    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    436    pub const MIN_POSITIVE: f32 = 1.17549435e-38_f32;
    437    /// Largest finite `f32` value.
    438    ///
    439    /// Equal to
    440    /// (1&nbsp;&minus;&nbsp;2<sup>&minus;[`MANTISSA_DIGITS`]</sup>)&nbsp;2<sup>[`MAX_EXP`]</sup>.
    441    ///
    442    /// [`MANTISSA_DIGITS`]: f32::MANTISSA_DIGITS
    443    /// [`MAX_EXP`]: f32::MAX_EXP
    444    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    445    pub const MAX: f32 = 3.40282347e+38_f32;
    446
    447    /// One greater than the minimum possible *normal* power of 2 exponent
    448    /// for a significand bounded by 1 ≤ x < 2 (i.e. the IEEE definition).
    449    ///
    450    /// This corresponds to the exact minimum possible *normal* power of 2 exponent
    451    /// for a significand bounded by 0.5 ≤ x < 1 (i.e. the C definition).
    452    /// In other words, all normal numbers representable by this type are
    453    /// greater than or equal to 0.5&nbsp;×&nbsp;2<sup><i>MIN_EXP</i></sup>.
    454    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    455    pub const MIN_EXP: i32 = -125;
    456    /// One greater than the maximum possible power of 2 exponent
    457    /// for a significand bounded by 1 ≤ x < 2 (i.e. the IEEE definition).
    458    ///
    459    /// This corresponds to the exact maximum possible power of 2 exponent
    460    /// for a significand bounded by 0.5 ≤ x < 1 (i.e. the C definition).
    461    /// In other words, all numbers representable by this type are
    462    /// strictly less than 2<sup><i>MAX_EXP</i></sup>.
    463    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    464    pub const MAX_EXP: i32 = 128;
    465
    466    /// Minimum <i>x</i> for which 10<sup><i>x</i></sup> is normal.
    467    ///
    468    /// Equal to ceil(log<sub>10</sub>&nbsp;[`MIN_POSITIVE`]).
    469    ///
    470    /// [`MIN_POSITIVE`]: f32::MIN_POSITIVE
    471    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    472    pub const MIN_10_EXP: i32 = -37;
    473    /// Maximum <i>x</i> for which 10<sup><i>x</i></sup> is normal.
    474    ///
    475    /// Equal to floor(log<sub>10</sub>&nbsp;[`MAX`]).
    476    ///
    477    /// [`MAX`]: f32::MAX
    478    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    479    pub const MAX_10_EXP: i32 = 38;
    480
    481    /// Not a Number (NaN).
    482    ///
    483    /// Note that IEEE 754 doesn't define just a single NaN value; a plethora of bit patterns are
    484    /// considered to be NaN. Furthermore, the standard makes a difference between a "signaling" and
    485    /// a "quiet" NaN, and allows inspecting its "payload" (the unspecified bits in the bit pattern)
    486    /// and its sign. See the [specification of NaN bit patterns](f32#nan-bit-patterns) for more
    487    /// info.
    488    ///
    489    /// This constant is guaranteed to be a quiet NaN (on targets that follow the Rust assumptions
    490    /// that the quiet/signaling bit being set to 1 indicates a quiet NaN). Beyond that, nothing is
    491    /// guaranteed about the specific bit pattern chosen here: both payload and sign are arbitrary.
    492    /// The concrete bit pattern may change across Rust versions and target platforms.
    493    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    494    #[rustc_diagnostic_item = "f32_nan"]
    495    #[allow(clippy::eq_op)]
    496    pub const NAN: f32 = 0.0_f32 / 0.0_f32;
    497    /// Infinity (∞).
    498    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    499    pub const INFINITY: f32 = 1.0_f32 / 0.0_f32;
    500    /// Negative infinity (−∞).
    501    #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    502    pub const NEG_INFINITY: f32 = -1.0_f32 / 0.0_f32;
    503
    504    /// Sign bit
    505    pub(crate) const SIGN_MASK: u32 = 0x8000_0000;
    506
    507    /// Exponent mask
    508    pub(crate) const EXP_MASK: u32 = 0x7f80_0000;
    509
    510    /// Mantissa mask
    511    pub(crate) const MAN_MASK: u32 = 0x007f_ffff;
    512
    513    /// Minimum representable positive value (min subnormal)
    514    const TINY_BITS: u32 = 0x1;
    515
    516    /// Minimum representable negative value (min negative subnormal)
    517    const NEG_TINY_BITS: u32 = Self::TINY_BITS | Self::SIGN_MASK;
    518
    519    /// Returns `true` if this value is NaN.
    520    ///
    521    /// ```
    522    /// let nan = f32::NAN;
    523    /// let f = 7.0_f32;
    524    ///
    525    /// assert!(nan.is_nan());
    526    /// assert!(!f.is_nan());
    527    /// ```
    528    #[must_use]
    529    #[stable(feature = "rust1", since = "1.0.0")]
    530    #[rustc_const_stable(feature = "const_float_classify", since = "1.83.0")]
    531    #[inline]
    532    #[allow(clippy::eq_op)] // > if you intended to check if the operand is NaN, use `.is_nan()` instead :)
    533    pub const fn is_nan(self) -> bool {
    534        self != self
    535    }
    536
    537    /// Returns `true` if this value is positive infinity or negative infinity, and
    538    /// `false` otherwise.
    539    ///
    540    /// ```
    541    /// let f = 7.0f32;
    542    /// let inf = f32::INFINITY;
    543    /// let neg_inf = f32::NEG_INFINITY;
    544    /// let nan = f32::NAN;
    545    ///
    546    /// assert!(!f.is_infinite());
    547    /// assert!(!nan.is_infinite());
    548    ///
    549    /// assert!(inf.is_infinite());
    550    /// assert!(neg_inf.is_infinite());
    551    /// ```
    552    #[must_use]
    553    #[stable(feature = "rust1", since = "1.0.0")]
    554    #[rustc_const_stable(feature = "const_float_classify", since = "1.83.0")]
    555    #[inline]
    556    pub const fn is_infinite(self) -> bool {
    557        // Getting clever with transmutation can result in incorrect answers on some FPUs
    558        // FIXME: alter the Rust <-> Rust calling convention to prevent this problem.
    559        // See https://github.com/rust-lang/rust/issues/72327
    560        (self == f32::INFINITY) | (self == f32::NEG_INFINITY)
    561    }
    562
    563    /// Returns `true` if this number is neither infinite nor NaN.
    564    ///
    565    /// ```
    566    /// let f = 7.0f32;
    567    /// let inf = f32::INFINITY;
    568    /// let neg_inf = f32::NEG_INFINITY;
    569    /// let nan = f32::NAN;
    570    ///
    571    /// assert!(f.is_finite());
    572    ///
    573    /// assert!(!nan.is_finite());
    574    /// assert!(!inf.is_finite());
    575    /// assert!(!neg_inf.is_finite());
    576    /// ```
    577    #[must_use]
    578    #[stable(feature = "rust1", since = "1.0.0")]
    579    #[rustc_const_stable(feature = "const_float_classify", since = "1.83.0")]
    580    #[inline]
    581    pub const fn is_finite(self) -> bool {
    582        // There's no need to handle NaN separately: if self is NaN,
    583        // the comparison is not true, exactly as desired.
    584        self.abs() < Self::INFINITY
    585    }
    586
    587    /// Returns `true` if the number is [subnormal].
    588    ///
    589    /// ```
    590    /// let min = f32::MIN_POSITIVE; // 1.17549435e-38f32
    591    /// let max = f32::MAX;
    592    /// let lower_than_min = 1.0e-40_f32;
    593    /// let zero = 0.0_f32;
    594    ///
    595    /// assert!(!min.is_subnormal());
    596    /// assert!(!max.is_subnormal());
    597    ///
    598    /// assert!(!zero.is_subnormal());
    599    /// assert!(!f32::NAN.is_subnormal());
    600    /// assert!(!f32::INFINITY.is_subnormal());
    601    /// // Values between `0` and `min` are Subnormal.
    602    /// assert!(lower_than_min.is_subnormal());
    603    /// ```
    604    /// [subnormal]: https://en.wikipedia.org/wiki/Denormal_number
    605    #[must_use]
    606    #[stable(feature = "is_subnormal", since = "1.53.0")]
    607    #[rustc_const_stable(feature = "const_float_classify", since = "1.83.0")]
    608    #[inline]
    609    pub const fn is_subnormal(self) -> bool {
    610        matches!(self.classify(), FpCategory::Subnormal)
    611    }
    612
    613    /// Returns `true` if the number is neither zero, infinite,
    614    /// [subnormal], or NaN.
    615    ///
    616    /// ```
    617    /// let min = f32::MIN_POSITIVE; // 1.17549435e-38f32
    618    /// let max = f32::MAX;
    619    /// let lower_than_min = 1.0e-40_f32;
    620    /// let zero = 0.0_f32;
    621    ///
    622    /// assert!(min.is_normal());
    623    /// assert!(max.is_normal());
    624    ///
    625    /// assert!(!zero.is_normal());
    626    /// assert!(!f32::NAN.is_normal());
    627    /// assert!(!f32::INFINITY.is_normal());
    628    /// // Values between `0` and `min` are Subnormal.
    629    /// assert!(!lower_than_min.is_normal());
    630    /// ```
    631    /// [subnormal]: https://en.wikipedia.org/wiki/Denormal_number
    632    #[must_use]
    633    #[stable(feature = "rust1", since = "1.0.0")]
    634    #[rustc_const_stable(feature = "const_float_classify", since = "1.83.0")]
    635    #[inline]
    636    pub const fn is_normal(self) -> bool {
    637        matches!(self.classify(), FpCategory::Normal)
    638    }
    639
    640    /// Returns the floating point category of the number. If only one property
    641    /// is going to be tested, it is generally faster to use the specific
    642    /// predicate instead.
    643    ///
    644    /// ```
    645    /// use std::num::FpCategory;
    646    ///
    647    /// let num = 12.4_f32;
    648    /// let inf = f32::INFINITY;
    649    ///
    650    /// assert_eq!(num.classify(), FpCategory::Normal);
    651    /// assert_eq!(inf.classify(), FpCategory::Infinite);
    652    /// ```
    653    #[stable(feature = "rust1", since = "1.0.0")]
    654    #[rustc_const_stable(feature = "const_float_classify", since = "1.83.0")]
    655    pub const fn classify(self) -> FpCategory {
    656        // We used to have complicated logic here that avoids the simple bit-based tests to work
    657        // around buggy codegen for x87 targets (see
    658        // https://github.com/rust-lang/rust/issues/114479). However, some LLVM versions later, none
    659        // of our tests is able to find any difference between the complicated and the naive
    660        // version, so now we are back to the naive version.
    661        let b = self.to_bits();
    662        match (b & Self::MAN_MASK, b & Self::EXP_MASK) {
    663            (0, Self::EXP_MASK) => FpCategory::Infinite,
    664            (_, Self::EXP_MASK) => FpCategory::Nan,
    665            (0, 0) => FpCategory::Zero,
    666            (_, 0) => FpCategory::Subnormal,
    667            _ => FpCategory::Normal,
    668        }
    669    }
    670
    671    /// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with
    672    /// positive sign bit and positive infinity.
    673    ///
    674    /// Note that IEEE 754 doesn't assign any meaning to the sign bit in case of
    675    /// a NaN, and as Rust doesn't guarantee that the bit pattern of NaNs are
    676    /// conserved over arithmetic operations, the result of `is_sign_positive` on
    677    /// a NaN might produce an unexpected or non-portable result. See the [specification
    678    /// of NaN bit patterns](f32#nan-bit-patterns) for more info. Use `self.signum() == 1.0`
    679    /// if you need fully portable behavior (will return `false` for all NaNs).
    680    ///
    681    /// ```
    682    /// let f = 7.0_f32;
    683    /// let g = -7.0_f32;
    684    ///
    685    /// assert!(f.is_sign_positive());
    686    /// assert!(!g.is_sign_positive());
    687    /// ```
    688    #[must_use]
    689    #[stable(feature = "rust1", since = "1.0.0")]
    690    #[rustc_const_stable(feature = "const_float_classify", since = "1.83.0")]
    691    #[inline]
    692    pub const fn is_sign_positive(self) -> bool {
    693        !self.is_sign_negative()
    694    }
    695
    696    /// Returns `true` if `self` has a negative sign, including `-0.0`, NaNs with
    697    /// negative sign bit and negative infinity.
    698    ///
    699    /// Note that IEEE 754 doesn't assign any meaning to the sign bit in case of
    700    /// a NaN, and as Rust doesn't guarantee that the bit pattern of NaNs are
    701    /// conserved over arithmetic operations, the result of `is_sign_negative` on
    702    /// a NaN might produce an unexpected or non-portable result. See the [specification
    703    /// of NaN bit patterns](f32#nan-bit-patterns) for more info. Use `self.signum() == -1.0`
    704    /// if you need fully portable behavior (will return `false` for all NaNs).
    705    ///
    706    /// ```
    707    /// let f = 7.0f32;
    708    /// let g = -7.0f32;
    709    ///
    710    /// assert!(!f.is_sign_negative());
    711    /// assert!(g.is_sign_negative());
    712    /// ```
    713    #[must_use]
    714    #[stable(feature = "rust1", since = "1.0.0")]
    715    #[rustc_const_stable(feature = "const_float_classify", since = "1.83.0")]
    716    #[inline]
    717    pub const fn is_sign_negative(self) -> bool {
    718        // IEEE754 says: isSignMinus(x) is true if and only if x has negative sign. isSignMinus
    719        // applies to zeros and NaNs as well.
    720        self.to_bits() & 0x8000_0000 != 0
    721    }
    722
    723    /// Returns the least number greater than `self`.
    724    ///
    725    /// Let `TINY` be the smallest representable positive `f32`. Then,
    726    ///  - if `self.is_nan()`, this returns `self`;
    727    ///  - if `self` is [`NEG_INFINITY`], this returns [`MIN`];
    728    ///  - if `self` is `-TINY`, this returns -0.0;
    729    ///  - if `self` is -0.0 or +0.0, this returns `TINY`;
    730    ///  - if `self` is [`MAX`] or [`INFINITY`], this returns [`INFINITY`];
    731    ///  - otherwise the unique least value greater than `self` is returned.
    732    ///
    733    /// The identity `x.next_up() == -(-x).next_down()` holds for all non-NaN `x`. When `x`
    734    /// is finite `x == x.next_up().next_down()` also holds.
    735    ///
    736    /// ```rust
    737    /// // f32::EPSILON is the difference between 1.0 and the next number up.
    738    /// assert_eq!(1.0f32.next_up(), 1.0 + f32::EPSILON);
    739    /// // But not for most numbers.
    740    /// assert!(0.1f32.next_up() < 0.1 + f32::EPSILON);
    741    /// assert_eq!(16777216f32.next_up(), 16777218.0);
    742    /// ```
    743    ///
    744    /// This operation corresponds to IEEE-754 `nextUp`.
    745    ///
    746    /// [`NEG_INFINITY`]: Self::NEG_INFINITY
    747    /// [`INFINITY`]: Self::INFINITY
    748    /// [`MIN`]: Self::MIN
    749    /// [`MAX`]: Self::MAX
    750    #[inline]
    751    #[doc(alias = "nextUp")]
    752    #[stable(feature = "float_next_up_down", since = "1.86.0")]
    753    #[rustc_const_stable(feature = "float_next_up_down", since = "1.86.0")]
    754    pub const fn next_up(self) -> Self {
    755        // Some targets violate Rust's assumption of IEEE semantics, e.g. by flushing
    756        // denormals to zero. This is in general unsound and unsupported, but here
    757        // we do our best to still produce the correct result on such targets.
    758        let bits = self.to_bits();
    759        if self.is_nan() || bits == Self::INFINITY.to_bits() {
    760            return self;
    761        }
    762
    763        let abs = bits & !Self::SIGN_MASK;
    764        let next_bits = if abs == 0 {
    765            Self::TINY_BITS
    766        } else if bits == abs {
    767            bits + 1
    768        } else {
    769            bits - 1
    770        };
    771        Self::from_bits(next_bits)
    772    }
    773
    774    /// Returns the greatest number less than `self`.
    775    ///
    776    /// Let `TINY` be the smallest representable positive `f32`. Then,
    777    ///  - if `self.is_nan()`, this returns `self`;
    778    ///  - if `self` is [`INFINITY`], this returns [`MAX`];
    779    ///  - if `self` is `TINY`, this returns 0.0;
    780    ///  - if `self` is -0.0 or +0.0, this returns `-TINY`;
    781    ///  - if `self` is [`MIN`] or [`NEG_INFINITY`], this returns [`NEG_INFINITY`];
    782    ///  - otherwise the unique greatest value less than `self` is returned.
    783    ///
    784    /// The identity `x.next_down() == -(-x).next_up()` holds for all non-NaN `x`. When `x`
    785    /// is finite `x == x.next_down().next_up()` also holds.
    786    ///
    787    /// ```rust
    788    /// let x = 1.0f32;
    789    /// // Clamp value into range [0, 1).
    790    /// let clamped = x.clamp(0.0, 1.0f32.next_down());
    791    /// assert!(clamped < 1.0);
    792    /// assert_eq!(clamped.next_up(), 1.0);
    793    /// ```
    794    ///
    795    /// This operation corresponds to IEEE-754 `nextDown`.
    796    ///
    797    /// [`NEG_INFINITY`]: Self::NEG_INFINITY
    798    /// [`INFINITY`]: Self::INFINITY
    799    /// [`MIN`]: Self::MIN
    800    /// [`MAX`]: Self::MAX
    801    #[inline]
    802    #[doc(alias = "nextDown")]
    803    #[stable(feature = "float_next_up_down", since = "1.86.0")]
    804    #[rustc_const_stable(feature = "float_next_up_down", since = "1.86.0")]
    805    pub const fn next_down(self) -> Self {
    806        // Some targets violate Rust's assumption of IEEE semantics, e.g. by flushing
    807        // denormals to zero. This is in general unsound and unsupported, but here
    808        // we do our best to still produce the correct result on such targets.
    809        let bits = self.to_bits();
    810        if self.is_nan() || bits == Self::NEG_INFINITY.to_bits() {
    811            return self;
    812        }
    813
    814        let abs = bits & !Self::SIGN_MASK;
    815        let next_bits = if abs == 0 {
    816            Self::NEG_TINY_BITS
    817        } else if bits == abs {
    818            bits - 1
    819        } else {
    820            bits + 1
    821        };
    822        Self::from_bits(next_bits)
    823    }
    824
    825    /// Takes the reciprocal (inverse) of a number, `1/x`.
    826    ///
    827    /// ```
    828    /// let x = 2.0_f32;
    829    /// let abs_difference = (x.recip() - (1.0 / x)).abs();
    830    ///
    831    /// assert!(abs_difference <= f32::EPSILON);
    832    /// ```
    833    #[must_use = "this returns the result of the operation, without modifying the original"]
    834    #[stable(feature = "rust1", since = "1.0.0")]
    835    #[rustc_const_stable(feature = "const_float_methods", since = "1.85.0")]
    836    #[inline]
    837    pub const fn recip(self) -> f32 {
    838        1.0 / self
    839    }
    840
    841    /// Converts radians to degrees.
    842    ///
    843    /// # Unspecified precision
    844    ///
    845    /// The precision of this function is non-deterministic. This means it varies by platform,
    846    /// Rust version, and can even differ within the same execution from one invocation to the next.
    847    ///
    848    /// # Examples
    849    ///
    850    /// ```
    851    /// let angle = std::f32::consts::PI;
    852    ///
    853    /// let abs_difference = (angle.to_degrees() - 180.0).abs();
    854    /// # #[cfg(any(not(target_arch = "x86"), target_feature = "sse2"))]
    855    /// assert!(abs_difference <= f32::EPSILON);
    856    /// ```
    857    #[must_use = "this returns the result of the operation, \
    858                  without modifying the original"]
    859    #[stable(feature = "f32_deg_rad_conversions", since = "1.7.0")]
    860    #[rustc_const_stable(feature = "const_float_methods", since = "1.85.0")]
    861    #[inline]
    862    pub const fn to_degrees(self) -> f32 {
    863        // Use a literal to avoid double rounding, consts::PI is already rounded,
    864        // and dividing would round again.
    865        const PIS_IN_180: f32 = 57.2957795130823208767981548141051703_f32;
    866        self * PIS_IN_180
    867    }
    868
    869    /// Converts degrees to radians.
    870    ///
    871    /// # Unspecified precision
    872    ///
    873    /// The precision of this function is non-deterministic. This means it varies by platform,
    874    /// Rust version, and can even differ within the same execution from one invocation to the next.
    875    ///
    876    /// # Examples
    877    ///
    878    /// ```
    879    /// let angle = 180.0f32;
    880    ///
    881    /// let abs_difference = (angle.to_radians() - std::f32::consts::PI).abs();
    882    ///
    883    /// assert!(abs_difference <= f32::EPSILON);
    884    /// ```
    885    #[must_use = "this returns the result of the operation, \
    886                  without modifying the original"]
    887    #[stable(feature = "f32_deg_rad_conversions", since = "1.7.0")]
    888    #[rustc_const_stable(feature = "const_float_methods", since = "1.85.0")]
    889    #[inline]
    890    pub const fn to_radians(self) -> f32 {
    891        // The division here is correctly rounded with respect to the true value of π/180.
    892        // Although π is irrational and already rounded, the double rounding happens
    893        // to produce correct result for f32.
    894        const RADS_PER_DEG: f32 = consts::PI / 180.0;
    895        self * RADS_PER_DEG
    896    }
    897
    898    /// Returns the maximum of the two numbers, ignoring NaN.
    899    ///
    900    /// If exactly one of the arguments is NaN (quiet or signaling), then the other argument is
    901    /// returned. If both arguments are NaN, the return value is NaN, with the bit pattern picked
    902    /// using the usual [rules for arithmetic operations](f32#nan-bit-patterns). If the inputs
    903    /// compare equal (such as for the case of `+0.0` and `-0.0`), either input may be returned
    904    /// non-deterministically.
    905    ///
    906    /// The handling of NaNs follows the IEEE 754-2019 semantics for `maximumNumber`, treating all
    907    /// NaNs the same way to ensure the operation is associative. The handling of signed zeros
    908    /// follows the IEEE 754-2008 semantics for `maxNum`.
    909    ///
    910    /// ```
    911    /// let x = 1.0f32;
    912    /// let y = 2.0f32;
    913    ///
    914    /// assert_eq!(x.max(y), y);
    915    /// assert_eq!(x.max(f32::NAN), x);
    916    /// ```
    917    #[must_use = "this returns the result of the comparison, without modifying either input"]
    918    #[stable(feature = "rust1", since = "1.0.0")]
    919    #[rustc_const_stable(feature = "const_float_methods", since = "1.85.0")]
    920    #[inline]
    921    pub const fn max(self, other: f32) -> f32 {
    922        intrinsics::maxnumf32(self, other)
    923    }
    924
    925    /// Returns the minimum of the two numbers, ignoring NaN.
    926    ///
    927    /// If exactly one of the arguments is NaN (quiet or signaling), then the other argument is
    928    /// returned. If both arguments are NaN, the return value is NaN, with the bit pattern picked
    929    /// using the usual [rules for arithmetic operations](f32#nan-bit-patterns). If the inputs
    930    /// compare equal (such as for the case of `+0.0` and `-0.0`), either input may be returned
    931    /// non-deterministically.
    932    ///
    933    /// The handling of NaNs follows the IEEE 754-2019 semantics for `minimumNumber`, treating all
    934    /// NaNs the same way to ensure the operation is associative. The handling of signed zeros
    935    /// follows the IEEE 754-2008 semantics for `minNum`.
    936    ///
    937    /// ```
    938    /// let x = 1.0f32;
    939    /// let y = 2.0f32;
    940    ///
    941    /// assert_eq!(x.min(y), x);
    942    /// assert_eq!(x.min(f32::NAN), x);
    943    /// ```
    944    #[must_use = "this returns the result of the comparison, without modifying either input"]
    945    #[stable(feature = "rust1", since = "1.0.0")]
    946    #[rustc_const_stable(feature = "const_float_methods", since = "1.85.0")]
    947    #[inline]
    948    pub const fn min(self, other: f32) -> f32 {
    949        intrinsics::minnumf32(self, other)
    950    }
    951
    952    /// Returns the maximum of the two numbers, propagating NaN.
    953    ///
    954    /// If at least one of the arguments is NaN, the return value is NaN, with the bit pattern
    955    /// picked using the usual [rules for arithmetic operations](f32#nan-bit-patterns). Furthermore,
    956    /// `-0.0` is considered to be less than `+0.0`, making this function fully deterministic for
    957    /// non-NaN inputs.
    958    ///
    959    /// This is in contrast to [`f32::max`] which only returns NaN when *both* arguments are NaN,
    960    /// and which does not reliably order `-0.0` and `+0.0`.
    961    ///
    962    /// This follows the IEEE 754-2019 semantics for `maximum`.
    963    ///
    964    /// ```
    965    /// #![feature(float_minimum_maximum)]
    966    /// let x = 1.0f32;
    967    /// let y = 2.0f32;
    968    ///
    969    /// assert_eq!(x.maximum(y), y);
    970    /// assert!(x.maximum(f32::NAN).is_nan());
    971    /// ```
    972    #[must_use = "this returns the result of the comparison, without modifying either input"]
    973    #[unstable(feature = "float_minimum_maximum", issue = "91079")]
    974    #[inline]
    975    pub const fn maximum(self, other: f32) -> f32 {
    976        intrinsics::maximumf32(self, other)
    977    }
    978
    979    /// Returns the minimum of the two numbers, propagating NaN.
    980    ///
    981    /// If at least one of the arguments is NaN, the return value is NaN, with the bit pattern
    982    /// picked using the usual [rules for arithmetic operations](f32#nan-bit-patterns). Furthermore,
    983    /// `-0.0` is considered to be less than `+0.0`, making this function fully deterministic for
    984    /// non-NaN inputs.
    985    ///
    986    /// This is in contrast to [`f32::min`] which only returns NaN when *both* arguments are NaN,
    987    /// and which does not reliably order `-0.0` and `+0.0`.
    988    ///
    989    /// This follows the IEEE 754-2019 semantics for `minimum`.
    990    ///
    991    /// ```
    992    /// #![feature(float_minimum_maximum)]
    993    /// let x = 1.0f32;
    994    /// let y = 2.0f32;
    995    ///
    996    /// assert_eq!(x.minimum(y), x);
    997    /// assert!(x.minimum(f32::NAN).is_nan());
    998    /// ```
    999    #[must_use = "this returns the result of the comparison, without modifying either input"]
    1000    #[unstable(feature = "float_minimum_maximum", issue = "91079")]
    1001    #[inline]
    1002    pub const fn minimum(self, other: f32) -> f32 {
    1003        intrinsics::minimumf32(self, other)
    1004    }
    1005
    1006    /// Calculates the midpoint (average) between `self` and `rhs`.
    1007    ///
    1008    /// This returns NaN when *either* argument is NaN or if a combination of
    1009    /// +inf and -inf is provided as arguments.
    1010    ///
    1011    /// # Examples
    1012    ///
    1013    /// ```
    1014    /// assert_eq!(1f32.midpoint(4.0), 2.5);
    1015    /// assert_eq!((-5.5f32).midpoint(8.0), 1.25);
    1016    /// ```
    1017    #[inline]
    1018    #[doc(alias = "average")]
    1019    #[stable(feature = "num_midpoint", since = "1.85.0")]
    1020    #[rustc_const_stable(feature = "num_midpoint", since = "1.85.0")]
    1021    pub const fn midpoint(self, other: f32) -> f32 {
    1022        cfg_select! {
    1023            // Allow faster implementation that have known good 64-bit float
    1024            // implementations. Falling back to the branchy code on targets that don't
    1025            // have 64-bit hardware floats or buggy implementations.
    1026            // https://github.com/rust-lang/rust/pull/121062#issuecomment-2123408114
    1027            any(
    1028                target_arch = "x86_64",
    1029                target_arch = "aarch64",
    1030                all(any(target_arch = "riscv32", target_arch = "riscv64"), target_feature = "d"),
    1031                all(target_arch = "loongarch64", target_feature = "d"),
    1032                all(target_arch = "arm", target_feature = "vfp2"),
    1033                target_arch = "wasm32",
    1034                target_arch = "wasm64",
    1035            ) => {
    1036                ((self as f64 + other as f64) / 2.0) as f32
    1037            }
    1038            _ => {
    1039                const HI: f32 = f32::MAX / 2.;
    1040
    1041                let (a, b) = (self, other);
    1042                let abs_a = a.abs();
    1043                let abs_b = b.abs();
    1044
    1045                if abs_a <= HI && abs_b <= HI {
    1046                    // Overflow is impossible
    1047                    (a + b) / 2.
    1048                } else {
    1049                    (a / 2.) + (b / 2.)
    1050                }
    1051            }
    1052        }
    1053    }
    1054
    1055    /// Rounds toward zero and converts to any primitive integer type,
    1056    /// assuming that the value is finite and fits in that type.
    1057    ///
    1058    /// ```
    1059    /// let value = 4.6_f32;
    1060    /// let rounded = unsafe { value.to_int_unchecked::<u16>() };
    1061    /// assert_eq!(rounded, 4);
    1062    ///
    1063    /// let value = -128.9_f32;
    1064    /// let rounded = unsafe { value.to_int_unchecked::<i8>() };
    1065    /// assert_eq!(rounded, i8::MIN);
    1066    /// ```
    1067    ///
    1068    /// # Safety
    1069    ///
    1070    /// The value must:
    1071    ///
    1072    /// * Not be `NaN`
    1073    /// * Not be infinite
    1074    /// * Be representable in the return type `Int`, after truncating off its fractional part
    1075    #[must_use = "this returns the result of the operation, \
    1076                  without modifying the original"]
    1077    #[stable(feature = "float_approx_unchecked_to", since = "1.44.0")]
    1078    #[inline]
    1079    pub unsafe fn to_int_unchecked<Int>(self) -> Int
    1080    where
    1081        Self: FloatToInt<Int>,
    1082    {
    1083        // SAFETY: the caller must uphold the safety contract for
    1084        // `FloatToInt::to_int_unchecked`.
    1085        unsafe { FloatToInt::<Int>::to_int_unchecked(self) }
    1086    }
    1087
    1088    /// Raw transmutation to `u32`.
    1089    ///
    1090    /// This is currently identical to `transmute::<f32, u32>(self)` on all platforms.
    1091    ///
    1092    /// See [`from_bits`](Self::from_bits) for some discussion of the
    1093    /// portability of this operation (there are almost no issues).
    1094    ///
    1095    /// Note that this function is distinct from `as` casting, which attempts to
    1096    /// preserve the *numeric* value, and not the bitwise value.
    1097    ///
    1098    /// # Examples
    1099    ///
    1100    /// ```
    1101    /// assert_ne!((1f32).to_bits(), 1f32 as u32); // to_bits() is not casting!
    1102    /// assert_eq!((12.5f32).to_bits(), 0x41480000);
    1103    ///
    1104    /// ```
    1105    #[must_use = "this returns the result of the operation, \
    1106                  without modifying the original"]
    1107    #[stable(feature = "float_bits_conv", since = "1.20.0")]
    1108    #[rustc_const_stable(feature = "const_float_bits_conv", since = "1.83.0")]
    1109    #[inline]
    1110    #[allow(unnecessary_transmutes)]
    1111    pub const fn to_bits(self) -> u32 {
    1112        // SAFETY: `u32` is a plain old datatype so we can always transmute to it.
    1113        unsafe { mem::transmute(self) }
    1114    }
    1115
    1116    /// Raw transmutation from `u32`.
    1117    ///
    1118    /// This is currently identical to `transmute::<u32, f32>(v)` on all platforms.
    1119    /// It turns out this is incredibly portable, for two reasons:
    1120    ///
    1121    /// * Floats and Ints have the same endianness on all supported platforms.
    1122    /// * IEEE 754 very precisely specifies the bit layout of floats.
    1123    ///
    1124    /// However there is one caveat: prior to the 2008 version of IEEE 754, how
    1125    /// to interpret the NaN signaling bit wasn't actually specified. Most platforms
    1126    /// (notably x86 and ARM) picked the interpretation that was ultimately
    1127    /// standardized in 2008, but some didn't (notably MIPS). As a result, all
    1128    /// signaling NaNs on MIPS are quiet NaNs on x86, and vice-versa.
    1129    ///
    1130    /// Rather than trying to preserve signaling-ness cross-platform, this
    1131    /// implementation favors preserving the exact bits. This means that
    1132    /// any payloads encoded in NaNs will be preserved even if the result of
    1133    /// this method is sent over the network from an x86 machine to a MIPS one.
    1134    ///
    1135    /// If the results of this method are only manipulated by the same
    1136    /// architecture that produced them, then there is no portability concern.
    1137    ///
    1138    /// If the input isn't NaN, then there is no portability concern.
    1139    ///
    1140    /// If you don't care about signalingness (very likely), then there is no
    1141    /// portability concern.
    1142    ///
    1143    /// Note that this function is distinct from `as` casting, which attempts to
    1144    /// preserve the *numeric* value, and not the bitwise value.
    1145    ///
    1146    /// # Examples
    1147    ///
    1148    /// ```
    1149    /// let v = f32::from_bits(0x41480000);
    1150    /// assert_eq!(v, 12.5);
    1151    /// ```
    1152    #[stable(feature = "float_bits_conv", since = "1.20.0")]
    1153    #[rustc_const_stable(feature = "const_float_bits_conv", since = "1.83.0")]
    1154    #[must_use]
    1155    #[inline]
    1156    #[allow(unnecessary_transmutes)]
    1157    pub const fn from_bits(v: u32) -> Self {
    1158        // It turns out the safety issues with sNaN were overblown! Hooray!
    1159        // SAFETY: `u32` is a plain old datatype so we can always transmute from it.
    1160        unsafe { mem::transmute(v) }
    1161    }
    1162
    1163    /// Returns the memory representation of this floating point number as a byte array in
    1164    /// big-endian (network) byte order.
    1165    ///
    1166    /// See [`from_bits`](Self::from_bits) for some discussion of the
    1167    /// portability of this operation (there are almost no issues).
    1168    ///
    1169    /// # Examples
    1170    ///
    1171    /// ```
    1172    /// let bytes = 12.5f32.to_be_bytes();
    1173    /// assert_eq!(bytes, [0x41, 0x48, 0x00, 0x00]);
    1174    /// ```
    1175    #[must_use = "this returns the result of the operation, \
    1176                  without modifying the original"]
    1177    #[stable(feature = "float_to_from_bytes", since = "1.40.0")]
    1178    #[rustc_const_stable(feature = "const_float_bits_conv", since = "1.83.0")]
    1179    #[inline]
    1180    pub const fn to_be_bytes(self) -> [u8; 4] {
    1181        self.to_bits().to_be_bytes()
    1182    }
    1183
    1184    /// Returns the memory representation of this floating point number as a byte array in
    1185    /// little-endian byte order.
    1186    ///
    1187    /// See [`from_bits`](Self::from_bits) for some discussion of the
    1188    /// portability of this operation (there are almost no issues).
    1189    ///
    1190    /// # Examples
    1191    ///
    1192    /// ```
    1193    /// let bytes = 12.5f32.to_le_bytes();
    1194    /// assert_eq!(bytes, [0x00, 0x00, 0x48, 0x41]);
    1195    /// ```
    1196    #[must_use = "this returns the result of the operation, \
    1197                  without modifying the original"]
    1198    #[stable(feature = "float_to_from_bytes", since = "1.40.0")]
    1199    #[rustc_const_stable(feature = "const_float_bits_conv", since = "1.83.0")]
    1200    #[inline]
    1201    pub const fn to_le_bytes(self) -> [u8; 4] {
    1202        self.to_bits().to_le_bytes()
    1203    }
    1204
    1205    /// Returns the memory representation of this floating point number as a byte array in
    1206    /// native byte order.
    1207    ///
    1208    /// As the target platform's native endianness is used, portable code
    1209    /// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate, instead.
    1210    ///
    1211    /// [`to_be_bytes`]: f32::to_be_bytes
    1212    /// [`to_le_bytes`]: f32::to_le_bytes
    1213    ///
    1214    /// See [`from_bits`](Self::from_bits) for some discussion of the
    1215    /// portability of this operation (there are almost no issues).
    1216    ///
    1217    /// # Examples
    1218    ///
    1219    /// ```
    1220    /// let bytes = 12.5f32.to_ne_bytes();
    1221    /// assert_eq!(
    1222    ///     bytes,
    1223    ///     if cfg!(target_endian = "big") {
    1224    ///         [0x41, 0x48, 0x00, 0x00]
    1225    ///     } else {
    1226    ///         [0x00, 0x00, 0x48, 0x41]
    1227    ///     }
    1228    /// );
    1229    /// ```
    1230    #[must_use = "this returns the result of the operation, \
    1231                  without modifying the original"]
    1232    #[stable(feature = "float_to_from_bytes", since = "1.40.0")]
    1233    #[rustc_const_stable(feature = "const_float_bits_conv", since = "1.83.0")]
    1234    #[inline]
    1235    pub const fn to_ne_bytes(self) -> [u8; 4] {
    1236        self.to_bits().to_ne_bytes()
    1237    }
    1238
    1239    /// Creates a floating point value from its representation as a byte array in big endian.
    1240    ///
    1241    /// See [`from_bits`](Self::from_bits) for some discussion of the
    1242    /// portability of this operation (there are almost no issues).
    1243    ///
    1244    /// # Examples
    1245    ///
    1246    /// ```
    1247    /// let value = f32::from_be_bytes([0x41, 0x48, 0x00, 0x00]);
    1248    /// assert_eq!(value, 12.5);
    1249    /// ```
    1250    #[stable(feature = "float_to_from_bytes", since = "1.40.0")]
    1251    #[rustc_const_stable(feature = "const_float_bits_conv", since = "1.83.0")]
    1252    #[must_use]
    1253    #[inline]
    1254    pub const fn from_be_bytes(bytes: [u8; 4]) -> Self {
    1255        Self::from_bits(u32::from_be_bytes(bytes))
    1256    }
    1257
    1258    /// Creates a floating point value from its representation as a byte array in little endian.
    1259    ///
    1260    /// See [`from_bits`](Self::from_bits) for some discussion of the
    1261    /// portability of this operation (there are almost no issues).
    1262    ///
    1263    /// # Examples
    1264    ///
    1265    /// ```
    1266    /// let value = f32::from_le_bytes([0x00, 0x00, 0x48, 0x41]);
    1267    /// assert_eq!(value, 12.5);
    1268    /// ```
    1269    #[stable(feature = "float_to_from_bytes", since = "1.40.0")]
    1270    #[rustc_const_stable(feature = "const_float_bits_conv", since = "1.83.0")]
    1271    #[must_use]
    1272    #[inline]
    1273    pub const fn from_le_bytes(bytes: [u8; 4]) -> Self {
    1274        Self::from_bits(u32::from_le_bytes(bytes))
    1275    }
    1276
    1277    /// Creates a floating point value from its representation as a byte array in native endian.
    1278    ///
    1279    /// As the target platform's native endianness is used, portable code
    1280    /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
    1281    /// appropriate instead.
    1282    ///
    1283    /// [`from_be_bytes`]: f32::from_be_bytes
    1284    /// [`from_le_bytes`]: f32::from_le_bytes
    1285    ///
    1286    /// See [`from_bits`](Self::from_bits) for some discussion of the
    1287    /// portability of this operation (there are almost no issues).
    1288    ///
    1289    /// # Examples
    1290    ///
    1291    /// ```
    1292    /// let value = f32::from_ne_bytes(if cfg!(target_endian = "big") {
    1293    ///     [0x41, 0x48, 0x00, 0x00]
    1294    /// } else {
    1295    ///     [0x00, 0x00, 0x48, 0x41]
    1296    /// });
    1297    /// assert_eq!(value, 12.5);
    1298    /// ```
    1299    #[stable(feature = "float_to_from_bytes", since = "1.40.0")]
    1300    #[rustc_const_stable(feature = "const_float_bits_conv", since = "1.83.0")]
    1301    #[must_use]
    1302    #[inline]
    1303    pub const fn from_ne_bytes(bytes: [u8; 4]) -> Self {
    1304        Self::from_bits(u32::from_ne_bytes(bytes))
    1305    }
    1306
    1307    /// Returns the ordering between `self` and `other`.
    1308    ///
    1309    /// Unlike the standard partial comparison between floating point numbers,
    1310    /// this comparison always produces an ordering in accordance to
    1311    /// the `totalOrder` predicate as defined in the IEEE 754 (2008 revision)
    1312    /// floating point standard. The values are ordered in the following sequence:
    1313    ///
    1314    /// - negative quiet NaN
    1315    /// - negative signaling NaN
    1316    /// - negative infinity
    1317    /// - negative numbers
    1318    /// - negative subnormal numbers
    1319    /// - negative zero
    1320    /// - positive zero
    1321    /// - positive subnormal numbers
    1322    /// - positive numbers
    1323    /// - positive infinity
    1324    /// - positive signaling NaN
    1325    /// - positive quiet NaN.
    1326    ///
    1327    /// The ordering established by this function does not always agree with the
    1328    /// [`PartialOrd`] and [`PartialEq`] implementations of `f32`. For example,
    1329    /// they consider negative and positive zero equal, while `total_cmp`
    1330    /// doesn't.
    1331    ///
    1332    /// The interpretation of the signaling NaN bit follows the definition in
    1333    /// the IEEE 754 standard, which may not match the interpretation by some of
    1334    /// the older, non-conformant (e.g. MIPS) hardware implementations.
    1335    ///
    1336    /// # Example
    1337    ///
    1338    /// ```
    1339    /// struct GoodBoy {
    1340    ///     name: String,
    1341    ///     weight: f32,
    1342    /// }
    1343    ///
    1344    /// let mut bois = vec![
    1345    ///     GoodBoy { name: "Pucci".to_owned(), weight: 0.1 },
    1346    ///     GoodBoy { name: "Woofer".to_owned(), weight: 99.0 },
    1347    ///     GoodBoy { name: "Yapper".to_owned(), weight: 10.0 },
    1348    ///     GoodBoy { name: "Chonk".to_owned(), weight: f32::INFINITY },
    1349    ///     GoodBoy { name: "Abs. Unit".to_owned(), weight: f32::NAN },
    1350    ///     GoodBoy { name: "Floaty".to_owned(), weight: -5.0 },
    1351    /// ];
    1352    ///
    1353    /// bois.sort_by(|a, b| a.weight.total_cmp(&b.weight));
    1354    ///
    1355    /// // `f32::NAN` could be positive or negative, which will affect the sort order.
    1356    /// if f32::NAN.is_sign_negative() {
    1357    ///     assert!(bois.into_iter().map(|b| b.weight)
    1358    ///         .zip([f32::NAN, -5.0, 0.1, 10.0, 99.0, f32::INFINITY].iter())
    1359    ///         .all(|(a, b)| a.to_bits() == b.to_bits()))
    1360    /// } else {
    1361    ///     assert!(bois.into_iter().map(|b| b.weight)
    1362    ///         .zip([-5.0, 0.1, 10.0, 99.0, f32::INFINITY, f32::NAN].iter())
    1363    ///         .all(|(a, b)| a.to_bits() == b.to_bits()))
    1364    /// }
    1365    /// ```
    1366    #[stable(feature = "total_cmp", since = "1.62.0")]
    1367    #[rustc_const_unstable(feature = "const_cmp", issue = "143800")]
    1368    #[must_use]
    1369    #[inline]
    1370    pub const fn total_cmp(&self, other: &Self) -> crate::cmp::Ordering {
    1371        let mut left = self.to_bits() as i32;
    1372        let mut right = other.to_bits() as i32;
    1373
    1374        // In case of negatives, flip all the bits except the sign
    1375        // to achieve a similar layout as two's complement integers
    1376        //
    1377        // Why does this work? IEEE 754 floats consist of three fields:
    1378        // Sign bit, exponent and mantissa. The set of exponent and mantissa
    1379        // fields as a whole have the property that their bitwise order is
    1380        // equal to the numeric magnitude where the magnitude is defined.
    1381        // The magnitude is not normally defined on NaN values, but
    1382        // IEEE 754 totalOrder defines the NaN values also to follow the
    1383        // bitwise order. This leads to order explained in the doc comment.
    1384        // However, the representation of magnitude is the same for negative
    1385        // and positive numbers – only the sign bit is different.
    1386        // To easily compare the floats as signed integers, we need to
    1387        // flip the exponent and mantissa bits in case of negative numbers.
    1388        // We effectively convert the numbers to "two's complement" form.
    1389        //
    1390        // To do the flipping, we construct a mask and XOR against it.
    1391        // We branchlessly calculate an "all-ones except for the sign bit"
    1392        // mask from negative-signed values: right shifting sign-extends
    1393        // the integer, so we "fill" the mask with sign bits, and then
    1394        // convert to unsigned to push one more zero bit.
    1395        // On positive values, the mask is all zeros, so it's a no-op.
    1396        left ^= (((left >> 31) as u32) >> 1) as i32;
    1397        right ^= (((right >> 31) as u32) >> 1) as i32;
    1398
    1399        left.cmp(&right)
    1400    }
    1401
    1402    /// Restrict a value to a certain interval unless it is NaN.
    1403    ///
    1404    /// Returns `max` if `self` is greater than `max`, and `min` if `self` is
    1405    /// less than `min`. Otherwise this returns `self`.
    1406    ///
    1407    /// Note that this function returns NaN if the initial value was NaN as
    1408    /// well. If the result is zero and among the three inputs `self`, `min`, and `max` there are
    1409    /// zeros with different sign, either `0.0` or `-0.0` is returned non-deterministically.
    1410    ///
    1411    /// # Panics
    1412    ///
    1413    /// Panics if `min > max`, `min` is NaN, or `max` is NaN.
    1414    ///
    1415    /// # Examples
    1416    ///
    1417    /// ```
    1418    /// assert!((-3.0f32).clamp(-2.0, 1.0) == -2.0);
    1419    /// assert!((0.0f32).clamp(-2.0, 1.0) == 0.0);
    1420    /// assert!((2.0f32).clamp(-2.0, 1.0) == 1.0);
    1421    /// assert!((f32::NAN).clamp(-2.0, 1.0).is_nan());
    1422    ///
    1423    /// // These always returns zero, but the sign (which is ignored by `==`) is non-deterministic.
    1424    /// assert!((0.0f32).clamp(-0.0, -0.0) == 0.0);
    1425    /// assert!((1.0f32).clamp(-0.0, 0.0) == 0.0);
    1426    /// // This is definitely a negative zero.
    1427    /// assert!((-1.0f32).clamp(-0.0, 1.0).is_sign_negative());
    1428    /// ```
    1429    #[must_use = "method returns a new number and does not mutate the original value"]
    1430    #[stable(feature = "clamp", since = "1.50.0")]
    1431    #[rustc_const_stable(feature = "const_float_methods", since = "1.85.0")]
    1432    #[inline]
    1433    pub const fn clamp(mut self, min: f32, max: f32) -> f32 {
    1434        const_assert!(
    1435            min <= max,
    1436            "min > max, or either was NaN",
    1437            "min > max, or either was NaN. min = {min:?}, max = {max:?}",
    1438            min: f32,
    1439            max: f32,
    1440        );
    1441
    1442        if self < min {
    1443            self = min;
    1444        }
    1445        if self > max {
    1446            self = max;
    1447        }
    1448        self
    1449    }
    1450
    1451    /// Clamps this number to a symmetric range centered around zero.
    1452    ///
    1453    /// The method clamps the number's magnitude (absolute value) to be at most `limit`.
    1454    ///
    1455    /// This is functionally equivalent to `self.clamp(-limit, limit)`, but is more
    1456    /// explicit about the intent.
    1457    ///
    1458    /// # Panics
    1459    ///
    1460    /// Panics if `limit` is negative or NaN, as this indicates a logic error.
    1461    ///
    1462    /// # Examples
    1463    ///
    1464    /// ```
    1465    /// #![feature(clamp_magnitude)]
    1466    /// assert_eq!(5.0f32.clamp_magnitude(3.0), 3.0);
    1467    /// assert_eq!((-5.0f32).clamp_magnitude(3.0), -3.0);
    1468    /// assert_eq!(2.0f32.clamp_magnitude(3.0), 2.0);
    1469    /// assert_eq!((-2.0f32).clamp_magnitude(3.0), -2.0);
    1470    /// ```
    1471    #[must_use = "this returns the clamped value and does not modify the original"]
    1472    #[unstable(feature = "clamp_magnitude", issue = "148519")]
    1473    #[inline]
    1474    pub fn clamp_magnitude(self, limit: f32) -> f32 {
    1475        assert!(limit >= 0.0, "limit must be non-negative");
    1476        let limit = limit.abs(); // Canonicalises -0.0 to 0.0
    1477        self.clamp(-limit, limit)
    1478    }
    1479
    1480    /// Computes the absolute value of `self`.
    1481    ///
    1482    /// This function always returns the precise result.
    1483    ///
    1484    /// # Examples
    1485    ///
    1486    /// ```
    1487    /// let x = 3.5_f32;
    1488    /// let y = -3.5_f32;
    1489    ///
    1490    /// assert_eq!(x.abs(), x);
    1491    /// assert_eq!(y.abs(), -y);
    1492    ///
    1493    /// assert!(f32::NAN.abs().is_nan());
    1494    /// ```
    1495    #[must_use = "method returns a new number and does not mutate the original value"]
    1496    #[stable(feature = "rust1", since = "1.0.0")]
    1497    #[rustc_const_stable(feature = "const_float_methods", since = "1.85.0")]
    1498    #[inline]
    1499    pub const fn abs(self) -> f32 {
    1500        intrinsics::fabsf32(self)
    1501    }
    1502
    1503    /// Returns a number that represents the sign of `self`.
    1504    ///
    1505    /// - `1.0` if the number is positive, `+0.0` or `INFINITY`
    1506    /// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY`
    1507    /// - NaN if the number is NaN
    1508    ///
    1509    /// # Examples
    1510    ///
    1511    /// ```
    1512    /// let f = 3.5_f32;
    1513    ///
    1514    /// assert_eq!(f.signum(), 1.0);
    1515    /// assert_eq!(f32::NEG_INFINITY.signum(), -1.0);
    1516    ///
    1517    /// assert!(f32::NAN.signum().is_nan());
    1518    /// ```
    1519    #[must_use = "method returns a new number and does not mutate the original value"]
    1520    #[stable(feature = "rust1", since = "1.0.0")]
    1521    #[rustc_const_stable(feature = "const_float_methods", since = "1.85.0")]
    1522    #[inline]
    1523    pub const fn signum(self) -> f32 {
    1524        if self.is_nan() { Self::NAN } else { 1.0_f32.copysign(self) }
    1525    }
    1526
    1527    /// Returns a number composed of the magnitude of `self` and the sign of
    1528    /// `sign`.
    1529    ///
    1530    /// Equal to `self` if the sign of `self` and `sign` are the same, otherwise equal to `-self`.
    1531    /// If `self` is a NaN, then a NaN with the same payload as `self` and the sign bit of `sign` is
    1532    /// returned.
    1533    ///
    1534    /// If `sign` is a NaN, then this operation will still carry over its sign into the result. Note
    1535    /// that IEEE 754 doesn't assign any meaning to the sign bit in case of a NaN, and as Rust
    1536    /// doesn't guarantee that the bit pattern of NaNs are conserved over arithmetic operations, the
    1537    /// result of `copysign` with `sign` being a NaN might produce an unexpected or non-portable
    1538    /// result. See the [specification of NaN bit patterns](primitive@f32#nan-bit-patterns) for more
    1539    /// info.
    1540    ///
    1541    /// # Examples
    1542    ///
    1543    /// ```
    1544    /// let f = 3.5_f32;
    1545    ///
    1546    /// assert_eq!(f.copysign(0.42), 3.5_f32);
    1547    /// assert_eq!(f.copysign(-0.42), -3.5_f32);
    1548    /// assert_eq!((-f).copysign(0.42), 3.5_f32);
    1549    /// assert_eq!((-f).copysign(-0.42), -3.5_f32);
    1550    ///
    1551    /// assert!(f32::NAN.copysign(1.0).is_nan());
    1552    /// ```
    1553    #[must_use = "method returns a new number and does not mutate the original value"]
    1554    #[inline]
    1555    #[stable(feature = "copysign", since = "1.35.0")]
    1556    #[rustc_const_stable(feature = "const_float_methods", since = "1.85.0")]
    1557    pub const fn copysign(self, sign: f32) -> f32 {
    1558        intrinsics::copysignf32(self, sign)
    1559    }
    1560
    1561    /// Float addition that allows optimizations based on algebraic rules.
    1562    ///
    1563    /// See [algebraic operators](primitive@f32#algebraic-operators) for more info.
    1564    #[must_use = "method returns a new number and does not mutate the original value"]
    1565    #[unstable(feature = "float_algebraic", issue = "136469")]
    1566    #[rustc_const_unstable(feature = "float_algebraic", issue = "136469")]
    1567    #[inline]
    1568    pub const fn algebraic_add(self, rhs: f32) -> f32 {
    1569        intrinsics::fadd_algebraic(self, rhs)
    1570    }
    1571
    1572    /// Float subtraction that allows optimizations based on algebraic rules.
    1573    ///
    1574    /// See [algebraic operators](primitive@f32#algebraic-operators) for more info.
    1575    #[must_use = "method returns a new number and does not mutate the original value"]
    1576    #[unstable(feature = "float_algebraic", issue = "136469")]
    1577    #[rustc_const_unstable(feature = "float_algebraic", issue = "136469")]
    1578    #[inline]
    1579    pub const fn algebraic_sub(self, rhs: f32) -> f32 {
    1580        intrinsics::fsub_algebraic(self, rhs)
    1581    }
    1582
    1583    /// Float multiplication that allows optimizations based on algebraic rules.
    1584    ///
    1585    /// See [algebraic operators](primitive@f32#algebraic-operators) for more info.
    1586    #[must_use = "method returns a new number and does not mutate the original value"]
    1587    #[unstable(feature = "float_algebraic", issue = "136469")]
    1588    #[rustc_const_unstable(feature = "float_algebraic", issue = "136469")]
    1589    #[inline]
    1590    pub const fn algebraic_mul(self, rhs: f32) -> f32 {
    1591        intrinsics::fmul_algebraic(self, rhs)
    1592    }
    1593
    1594    /// Float division that allows optimizations based on algebraic rules.
    1595    ///
    1596    /// See [algebraic operators](primitive@f32#algebraic-operators) for more info.
    1597    #[must_use = "method returns a new number and does not mutate the original value"]
    1598    #[unstable(feature = "float_algebraic", issue = "136469")]
    1599    #[rustc_const_unstable(feature = "float_algebraic", issue = "136469")]
    1600    #[inline]
    1601    pub const fn algebraic_div(self, rhs: f32) -> f32 {
    1602        intrinsics::fdiv_algebraic(self, rhs)
    1603    }
    1604
    1605    /// Float remainder that allows optimizations based on algebraic rules.
    1606    ///
    1607    /// See [algebraic operators](primitive@f32#algebraic-operators) for more info.
    1608    #[must_use = "method returns a new number and does not mutate the original value"]
    1609    #[unstable(feature = "float_algebraic", issue = "136469")]
    1610    #[rustc_const_unstable(feature = "float_algebraic", issue = "136469")]
    1611    #[inline]
    1612    pub const fn algebraic_rem(self, rhs: f32) -> f32 {
    1613        intrinsics::frem_algebraic(self, rhs)
    1614    }
    1615}
    1616
    1617/// Experimental implementations of floating point functions in `core`.
    1618///
    1619/// _The standalone functions in this module are for testing only.
    1620/// They will be stabilized as inherent methods._
    1621#[unstable(feature = "core_float_math", issue = "137578")]
    1622pub mod math {
    1623    use crate::intrinsics;
    1624    use crate::num::libm;
    1625
    1626    /// Experimental version of `floor` in `core`. See [`f32::floor`] for details.
    1627    ///
    1628    /// # Examples
    1629    ///
    1630    /// ```
    1631    /// #![feature(core_float_math)]
    1632    ///
    1633    /// use core::f32;
    1634    ///
    1635    /// let f = 3.7_f32;
    1636    /// let g = 3.0_f32;
    1637    /// let h = -3.7_f32;
    1638    ///
    1639    /// assert_eq!(f32::math::floor(f), 3.0);
    1640    /// assert_eq!(f32::math::floor(g), 3.0);
    1641    /// assert_eq!(f32::math::floor(h), -4.0);
    1642    /// ```
    1643    ///
    1644    /// _This standalone function is for testing only.
    1645    /// It will be stabilized as an inherent method._
    1646    ///
    1647    /// [`f32::floor`]: ../../../std/primitive.f32.html#method.floor
    1648    #[inline]
    1649    #[unstable(feature = "core_float_math", issue = "137578")]
    1650    #[must_use = "method returns a new number and does not mutate the original value"]
    1651    pub const fn floor(x: f32) -> f32 {
    1652        intrinsics::floorf32(x)
    1653    }
    1654
    1655    /// Experimental version of `ceil` in `core`. See [`f32::ceil`] for details.
    1656    ///
    1657    /// # Examples
    1658    ///
    1659    /// ```
    1660    /// #![feature(core_float_math)]
    1661    ///
    1662    /// use core::f32;
    1663    ///
    1664    /// let f = 3.01_f32;
    1665    /// let g = 4.0_f32;
    1666    ///
    1667    /// assert_eq!(f32::math::ceil(f), 4.0);
    1668    /// assert_eq!(f32::math::ceil(g), 4.0);
    1669    /// ```
    1670    ///
    1671    /// _This standalone function is for testing only.
    1672    /// It will be stabilized as an inherent method._
    1673    ///
    1674    /// [`f32::ceil`]: ../../../std/primitive.f32.html#method.ceil
    1675    #[inline]
    1676    #[doc(alias = "ceiling")]
    1677    #[must_use = "method returns a new number and does not mutate the original value"]
    1678    #[unstable(feature = "core_float_math", issue = "137578")]
    1679    pub const fn ceil(x: f32) -> f32 {
    1680        intrinsics::ceilf32(x)
    1681    }
    1682
    1683    /// Experimental version of `round` in `core`. See [`f32::round`] for details.
    1684    ///
    1685    /// # Examples
    1686    ///
    1687    /// ```
    1688    /// #![feature(core_float_math)]
    1689    ///
    1690    /// use core::f32;
    1691    ///
    1692    /// let f = 3.3_f32;
    1693    /// let g = -3.3_f32;
    1694    /// let h = -3.7_f32;
    1695    /// let i = 3.5_f32;
    1696    /// let j = 4.5_f32;
    1697    ///
    1698    /// assert_eq!(f32::math::round(f), 3.0);
    1699    /// assert_eq!(f32::math::round(g), -3.0);
    1700    /// assert_eq!(f32::math::round(h), -4.0);
    1701    /// assert_eq!(f32::math::round(i), 4.0);
    1702    /// assert_eq!(f32::math::round(j), 5.0);
    1703    /// ```
    1704    ///
    1705    /// _This standalone function is for testing only.
    1706    /// It will be stabilized as an inherent method._
    1707    ///
    1708    /// [`f32::round`]: ../../../std/primitive.f32.html#method.round
    1709    #[inline]
    1710    #[unstable(feature = "core_float_math", issue = "137578")]
    1711    #[must_use = "method returns a new number and does not mutate the original value"]
    1712    pub const fn round(x: f32) -> f32 {
    1713        intrinsics::roundf32(x)
    1714    }
    1715
    1716    /// Experimental version of `round_ties_even` in `core`. See [`f32::round_ties_even`] for
    1717    /// details.
    1718    ///
    1719    /// # Examples
    1720    ///
    1721    /// ```
    1722    /// #![feature(core_float_math)]
    1723    ///
    1724    /// use core::f32;
    1725    ///
    1726    /// let f = 3.3_f32;
    1727    /// let g = -3.3_f32;
    1728    /// let h = 3.5_f32;
    1729    /// let i = 4.5_f32;
    1730    ///
    1731    /// assert_eq!(f32::math::round_ties_even(f), 3.0);
    1732    /// assert_eq!(f32::math::round_ties_even(g), -3.0);
    1733    /// assert_eq!(f32::math::round_ties_even(h), 4.0);
    1734    /// assert_eq!(f32::math::round_ties_even(i), 4.0);
    1735    /// ```
    1736    ///
    1737    /// _This standalone function is for testing only.
    1738    /// It will be stabilized as an inherent method._
    1739    ///
    1740    /// [`f32::round_ties_even`]: ../../../std/primitive.f32.html#method.round_ties_even
    1741    #[inline]
    1742    #[unstable(feature = "core_float_math", issue = "137578")]
    1743    #[must_use = "method returns a new number and does not mutate the original value"]
    1744    pub const fn round_ties_even(x: f32) -> f32 {
    1745        intrinsics::round_ties_even_f32(x)
    1746    }
    1747
    1748    /// Experimental version of `trunc` in `core`. See [`f32::trunc`] for details.
    1749    ///
    1750    /// # Examples
    1751    ///
    1752    /// ```
    1753    /// #![feature(core_float_math)]
    1754    ///
    1755    /// use core::f32;
    1756    ///
    1757    /// let f = 3.7_f32;
    1758    /// let g = 3.0_f32;
    1759    /// let h = -3.7_f32;
    1760    ///
    1761    /// assert_eq!(f32::math::trunc(f), 3.0);
    1762    /// assert_eq!(f32::math::trunc(g), 3.0);
    1763    /// assert_eq!(f32::math::trunc(h), -3.0);
    1764    /// ```
    1765    ///
    1766    /// _This standalone function is for testing only.
    1767    /// It will be stabilized as an inherent method._
    1768    ///
    1769    /// [`f32::trunc`]: ../../../std/primitive.f32.html#method.trunc
    1770    #[inline]
    1771    #[doc(alias = "truncate")]
    1772    #[must_use = "method returns a new number and does not mutate the original value"]
    1773    #[unstable(feature = "core_float_math", issue = "137578")]
    1774    pub const fn trunc(x: f32) -> f32 {
    1775        intrinsics::truncf32(x)
    1776    }
    1777
    1778    /// Experimental version of `fract` in `core`. See [`f32::fract`] for details.
    1779    ///
    1780    /// # Examples
    1781    ///
    1782    /// ```
    1783    /// #![feature(core_float_math)]
    1784    ///
    1785    /// use core::f32;
    1786    ///
    1787    /// let x = 3.6_f32;
    1788    /// let y = -3.6_f32;
    1789    /// let abs_difference_x = (f32::math::fract(x) - 0.6).abs();
    1790    /// let abs_difference_y = (f32::math::fract(y) - (-0.6)).abs();
    1791    ///
    1792    /// assert!(abs_difference_x <= f32::EPSILON);
    1793    /// assert!(abs_difference_y <= f32::EPSILON);
    1794    /// ```
    1795    ///
    1796    /// _This standalone function is for testing only.
    1797    /// It will be stabilized as an inherent method._
    1798    ///
    1799    /// [`f32::fract`]: ../../../std/primitive.f32.html#method.fract
    1800    #[inline]
    1801    #[unstable(feature = "core_float_math", issue = "137578")]
    1802    #[must_use = "method returns a new number and does not mutate the original value"]
    1803    pub const fn fract(x: f32) -> f32 {
    1804        x - trunc(x)
    1805    }
    1806
    1807    /// Experimental version of `mul_add` in `core`. See [`f32::mul_add`] for details.
    1808    ///
    1809    /// # Examples
    1810    ///
    1811    /// ```
    1812    /// #![feature(core_float_math)]
    1813    ///
    1814    /// # // FIXME(#140515): mingw has an incorrect fma
    1815    /// # // https://sourceforge.net/p/mingw-w64/bugs/848/
    1816    /// # #[cfg(all(target_os = "windows", target_env = "gnu", not(target_abi = "llvm")))] {
    1817    /// use core::f32;
    1818    ///
    1819    /// let m = 10.0_f32;
    1820    /// let x = 4.0_f32;
    1821    /// let b = 60.0_f32;
    1822    ///
    1823    /// assert_eq!(f32::math::mul_add(m, x, b), 100.0);
    1824    /// assert_eq!(m * x + b, 100.0);
    1825    ///
    1826    /// let one_plus_eps = 1.0_f32 + f32::EPSILON;
    1827    /// let one_minus_eps = 1.0_f32 - f32::EPSILON;
    1828    /// let minus_one = -1.0_f32;
    1829    ///
    1830    /// // The exact result (1 + eps) * (1 - eps) = 1 - eps * eps.
    1831    /// assert_eq!(
    1832    ///     f32::math::mul_add(one_plus_eps, one_minus_eps, minus_one),
    1833    ///     -f32::EPSILON * f32::EPSILON
    1834    /// );
    1835    /// // Different rounding with the non-fused multiply and add.
    1836    /// assert_eq!(one_plus_eps * one_minus_eps + minus_one, 0.0);
    1837    /// # }
    1838    /// ```
    1839    ///
    1840    /// _This standalone function is for testing only.
    1841    /// It will be stabilized as an inherent method._
    1842    ///
    1843    /// [`f32::mul_add`]: ../../../std/primitive.f32.html#method.mul_add
    1844    #[inline]
    1845    #[doc(alias = "fmaf", alias = "fusedMultiplyAdd")]
    1846    #[must_use = "method returns a new number and does not mutate the original value"]
    1847    #[unstable(feature = "core_float_math", issue = "137578")]
    1848    pub const fn mul_add(x: f32, y: f32, z: f32) -> f32 {
    1849        intrinsics::fmaf32(x, y, z)
    1850    }
    1851
    1852    /// Experimental version of `div_euclid` in `core`. See [`f32::div_euclid`] for details.
    1853    ///
    1854    /// # Examples
    1855    ///
    1856    /// ```
    1857    /// #![feature(core_float_math)]
    1858    ///
    1859    /// use core::f32;
    1860    ///
    1861    /// let a: f32 = 7.0;
    1862    /// let b = 4.0;
    1863    /// assert_eq!(f32::math::div_euclid(a, b), 1.0); // 7.0 > 4.0 * 1.0
    1864    /// assert_eq!(f32::math::div_euclid(-a, b), -2.0); // -7.0 >= 4.0 * -2.0
    1865    /// assert_eq!(f32::math::div_euclid(a, -b), -1.0); // 7.0 >= -4.0 * -1.0
    1866    /// assert_eq!(f32::math::div_euclid(-a, -b), 2.0); // -7.0 >= -4.0 * 2.0
    1867    /// ```
    1868    ///
    1869    /// _This standalone function is for testing only.
    1870    /// It will be stabilized as an inherent method._
    1871    ///
    1872    /// [`f32::div_euclid`]: ../../../std/primitive.f32.html#method.div_euclid
    1873    #[inline]
    1874    #[unstable(feature = "core_float_math", issue = "137578")]
    1875    #[must_use = "method returns a new number and does not mutate the original value"]
    1876    pub fn div_euclid(x: f32, rhs: f32) -> f32 {
    1877        let q = trunc(x / rhs);
    1878        if x % rhs < 0.0 {
    1879            return if rhs > 0.0 { q - 1.0 } else { q + 1.0 };
    1880        }
    1881        q
    1882    }
    1883
    1884    /// Experimental version of `rem_euclid` in `core`. See [`f32::rem_euclid`] for details.
    1885    ///
    1886    /// # Examples
    1887    ///
    1888    /// ```
    1889    /// #![feature(core_float_math)]
    1890    ///
    1891    /// use core::f32;
    1892    ///
    1893    /// let a: f32 = 7.0;
    1894    /// let b = 4.0;
    1895    /// assert_eq!(f32::math::rem_euclid(a, b), 3.0);
    1896    /// assert_eq!(f32::math::rem_euclid(-a, b), 1.0);
    1897    /// assert_eq!(f32::math::rem_euclid(a, -b), 3.0);
    1898    /// assert_eq!(f32::math::rem_euclid(-a, -b), 1.0);
    1899    /// // limitation due to round-off error
    1900    /// assert!(f32::math::rem_euclid(-f32::EPSILON, 3.0) != 0.0);
    1901    /// ```
    1902    ///
    1903    /// _This standalone function is for testing only.
    1904    /// It will be stabilized as an inherent method._
    1905    ///
    1906    /// [`f32::rem_euclid`]: ../../../std/primitive.f32.html#method.rem_euclid
    1907    #[inline]
    1908    #[doc(alias = "modulo", alias = "mod")]
    1909    #[unstable(feature = "core_float_math", issue = "137578")]
    1910    #[must_use = "method returns a new number and does not mutate the original value"]
    1911    pub fn rem_euclid(x: f32, rhs: f32) -> f32 {
    1912        let r = x % rhs;
    1913        if r < 0.0 { r + rhs.abs() } else { r }
    1914    }
    1915
    1916    /// Experimental version of `powi` in `core`. See [`f32::powi`] for details.
    1917    ///
    1918    /// # Examples
    1919    ///
    1920    /// ```
    1921    /// #![feature(core_float_math)]
    1922    ///
    1923    /// use core::f32;
    1924    ///
    1925    /// let x = 2.0_f32;
    1926    /// let abs_difference = (f32::math::powi(x, 2) - (x * x)).abs();
    1927    /// assert!(abs_difference <= 1e-5);
    1928    ///
    1929    /// assert_eq!(f32::math::powi(f32::NAN, 0), 1.0);
    1930    /// ```
    1931    ///
    1932    /// _This standalone function is for testing only.
    1933    /// It will be stabilized as an inherent method._
    1934    ///
    1935    /// [`f32::powi`]: ../../../std/primitive.f32.html#method.powi
    1936    #[inline]
    1937    #[must_use = "method returns a new number and does not mutate the original value"]
    1938    #[unstable(feature = "core_float_math", issue = "137578")]
    1939    pub fn powi(x: f32, n: i32) -> f32 {
    1940        intrinsics::powif32(x, n)
    1941    }
    1942
    1943    /// Experimental version of `sqrt` in `core`. See [`f32::sqrt`] for details.
    1944    ///
    1945    /// # Examples
    1946    ///
    1947    /// ```
    1948    /// #![feature(core_float_math)]
    1949    ///
    1950    /// use core::f32;
    1951    ///
    1952    /// let positive = 4.0_f32;
    1953    /// let negative = -4.0_f32;
    1954    /// let negative_zero = -0.0_f32;
    1955    ///
    1956    /// assert_eq!(f32::math::sqrt(positive), 2.0);
    1957    /// assert!(f32::math::sqrt(negative).is_nan());
    1958    /// assert_eq!(f32::math::sqrt(negative_zero), negative_zero);
    1959    /// ```
    1960    ///
    1961    /// _This standalone function is for testing only.
    1962    /// It will be stabilized as an inherent method._
    1963    ///
    1964    /// [`f32::sqrt`]: ../../../std/primitive.f32.html#method.sqrt
    1965    #[inline]
    1966    #[doc(alias = "squareRoot")]
    1967    #[unstable(feature = "core_float_math", issue = "137578")]
    1968    #[must_use = "method returns a new number and does not mutate the original value"]
    1969    pub fn sqrt(x: f32) -> f32 {
    1970        intrinsics::sqrtf32(x)
    1971    }
    1972
    1973    /// Experimental version of `abs_sub` in `core`. See [`f32::abs_sub`] for details.
    1974    ///
    1975    /// # Examples
    1976    ///
    1977    /// ```
    1978    /// #![feature(core_float_math)]
    1979    ///
    1980    /// use core::f32;
    1981    ///
    1982    /// let x = 3.0f32;
    1983    /// let y = -3.0f32;
    1984    ///
    1985    /// let abs_difference_x = (f32::math::abs_sub(x, 1.0) - 2.0).abs();
    1986    /// let abs_difference_y = (f32::math::abs_sub(y, 1.0) - 0.0).abs();
    1987    ///
    1988    /// assert!(abs_difference_x <= 1e-6);
    1989    /// assert!(abs_difference_y <= 1e-6);
    1990    /// ```
    1991    ///
    1992    /// _This standalone function is for testing only.
    1993    /// It will be stabilized as an inherent method._
    1994    ///
    1995    /// [`f32::abs_sub`]: ../../../std/primitive.f32.html#method.abs_sub
    1996    #[inline]
    1997    #[stable(feature = "rust1", since = "1.0.0")]
    1998    #[deprecated(
    1999        since = "1.10.0",
    2000        note = "you probably meant `(self - other).abs()`: \
    2001            this operation is `(self - other).max(0.0)` \
    2002            except that `abs_sub` also propagates NaNs (also \
    2003            known as `fdimf` in C). If you truly need the positive \
    2004            difference, consider using that expression or the C function \
    2005            `fdimf`, depending on how you wish to handle NaN (please consider \
    2006            filing an issue describing your use-case too)."
    2007    )]
    2008    #[must_use = "method returns a new number and does not mutate the original value"]
    2009    pub fn abs_sub(x: f32, other: f32) -> f32 {
    2010        libm::fdimf(x, other)
    2011    }
    2012
    2013    /// Experimental version of `cbrt` in `core`. See [`f32::cbrt`] for details.
    2014    ///
    2015    /// # Unspecified precision
    2016    ///
    2017    /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
    2018    /// can even differ within the same execution from one invocation to the next.
    2019    /// This function currently corresponds to the `cbrtf` from libc on Unix
    2020    /// and Windows. Note that this might change in the future.
    2021    ///
    2022    /// # Examples
    2023    ///
    2024    /// ```
    2025    /// #![feature(core_float_math)]
    2026    ///
    2027    /// use core::f32;
    2028    ///
    2029    /// let x = 8.0f32;
    2030    ///
    2031    /// // x^(1/3) - 2 == 0
    2032    /// let abs_difference = (f32::math::cbrt(x) - 2.0).abs();
    2033    ///
    2034    /// assert!(abs_difference <= 1e-6);
    2035    /// ```
    2036    ///
    2037    /// _This standalone function is for testing only.
    2038    /// It will be stabilized as an inherent method._
    2039    ///
    2040    /// [`f32::cbrt`]: ../../../std/primitive.f32.html#method.cbrt
    2041    #[inline]
    2042    #[must_use = "method returns a new number and does not mutate the original value"]
    2043    #[unstable(feature = "core_float_math", issue = "137578")]
    2044    pub fn cbrt(x: f32) -> f32 {
    2045        libm::cbrtf(x)
    2046    }
    2047}