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