library/std/src/f64.rs

   1 //! Constants specific to the `f64` double-precision floating point type.
   2 //!
   3 //! *[See also the `f64` primitive type](primitive@f64).*
   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 `f64` type.
  11
  12 #![stable(feature = "rust1", since = "1.0.0")]
  13 #![allow(missing_docs)]
  14
  15 #[cfg(test)]
  16 mod tests;
  17
  18 #[cfg(not(test))]
  19 use crate::intrinsics;
  20 #[cfg(not(test))]
  21 use crate::sys::cmath;
  22
  23 #[stable(feature = "rust1", since = "1.0.0")]
  24 #[allow(deprecated, deprecated_in_future)]
  25 pub use core::f64::{
  26     consts, DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_10_EXP,
  27     MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX,
  28 };
  29
  30 #[cfg(not(test))]
  31 #[cfg_attr(bootstrap, lang = "f64_runtime")]
  32 impl f64 {
  33     /// Returns the largest integer less than or equal to a number.
  34     ///
  35     /// # Examples
  36     ///
  37     /// ```
  38     /// let f = 3.7_f64;
  39     /// let g = 3.0_f64;
  40     /// let h = -3.7_f64;
  41     ///
  42     /// assert_eq!(f.floor(), 3.0);
  43     /// assert_eq!(g.floor(), 3.0);
  44     /// assert_eq!(h.floor(), -4.0);
  45     /// ```
  46     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
  47     #[must_use = "method returns a new number and does not mutate the original value"]
  48     #[stable(feature = "rust1", since = "1.0.0")]
  49     #[inline]
  50     pub fn floor(self) -> f64 {
  51         unsafe { intrinsics::floorf64(self) }
  52     }
  53
  54     /// Returns the smallest integer greater than or equal to a number.
  55     ///
  56     /// # Examples
  57     ///
  58     /// ```
  59     /// let f = 3.01_f64;
  60     /// let g = 4.0_f64;
  61     ///
  62     /// assert_eq!(f.ceil(), 4.0);
  63     /// assert_eq!(g.ceil(), 4.0);
  64     /// ```
  65     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
  66     #[must_use = "method returns a new number and does not mutate the original value"]
  67     #[stable(feature = "rust1", since = "1.0.0")]
  68     #[inline]
  69     pub fn ceil(self) -> f64 {
  70         unsafe { intrinsics::ceilf64(self) }
  71     }
  72
  73     /// Returns the nearest integer to a number. Round half-way cases away from
  74     /// `0.0`.
  75     ///
  76     /// # Examples
  77     ///
  78     /// ```
  79     /// let f = 3.3_f64;
  80     /// let g = -3.3_f64;
  81     ///
  82     /// assert_eq!(f.round(), 3.0);
  83     /// assert_eq!(g.round(), -3.0);
  84     /// ```
  85     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
  86     #[must_use = "method returns a new number and does not mutate the original value"]
  87     #[stable(feature = "rust1", since = "1.0.0")]
  88     #[inline]
  89     pub fn round(self) -> f64 {
  90         unsafe { intrinsics::roundf64(self) }
  91     }
  92
  93     /// Returns the integer part of a number.
  94     ///
  95     /// # Examples
  96     ///
  97     /// ```
  98     /// let f = 3.7_f64;
  99     /// let g = 3.0_f64;
 100     /// let h = -3.7_f64;
 101     ///
 102     /// assert_eq!(f.trunc(), 3.0);
 103     /// assert_eq!(g.trunc(), 3.0);
 104     /// assert_eq!(h.trunc(), -3.0);
 105     /// ```
 106     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 107     #[must_use = "method returns a new number and does not mutate the original value"]
 108     #[stable(feature = "rust1", since = "1.0.0")]
 109     #[inline]
 110     pub fn trunc(self) -> f64 {
 111         unsafe { intrinsics::truncf64(self) }
 112     }
 113
 114     /// Returns the fractional part of a number.
 115     ///
 116     /// # Examples
 117     ///
 118     /// ```
 119     /// let x = 3.6_f64;
 120     /// let y = -3.6_f64;
 121     /// let abs_difference_x = (x.fract() - 0.6).abs();
 122     /// let abs_difference_y = (y.fract() - (-0.6)).abs();
 123     ///
 124     /// assert!(abs_difference_x < 1e-10);
 125     /// assert!(abs_difference_y < 1e-10);
 126     /// ```
 127     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 128     #[must_use = "method returns a new number and does not mutate the original value"]
 129     #[stable(feature = "rust1", since = "1.0.0")]
 130     #[inline]
 131     pub fn fract(self) -> f64 {
 132         self - self.trunc()
 133     }
 134
 135     /// Computes the absolute value of `self`. Returns `NAN` if the
 136     /// number is `NAN`.
 137     ///
 138     /// # Examples
 139     ///
 140     /// ```
 141     /// let x = 3.5_f64;
 142     /// let y = -3.5_f64;
 143     ///
 144     /// let abs_difference_x = (x.abs() - x).abs();
 145     /// let abs_difference_y = (y.abs() - (-y)).abs();
 146     ///
 147     /// assert!(abs_difference_x < 1e-10);
 148     /// assert!(abs_difference_y < 1e-10);
 149     ///
 150     /// assert!(f64::NAN.abs().is_nan());
 151     /// ```
 152     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 153     #[must_use = "method returns a new number and does not mutate the original value"]
 154     #[stable(feature = "rust1", since = "1.0.0")]
 155     #[inline]
 156     pub fn abs(self) -> f64 {
 157         unsafe { intrinsics::fabsf64(self) }
 158     }
 159
 160     /// Returns a number that represents the sign of `self`.
 161     ///
 162     /// - `1.0` if the number is positive, `+0.0` or `INFINITY`
 163     /// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY`
 164     /// - `NAN` if the number is `NAN`
 165     ///
 166     /// # Examples
 167     ///
 168     /// ```
 169     /// let f = 3.5_f64;
 170     ///
 171     /// assert_eq!(f.signum(), 1.0);
 172     /// assert_eq!(f64::NEG_INFINITY.signum(), -1.0);
 173     ///
 174     /// assert!(f64::NAN.signum().is_nan());
 175     /// ```
 176     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 177     #[must_use = "method returns a new number and does not mutate the original value"]
 178     #[stable(feature = "rust1", since = "1.0.0")]
 179     #[inline]
 180     pub fn signum(self) -> f64 {
 181         if self.is_nan() { Self::NAN } else { 1.0_f64.copysign(self) }
 182     }
 183
 184     /// Returns a number composed of the magnitude of `self` and the sign of
 185     /// `sign`.
 186     ///
 187     /// Equal to `self` if the sign of `self` and `sign` are the same, otherwise
 188     /// equal to `-self`. If `self` is a `NAN`, then a `NAN` with the sign of
 189     /// `sign` is returned.
 190     ///
 191     /// # Examples
 192     ///
 193     /// ```
 194     /// let f = 3.5_f64;
 195     ///
 196     /// assert_eq!(f.copysign(0.42), 3.5_f64);
 197     /// assert_eq!(f.copysign(-0.42), -3.5_f64);
 198     /// assert_eq!((-f).copysign(0.42), 3.5_f64);
 199     /// assert_eq!((-f).copysign(-0.42), -3.5_f64);
 200     ///
 201     /// assert!(f64::NAN.copysign(1.0).is_nan());
 202     /// ```
 203     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 204     #[must_use = "method returns a new number and does not mutate the original value"]
 205     #[stable(feature = "copysign", since = "1.35.0")]
 206     #[inline]
 207     pub fn copysign(self, sign: f64) -> f64 {
 208         unsafe { intrinsics::copysignf64(self, sign) }
 209     }
 210
 211     /// Fused multiply-add. Computes `(self * a) + b` with only one rounding
 212     /// error, yielding a more accurate result than an unfused multiply-add.
 213     ///
 214     /// Using `mul_add` *may* be more performant than an unfused multiply-add if
 215     /// the target architecture has a dedicated `fma` CPU instruction. However,
 216     /// this is not always true, and will be heavily dependant on designing
 217     /// algorithms with specific target hardware in mind.
 218     ///
 219     /// # Examples
 220     ///
 221     /// ```
 222     /// let m = 10.0_f64;
 223     /// let x = 4.0_f64;
 224     /// let b = 60.0_f64;
 225     ///
 226     /// // 100.0
 227     /// let abs_difference = (m.mul_add(x, b) - ((m * x) + b)).abs();
 228     ///
 229     /// assert!(abs_difference < 1e-10);
 230     /// ```
 231     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 232     #[must_use = "method returns a new number and does not mutate the original value"]
 233     #[stable(feature = "rust1", since = "1.0.0")]
 234     #[inline]
 235     pub fn mul_add(self, a: f64, b: f64) -> f64 {
 236         unsafe { intrinsics::fmaf64(self, a, b) }
 237     }
 238
 239     /// Calculates Euclidean division, the matching method for `rem_euclid`.
 240     ///
 241     /// This computes the integer `n` such that
 242     /// `self = n * rhs + self.rem_euclid(rhs)`.
 243     /// In other words, the result is `self / rhs` rounded to the integer `n`
 244     /// such that `self >= n * rhs`.
 245     ///
 246     /// # Examples
 247     ///
 248     /// ```
 249     /// let a: f64 = 7.0;
 250     /// let b = 4.0;
 251     /// assert_eq!(a.div_euclid(b), 1.0); // 7.0 > 4.0 * 1.0
 252     /// assert_eq!((-a).div_euclid(b), -2.0); // -7.0 >= 4.0 * -2.0
 253     /// assert_eq!(a.div_euclid(-b), -1.0); // 7.0 >= -4.0 * -1.0
 254     /// assert_eq!((-a).div_euclid(-b), 2.0); // -7.0 >= -4.0 * 2.0
 255     /// ```
 256     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 257     #[must_use = "method returns a new number and does not mutate the original value"]
 258     #[inline]
 259     #[stable(feature = "euclidean_division", since = "1.38.0")]
 260     pub fn div_euclid(self, rhs: f64) -> f64 {
 261         let q = (self / rhs).trunc();
 262         if self % rhs < 0.0 {
 263             return if rhs > 0.0 { q - 1.0 } else { q + 1.0 };
 264         }
 265         q
 266     }
 267
 268     /// Calculates the least nonnegative remainder of `self (mod rhs)`.
 269     ///
 270     /// In particular, the return value `r` satisfies `0.0 <= r < rhs.abs()` in
 271     /// most cases. However, due to a floating point round-off error it can
 272     /// result in `r == rhs.abs()`, violating the mathematical definition, if
 273     /// `self` is much smaller than `rhs.abs()` in magnitude and `self < 0.0`.
 274     /// This result is not an element of the function's codomain, but it is the
 275     /// closest floating point number in the real numbers and thus fulfills the
 276     /// property `self == self.div_euclid(rhs) * rhs + self.rem_euclid(rhs)`
 277     /// approximatively.
 278     ///
 279     /// # Examples
 280     ///
 281     /// ```
 282     /// let a: f64 = 7.0;
 283     /// let b = 4.0;
 284     /// assert_eq!(a.rem_euclid(b), 3.0);
 285     /// assert_eq!((-a).rem_euclid(b), 1.0);
 286     /// assert_eq!(a.rem_euclid(-b), 3.0);
 287     /// assert_eq!((-a).rem_euclid(-b), 1.0);
 288     /// // limitation due to round-off error
 289     /// assert!((-f64::EPSILON).rem_euclid(3.0) != 0.0);
 290     /// ```
 291     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 292     #[must_use = "method returns a new number and does not mutate the original value"]
 293     #[inline]
 294     #[stable(feature = "euclidean_division", since = "1.38.0")]
 295     pub fn rem_euclid(self, rhs: f64) -> f64 {
 296         let r = self % rhs;
 297         if r < 0.0 { r + rhs.abs() } else { r }
 298     }
 299
 300     /// Raises a number to an integer power.
 301     ///
 302     /// Using this function is generally faster than using `powf`
 303     ///
 304     /// # Examples
 305     ///
 306     /// ```
 307     /// let x = 2.0_f64;
 308     /// let abs_difference = (x.powi(2) - (x * x)).abs();
 309     ///
 310     /// assert!(abs_difference < 1e-10);
 311     /// ```
 312     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 313     #[must_use = "method returns a new number and does not mutate the original value"]
 314     #[stable(feature = "rust1", since = "1.0.0")]
 315     #[inline]
 316     pub fn powi(self, n: i32) -> f64 {
 317         unsafe { intrinsics::powif64(self, n) }
 318     }
 319
 320     /// Raises a number to a floating point power.
 321     ///
 322     /// # Examples
 323     ///
 324     /// ```
 325     /// let x = 2.0_f64;
 326     /// let abs_difference = (x.powf(2.0) - (x * x)).abs();
 327     ///
 328     /// assert!(abs_difference < 1e-10);
 329     /// ```
 330     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 331     #[must_use = "method returns a new number and does not mutate the original value"]
 332     #[stable(feature = "rust1", since = "1.0.0")]
 333     #[inline]
 334     pub fn powf(self, n: f64) -> f64 {
 335         unsafe { intrinsics::powf64(self, n) }
 336     }
 337
 338     /// Returns the square root of a number.
 339     ///
 340     /// Returns NaN if `self` is a negative number other than `-0.0`.
 341     ///
 342     /// # Examples
 343     ///
 344     /// ```
 345     /// let positive = 4.0_f64;
 346     /// let negative = -4.0_f64;
 347     /// let negative_zero = -0.0_f64;
 348     ///
 349     /// let abs_difference = (positive.sqrt() - 2.0).abs();
 350     ///
 351     /// assert!(abs_difference < 1e-10);
 352     /// assert!(negative.sqrt().is_nan());
 353     /// assert!(negative_zero.sqrt() == negative_zero);
 354     /// ```
 355     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 356     #[must_use = "method returns a new number and does not mutate the original value"]
 357     #[stable(feature = "rust1", since = "1.0.0")]
 358     #[inline]
 359     pub fn sqrt(self) -> f64 {
 360         unsafe { intrinsics::sqrtf64(self) }
 361     }
 362
 363     /// Returns `e^(self)`, (the exponential function).
 364     ///
 365     /// # Examples
 366     ///
 367     /// ```
 368     /// let one = 1.0_f64;
 369     /// // e^1
 370     /// let e = one.exp();
 371     ///
 372     /// // ln(e) - 1 == 0
 373     /// let abs_difference = (e.ln() - 1.0).abs();
 374     ///
 375     /// assert!(abs_difference < 1e-10);
 376     /// ```
 377     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 378     #[must_use = "method returns a new number and does not mutate the original value"]
 379     #[stable(feature = "rust1", since = "1.0.0")]
 380     #[inline]
 381     pub fn exp(self) -> f64 {
 382         unsafe { intrinsics::expf64(self) }
 383     }
 384
 385     /// Returns `2^(self)`.
 386     ///
 387     /// # Examples
 388     ///
 389     /// ```
 390     /// let f = 2.0_f64;
 391     ///
 392     /// // 2^2 - 4 == 0
 393     /// let abs_difference = (f.exp2() - 4.0).abs();
 394     ///
 395     /// assert!(abs_difference < 1e-10);
 396     /// ```
 397     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 398     #[must_use = "method returns a new number and does not mutate the original value"]
 399     #[stable(feature = "rust1", since = "1.0.0")]
 400     #[inline]
 401     pub fn exp2(self) -> f64 {
 402         unsafe { intrinsics::exp2f64(self) }
 403     }
 404
 405     /// Returns the natural logarithm of the number.
 406     ///
 407     /// # Examples
 408     ///
 409     /// ```
 410     /// let one = 1.0_f64;
 411     /// // e^1
 412     /// let e = one.exp();
 413     ///
 414     /// // ln(e) - 1 == 0
 415     /// let abs_difference = (e.ln() - 1.0).abs();
 416     ///
 417     /// assert!(abs_difference < 1e-10);
 418     /// ```
 419     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 420     #[must_use = "method returns a new number and does not mutate the original value"]
 421     #[stable(feature = "rust1", since = "1.0.0")]
 422     #[inline]
 423     pub fn ln(self) -> f64 {
 424         self.log_wrapper(|n| unsafe { intrinsics::logf64(n) })
 425     }
 426
 427     /// Returns the logarithm of the number with respect to an arbitrary base.
 428     ///
 429     /// The result might not be correctly rounded owing to implementation details;
 430     /// `self.log2()` can produce more accurate results for base 2, and
 431     /// `self.log10()` can produce more accurate results for base 10.
 432     ///
 433     /// # Examples
 434     ///
 435     /// ```
 436     /// let twenty_five = 25.0_f64;
 437     ///
 438     /// // log5(25) - 2 == 0
 439     /// let abs_difference = (twenty_five.log(5.0) - 2.0).abs();
 440     ///
 441     /// assert!(abs_difference < 1e-10);
 442     /// ```
 443     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 444     #[must_use = "method returns a new number and does not mutate the original value"]
 445     #[stable(feature = "rust1", since = "1.0.0")]
 446     #[inline]
 447     pub fn log(self, base: f64) -> f64 {
 448         self.ln() / base.ln()
 449     }
 450
 451     /// Returns the base 2 logarithm of the number.
 452     ///
 453     /// # Examples
 454     ///
 455     /// ```
 456     /// let four = 4.0_f64;
 457     ///
 458     /// // log2(4) - 2 == 0
 459     /// let abs_difference = (four.log2() - 2.0).abs();
 460     ///
 461     /// assert!(abs_difference < 1e-10);
 462     /// ```
 463     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 464     #[must_use = "method returns a new number and does not mutate the original value"]
 465     #[stable(feature = "rust1", since = "1.0.0")]
 466     #[inline]
 467     pub fn log2(self) -> f64 {
 468         self.log_wrapper(|n| {
 469             #[cfg(target_os = "android")]
 470             return crate::sys::android::log2f64(n);
 471             #[cfg(not(target_os = "android"))]
 472             return unsafe { intrinsics::log2f64(n) };
 473         })
 474     }
 475
 476     /// Returns the base 10 logarithm of the number.
 477     ///
 478     /// # Examples
 479     ///
 480     /// ```
 481     /// let hundred = 100.0_f64;
 482     ///
 483     /// // log10(100) - 2 == 0
 484     /// let abs_difference = (hundred.log10() - 2.0).abs();
 485     ///
 486     /// assert!(abs_difference < 1e-10);
 487     /// ```
 488     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 489     #[must_use = "method returns a new number and does not mutate the original value"]
 490     #[stable(feature = "rust1", since = "1.0.0")]
 491     #[inline]
 492     pub fn log10(self) -> f64 {
 493         self.log_wrapper(|n| unsafe { intrinsics::log10f64(n) })
 494     }
 495
 496     /// The positive difference of two numbers.
 497     ///
 498     /// * If `self <= other`: `0:0`
 499     /// * Else: `self - other`
 500     ///
 501     /// # Examples
 502     ///
 503     /// ```
 504     /// let x = 3.0_f64;
 505     /// let y = -3.0_f64;
 506     ///
 507     /// let abs_difference_x = (x.abs_sub(1.0) - 2.0).abs();
 508     /// let abs_difference_y = (y.abs_sub(1.0) - 0.0).abs();
 509     ///
 510     /// assert!(abs_difference_x < 1e-10);
 511     /// assert!(abs_difference_y < 1e-10);
 512     /// ```
 513     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 514     #[must_use = "method returns a new number and does not mutate the original value"]
 515     #[stable(feature = "rust1", since = "1.0.0")]
 516     #[inline]
 517     #[rustc_deprecated(
 518         since = "1.10.0",
 519         reason = "you probably meant `(self - other).abs()`: \
 520                   this operation is `(self - other).max(0.0)` \
 521                   except that `abs_sub` also propagates NaNs (also \
 522                   known as `fdim` in C). If you truly need the positive \
 523                   difference, consider using that expression or the C function \
 524                   `fdim`, depending on how you wish to handle NaN (please consider \
 525                   filing an issue describing your use-case too)."
 526     )]
 527     pub fn abs_sub(self, other: f64) -> f64 {
 528         unsafe { cmath::fdim(self, other) }
 529     }
 530
 531     /// Returns the cube root of a number.
 532     ///
 533     /// # Examples
 534     ///
 535     /// ```
 536     /// let x = 8.0_f64;
 537     ///
 538     /// // x^(1/3) - 2 == 0
 539     /// let abs_difference = (x.cbrt() - 2.0).abs();
 540     ///
 541     /// assert!(abs_difference < 1e-10);
 542     /// ```
 543     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 544     #[must_use = "method returns a new number and does not mutate the original value"]
 545     #[stable(feature = "rust1", since = "1.0.0")]
 546     #[inline]
 547     pub fn cbrt(self) -> f64 {
 548         unsafe { cmath::cbrt(self) }
 549     }
 550
 551     /// Calculates the length of the hypotenuse of a right-angle triangle given
 552     /// legs of length `x` and `y`.
 553     ///
 554     /// # Examples
 555     ///
 556     /// ```
 557     /// let x = 2.0_f64;
 558     /// let y = 3.0_f64;
 559     ///
 560     /// // sqrt(x^2 + y^2)
 561     /// let abs_difference = (x.hypot(y) - (x.powi(2) + y.powi(2)).sqrt()).abs();
 562     ///
 563     /// assert!(abs_difference < 1e-10);
 564     /// ```
 565     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 566     #[must_use = "method returns a new number and does not mutate the original value"]
 567     #[stable(feature = "rust1", since = "1.0.0")]
 568     #[inline]
 569     pub fn hypot(self, other: f64) -> f64 {
 570         unsafe { cmath::hypot(self, other) }
 571     }
 572
 573     /// Computes the sine of a number (in radians).
 574     ///
 575     /// # Examples
 576     ///
 577     /// ```
 578     /// let x = std::f64::consts::FRAC_PI_2;
 579     ///
 580     /// let abs_difference = (x.sin() - 1.0).abs();
 581     ///
 582     /// assert!(abs_difference < 1e-10);
 583     /// ```
 584     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 585     #[must_use = "method returns a new number and does not mutate the original value"]
 586     #[stable(feature = "rust1", since = "1.0.0")]
 587     #[inline]
 588     pub fn sin(self) -> f64 {
 589         unsafe { intrinsics::sinf64(self) }
 590     }
 591
 592     /// Computes the cosine of a number (in radians).
 593     ///
 594     /// # Examples
 595     ///
 596     /// ```
 597     /// let x = 2.0 * std::f64::consts::PI;
 598     ///
 599     /// let abs_difference = (x.cos() - 1.0).abs();
 600     ///
 601     /// assert!(abs_difference < 1e-10);
 602     /// ```
 603     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 604     #[must_use = "method returns a new number and does not mutate the original value"]
 605     #[stable(feature = "rust1", since = "1.0.0")]
 606     #[inline]
 607     pub fn cos(self) -> f64 {
 608         unsafe { intrinsics::cosf64(self) }
 609     }
 610
 611     /// Computes the tangent of a number (in radians).
 612     ///
 613     /// # Examples
 614     ///
 615     /// ```
 616     /// let x = std::f64::consts::FRAC_PI_4;
 617     /// let abs_difference = (x.tan() - 1.0).abs();
 618     ///
 619     /// assert!(abs_difference < 1e-14);
 620     /// ```
 621     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 622     #[must_use = "method returns a new number and does not mutate the original value"]
 623     #[stable(feature = "rust1", since = "1.0.0")]
 624     #[inline]
 625     pub fn tan(self) -> f64 {
 626         unsafe { cmath::tan(self) }
 627     }
 628
 629     /// Computes the arcsine of a number. Return value is in radians in
 630     /// the range [-pi/2, pi/2] or NaN if the number is outside the range
 631     /// [-1, 1].
 632     ///
 633     /// # Examples
 634     ///
 635     /// ```
 636     /// let f = std::f64::consts::FRAC_PI_2;
 637     ///
 638     /// // asin(sin(pi/2))
 639     /// let abs_difference = (f.sin().asin() - std::f64::consts::FRAC_PI_2).abs();
 640     ///
 641     /// assert!(abs_difference < 1e-10);
 642     /// ```
 643     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 644     #[must_use = "method returns a new number and does not mutate the original value"]
 645     #[stable(feature = "rust1", since = "1.0.0")]
 646     #[inline]
 647     pub fn asin(self) -> f64 {
 648         unsafe { cmath::asin(self) }
 649     }
 650
 651     /// Computes the arccosine of a number. Return value is in radians in
 652     /// the range [0, pi] or NaN if the number is outside the range
 653     /// [-1, 1].
 654     ///
 655     /// # Examples
 656     ///
 657     /// ```
 658     /// let f = std::f64::consts::FRAC_PI_4;
 659     ///
 660     /// // acos(cos(pi/4))
 661     /// let abs_difference = (f.cos().acos() - std::f64::consts::FRAC_PI_4).abs();
 662     ///
 663     /// assert!(abs_difference < 1e-10);
 664     /// ```
 665     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 666     #[must_use = "method returns a new number and does not mutate the original value"]
 667     #[stable(feature = "rust1", since = "1.0.0")]
 668     #[inline]
 669     pub fn acos(self) -> f64 {
 670         unsafe { cmath::acos(self) }
 671     }
 672
 673     /// Computes the arctangent of a number. Return value is in radians in the
 674     /// range [-pi/2, pi/2];
 675     ///
 676     /// # Examples
 677     ///
 678     /// ```
 679     /// let f = 1.0_f64;
 680     ///
 681     /// // atan(tan(1))
 682     /// let abs_difference = (f.tan().atan() - 1.0).abs();
 683     ///
 684     /// assert!(abs_difference < 1e-10);
 685     /// ```
 686     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 687     #[must_use = "method returns a new number and does not mutate the original value"]
 688     #[stable(feature = "rust1", since = "1.0.0")]
 689     #[inline]
 690     pub fn atan(self) -> f64 {
 691         unsafe { cmath::atan(self) }
 692     }
 693
 694     /// Computes the four quadrant arctangent of `self` (`y`) and `other` (`x`) in radians.
 695     ///
 696     /// * `x = 0`, `y = 0`: `0`
 697     /// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]`
 698     /// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]`
 699     /// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)`
 700     ///
 701     /// # Examples
 702     ///
 703     /// ```
 704     /// // Positive angles measured counter-clockwise
 705     /// // from positive x axis
 706     /// // -pi/4 radians (45 deg clockwise)
 707     /// let x1 = 3.0_f64;
 708     /// let y1 = -3.0_f64;
 709     ///
 710     /// // 3pi/4 radians (135 deg counter-clockwise)
 711     /// let x2 = -3.0_f64;
 712     /// let y2 = 3.0_f64;
 713     ///
 714     /// let abs_difference_1 = (y1.atan2(x1) - (-std::f64::consts::FRAC_PI_4)).abs();
 715     /// let abs_difference_2 = (y2.atan2(x2) - (3.0 * std::f64::consts::FRAC_PI_4)).abs();
 716     ///
 717     /// assert!(abs_difference_1 < 1e-10);
 718     /// assert!(abs_difference_2 < 1e-10);
 719     /// ```
 720     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 721     #[must_use = "method returns a new number and does not mutate the original value"]
 722     #[stable(feature = "rust1", since = "1.0.0")]
 723     #[inline]
 724     pub fn atan2(self, other: f64) -> f64 {
 725         unsafe { cmath::atan2(self, other) }
 726     }
 727
 728     /// Simultaneously computes the sine and cosine of the number, `x`. Returns
 729     /// `(sin(x), cos(x))`.
 730     ///
 731     /// # Examples
 732     ///
 733     /// ```
 734     /// let x = std::f64::consts::FRAC_PI_4;
 735     /// let f = x.sin_cos();
 736     ///
 737     /// let abs_difference_0 = (f.0 - x.sin()).abs();
 738     /// let abs_difference_1 = (f.1 - x.cos()).abs();
 739     ///
 740     /// assert!(abs_difference_0 < 1e-10);
 741     /// assert!(abs_difference_1 < 1e-10);
 742     /// ```
 743     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 744     #[stable(feature = "rust1", since = "1.0.0")]
 745     #[inline]
 746     pub fn sin_cos(self) -> (f64, f64) {
 747         (self.sin(), self.cos())
 748     }
 749
 750     /// Returns `e^(self) - 1` in a way that is accurate even if the
 751     /// number is close to zero.
 752     ///
 753     /// # Examples
 754     ///
 755     /// ```
 756     /// let x = 1e-16_f64;
 757     ///
 758     /// // for very small x, e^x is approximately 1 + x + x^2 / 2
 759     /// let approx = x + x * x / 2.0;
 760     /// let abs_difference = (x.exp_m1() - approx).abs();
 761     ///
 762     /// assert!(abs_difference < 1e-20);
 763     /// ```
 764     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 765     #[must_use = "method returns a new number and does not mutate the original value"]
 766     #[stable(feature = "rust1", since = "1.0.0")]
 767     #[inline]
 768     pub fn exp_m1(self) -> f64 {
 769         unsafe { cmath::expm1(self) }
 770     }
 771
 772     /// Returns `ln(1+n)` (natural logarithm) more accurately than if
 773     /// the operations were performed separately.
 774     ///
 775     /// # Examples
 776     ///
 777     /// ```
 778     /// let x = 1e-16_f64;
 779     ///
 780     /// // for very small x, ln(1 + x) is approximately x - x^2 / 2
 781     /// let approx = x - x * x / 2.0;
 782     /// let abs_difference = (x.ln_1p() - approx).abs();
 783     ///
 784     /// assert!(abs_difference < 1e-20);
 785     /// ```
 786     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 787     #[must_use = "method returns a new number and does not mutate the original value"]
 788     #[stable(feature = "rust1", since = "1.0.0")]
 789     #[inline]
 790     pub fn ln_1p(self) -> f64 {
 791         unsafe { cmath::log1p(self) }
 792     }
 793
 794     /// Hyperbolic sine function.
 795     ///
 796     /// # Examples
 797     ///
 798     /// ```
 799     /// let e = std::f64::consts::E;
 800     /// let x = 1.0_f64;
 801     ///
 802     /// let f = x.sinh();
 803     /// // Solving sinh() at 1 gives `(e^2-1)/(2e)`
 804     /// let g = ((e * e) - 1.0) / (2.0 * e);
 805     /// let abs_difference = (f - g).abs();
 806     ///
 807     /// assert!(abs_difference < 1e-10);
 808     /// ```
 809     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 810     #[must_use = "method returns a new number and does not mutate the original value"]
 811     #[stable(feature = "rust1", since = "1.0.0")]
 812     #[inline]
 813     pub fn sinh(self) -> f64 {
 814         unsafe { cmath::sinh(self) }
 815     }
 816
 817     /// Hyperbolic cosine function.
 818     ///
 819     /// # Examples
 820     ///
 821     /// ```
 822     /// let e = std::f64::consts::E;
 823     /// let x = 1.0_f64;
 824     /// let f = x.cosh();
 825     /// // Solving cosh() at 1 gives this result
 826     /// let g = ((e * e) + 1.0) / (2.0 * e);
 827     /// let abs_difference = (f - g).abs();
 828     ///
 829     /// // Same result
 830     /// assert!(abs_difference < 1.0e-10);
 831     /// ```
 832     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 833     #[must_use = "method returns a new number and does not mutate the original value"]
 834     #[stable(feature = "rust1", since = "1.0.0")]
 835     #[inline]
 836     pub fn cosh(self) -> f64 {
 837         unsafe { cmath::cosh(self) }
 838     }
 839
 840     /// Hyperbolic tangent function.
 841     ///
 842     /// # Examples
 843     ///
 844     /// ```
 845     /// let e = std::f64::consts::E;
 846     /// let x = 1.0_f64;
 847     ///
 848     /// let f = x.tanh();
 849     /// // Solving tanh() at 1 gives `(1 - e^(-2))/(1 + e^(-2))`
 850     /// let g = (1.0 - e.powi(-2)) / (1.0 + e.powi(-2));
 851     /// let abs_difference = (f - g).abs();
 852     ///
 853     /// assert!(abs_difference < 1.0e-10);
 854     /// ```
 855     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 856     #[must_use = "method returns a new number and does not mutate the original value"]
 857     #[stable(feature = "rust1", since = "1.0.0")]
 858     #[inline]
 859     pub fn tanh(self) -> f64 {
 860         unsafe { cmath::tanh(self) }
 861     }
 862
 863     /// Inverse hyperbolic sine function.
 864     ///
 865     /// # Examples
 866     ///
 867     /// ```
 868     /// let x = 1.0_f64;
 869     /// let f = x.sinh().asinh();
 870     ///
 871     /// let abs_difference = (f - x).abs();
 872     ///
 873     /// assert!(abs_difference < 1.0e-10);
 874     /// ```
 875     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 876     #[must_use = "method returns a new number and does not mutate the original value"]
 877     #[stable(feature = "rust1", since = "1.0.0")]
 878     #[inline]
 879     pub fn asinh(self) -> f64 {
 880         (self.abs() + ((self * self) + 1.0).sqrt()).ln().copysign(self)
 881     }
 882
 883     /// Inverse hyperbolic cosine function.
 884     ///
 885     /// # Examples
 886     ///
 887     /// ```
 888     /// let x = 1.0_f64;
 889     /// let f = x.cosh().acosh();
 890     ///
 891     /// let abs_difference = (f - x).abs();
 892     ///
 893     /// assert!(abs_difference < 1.0e-10);
 894     /// ```
 895     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 896     #[must_use = "method returns a new number and does not mutate the original value"]
 897     #[stable(feature = "rust1", since = "1.0.0")]
 898     #[inline]
 899     pub fn acosh(self) -> f64 {
 900         if self < 1.0 { Self::NAN } else { (self + ((self * self) - 1.0).sqrt()).ln() }
 901     }
 902
 903     /// Inverse hyperbolic tangent function.
 904     ///
 905     /// # Examples
 906     ///
 907     /// ```
 908     /// let e = std::f64::consts::E;
 909     /// let f = e.tanh().atanh();
 910     ///
 911     /// let abs_difference = (f - e).abs();
 912     ///
 913     /// assert!(abs_difference < 1.0e-10);
 914     /// ```
 915     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 916     #[must_use = "method returns a new number and does not mutate the original value"]
 917     #[stable(feature = "rust1", since = "1.0.0")]
 918     #[inline]
 919     pub fn atanh(self) -> f64 {
 920         0.5 * ((2.0 * self) / (1.0 - self)).ln_1p()
 921     }
 922
 923     // Solaris/Illumos requires a wrapper around log, log2, and log10 functions
 924     // because of their non-standard behavior (e.g., log(-n) returns -Inf instead
 925     // of expected NaN).
 926     #[cfg_attr(not(bootstrap), rustc_allow_incoherent_impl)]
 927     fn log_wrapper<F: Fn(f64) -> f64>(self, log_fn: F) -> f64 {
 928         if !cfg!(any(target_os = "solaris", target_os = "illumos")) {
 929             log_fn(self)
 930         } else if self.is_finite() {
 931             if self > 0.0 {
 932                 log_fn(self)
 933             } else if self == 0.0 {
 934                 Self::NEG_INFINITY // log(0) = -Inf
 935             } else {
 936                 Self::NAN // log(-n) = NaN
 937             }
 938         } else if self.is_nan() {
 939             self // log(NaN) = NaN
 940         } else if self > 0.0 {
 941             self // log(Inf) = Inf
 942         } else {
 943             Self::NAN // log(-Inf) = NaN
 944         }
 945     }
 946 }