std/num/f64.rs
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, clippy::legacy_numeric_constants)]
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 that is 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_stable(feature = "const_float_round_methods", since = "1.90.0")]
48 #[inline]
49 pub const fn floor(self) -> f64 {
50 core::f64::math::floor(self)
51 }
52
53 /// Returns the smallest integer that is 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 /// let h = -3.01_f64;
63 ///
64 /// assert_eq!(f.ceil(), 4.0);
65 /// assert_eq!(g.ceil(), 4.0);
66 /// assert_eq!(h.ceil(), -3.0);
67 /// ```
68 #[doc(alias = "ceiling")]
69 #[rustc_allow_incoherent_impl]
70 #[must_use = "method returns a new number and does not mutate the original value"]
71 #[stable(feature = "rust1", since = "1.0.0")]
72 #[rustc_const_stable(feature = "const_float_round_methods", since = "1.90.0")]
73 #[inline]
74 pub const fn ceil(self) -> f64 {
75 core::f64::math::ceil(self)
76 }
77
78 /// Returns the nearest integer to `self`. If a value is half-way between two
79 /// integers, round away from `0.0`.
80 ///
81 /// This function always returns the precise result.
82 ///
83 /// # Examples
84 ///
85 /// ```
86 /// let f = 3.3_f64;
87 /// let g = -3.3_f64;
88 /// let h = -3.7_f64;
89 /// let i = 3.5_f64;
90 /// let j = 4.5_f64;
91 ///
92 /// assert_eq!(f.round(), 3.0);
93 /// assert_eq!(g.round(), -3.0);
94 /// assert_eq!(h.round(), -4.0);
95 /// assert_eq!(i.round(), 4.0);
96 /// assert_eq!(j.round(), 5.0);
97 /// ```
98 #[rustc_allow_incoherent_impl]
99 #[must_use = "method returns a new number and does not mutate the original value"]
100 #[stable(feature = "rust1", since = "1.0.0")]
101 #[rustc_const_stable(feature = "const_float_round_methods", since = "1.90.0")]
102 #[inline]
103 pub const fn round(self) -> f64 {
104 core::f64::math::round(self)
105 }
106
107 /// Returns the nearest integer to a number. Rounds half-way cases to the number
108 /// with an even least significant digit.
109 ///
110 /// This function always returns the precise result.
111 ///
112 /// # Examples
113 ///
114 /// ```
115 /// let f = 3.3_f64;
116 /// let g = -3.3_f64;
117 /// let h = 3.5_f64;
118 /// let i = 4.5_f64;
119 ///
120 /// assert_eq!(f.round_ties_even(), 3.0);
121 /// assert_eq!(g.round_ties_even(), -3.0);
122 /// assert_eq!(h.round_ties_even(), 4.0);
123 /// assert_eq!(i.round_ties_even(), 4.0);
124 /// ```
125 #[rustc_allow_incoherent_impl]
126 #[must_use = "method returns a new number and does not mutate the original value"]
127 #[stable(feature = "round_ties_even", since = "1.77.0")]
128 #[rustc_const_stable(feature = "const_float_round_methods", since = "1.90.0")]
129 #[inline]
130 pub const fn round_ties_even(self) -> f64 {
131 core::f64::math::round_ties_even(self)
132 }
133
134 /// Returns the integer part of `self`.
135 /// This means that non-integer numbers are always truncated towards zero.
136 ///
137 /// This function always returns the precise result.
138 ///
139 /// # Examples
140 ///
141 /// ```
142 /// let f = 3.7_f64;
143 /// let g = 3.0_f64;
144 /// let h = -3.7_f64;
145 ///
146 /// assert_eq!(f.trunc(), 3.0);
147 /// assert_eq!(g.trunc(), 3.0);
148 /// assert_eq!(h.trunc(), -3.0);
149 /// ```
150 #[doc(alias = "truncate")]
151 #[rustc_allow_incoherent_impl]
152 #[must_use = "method returns a new number and does not mutate the original value"]
153 #[stable(feature = "rust1", since = "1.0.0")]
154 #[rustc_const_stable(feature = "const_float_round_methods", since = "1.90.0")]
155 #[inline]
156 pub const fn trunc(self) -> f64 {
157 core::f64::math::trunc(self)
158 }
159
160 /// Returns the fractional part of `self`.
161 ///
162 /// This function always returns the precise result.
163 ///
164 /// # Examples
165 ///
166 /// ```
167 /// let x = 3.6_f64;
168 /// let y = -3.6_f64;
169 /// let abs_difference_x = (x.fract() - 0.6).abs();
170 /// let abs_difference_y = (y.fract() - (-0.6)).abs();
171 ///
172 /// assert!(abs_difference_x < 1e-10);
173 /// assert!(abs_difference_y < 1e-10);
174 /// ```
175 #[rustc_allow_incoherent_impl]
176 #[must_use = "method returns a new number and does not mutate the original value"]
177 #[stable(feature = "rust1", since = "1.0.0")]
178 #[rustc_const_stable(feature = "const_float_round_methods", since = "1.90.0")]
179 #[inline]
180 pub const fn fract(self) -> f64 {
181 core::f64::math::fract(self)
182 }
183
184 /// Fused multiply-add. Computes `(self * a) + b` with only one rounding
185 /// error, yielding a more accurate result than an unfused multiply-add.
186 ///
187 /// Using `mul_add` *may* be more performant than an unfused multiply-add if
188 /// the target architecture has a dedicated `fma` CPU instruction. However,
189 /// this is not always true, and will be heavily dependant on designing
190 /// algorithms with specific target hardware in mind.
191 ///
192 /// # Precision
193 ///
194 /// The result of this operation is guaranteed to be the rounded
195 /// infinite-precision result. It is specified by IEEE 754 as
196 /// `fusedMultiplyAdd` and guaranteed not to change.
197 ///
198 /// # Examples
199 ///
200 /// ```
201 /// let m = 10.0_f64;
202 /// let x = 4.0_f64;
203 /// let b = 60.0_f64;
204 ///
205 /// assert_eq!(m.mul_add(x, b), 100.0);
206 /// assert_eq!(m * x + b, 100.0);
207 ///
208 /// let one_plus_eps = 1.0_f64 + f64::EPSILON;
209 /// let one_minus_eps = 1.0_f64 - f64::EPSILON;
210 /// let minus_one = -1.0_f64;
211 ///
212 /// // The exact result (1 + eps) * (1 - eps) = 1 - eps * eps.
213 /// assert_eq!(one_plus_eps.mul_add(one_minus_eps, minus_one), -f64::EPSILON * f64::EPSILON);
214 /// // Different rounding with the non-fused multiply and add.
215 /// assert_eq!(one_plus_eps * one_minus_eps + minus_one, 0.0);
216 /// ```
217 #[rustc_allow_incoherent_impl]
218 #[doc(alias = "fma", alias = "fusedMultiplyAdd")]
219 #[must_use = "method returns a new number and does not mutate the original value"]
220 #[stable(feature = "rust1", since = "1.0.0")]
221 #[inline]
222 #[rustc_const_stable(feature = "const_mul_add", since = "1.94.0")]
223 pub const fn mul_add(self, a: f64, b: f64) -> f64 {
224 core::f64::math::mul_add(self, a, b)
225 }
226
227 /// Calculates Euclidean division, the matching method for `rem_euclid`.
228 ///
229 /// This computes the integer `n` such that
230 /// `self = n * rhs + self.rem_euclid(rhs)`.
231 /// In other words, the result is `self / rhs` rounded to the integer `n`
232 /// such that `self >= n * rhs`.
233 ///
234 /// # Precision
235 ///
236 /// The result of this operation is guaranteed to be the rounded
237 /// infinite-precision result.
238 ///
239 /// # Examples
240 ///
241 /// ```
242 /// let a: f64 = 7.0;
243 /// let b = 4.0;
244 /// assert_eq!(a.div_euclid(b), 1.0); // 7.0 > 4.0 * 1.0
245 /// assert_eq!((-a).div_euclid(b), -2.0); // -7.0 >= 4.0 * -2.0
246 /// assert_eq!(a.div_euclid(-b), -1.0); // 7.0 >= -4.0 * -1.0
247 /// assert_eq!((-a).div_euclid(-b), 2.0); // -7.0 >= -4.0 * 2.0
248 /// ```
249 #[rustc_allow_incoherent_impl]
250 #[must_use = "method returns a new number and does not mutate the original value"]
251 #[inline]
252 #[stable(feature = "euclidean_division", since = "1.38.0")]
253 pub fn div_euclid(self, rhs: f64) -> f64 {
254 core::f64::math::div_euclid(self, rhs)
255 }
256
257 /// Calculates the least nonnegative remainder of `self` when divided by
258 /// `rhs`.
259 ///
260 /// In particular, the return value `r` satisfies `0.0 <= r < rhs.abs()` in
261 /// most cases. However, due to a floating point round-off error it can
262 /// result in `r == rhs.abs()`, violating the mathematical definition, if
263 /// `self` is much smaller than `rhs.abs()` in magnitude and `self < 0.0`.
264 /// This result is not an element of the function's codomain, but it is the
265 /// closest floating point number in the real numbers and thus fulfills the
266 /// property `self == self.div_euclid(rhs) * rhs + self.rem_euclid(rhs)`
267 /// approximately.
268 ///
269 /// # Precision
270 ///
271 /// The result of this operation is guaranteed to be the rounded
272 /// infinite-precision result.
273 ///
274 /// # Examples
275 ///
276 /// ```
277 /// let a: f64 = 7.0;
278 /// let b = 4.0;
279 /// assert_eq!(a.rem_euclid(b), 3.0);
280 /// assert_eq!((-a).rem_euclid(b), 1.0);
281 /// assert_eq!(a.rem_euclid(-b), 3.0);
282 /// assert_eq!((-a).rem_euclid(-b), 1.0);
283 /// // limitation due to round-off error
284 /// assert!((-f64::EPSILON).rem_euclid(3.0) != 0.0);
285 /// ```
286 #[doc(alias = "modulo", alias = "mod")]
287 #[rustc_allow_incoherent_impl]
288 #[must_use = "method returns a new number and does not mutate the original value"]
289 #[inline]
290 #[stable(feature = "euclidean_division", since = "1.38.0")]
291 pub fn rem_euclid(self, rhs: f64) -> f64 {
292 core::f64::math::rem_euclid(self, rhs)
293 }
294
295 /// Raises a number to an integer power.
296 ///
297 /// Using this function is generally faster than using `powf`.
298 /// It might have a different sequence of rounding operations than `powf`,
299 /// so the results are not guaranteed to agree.
300 ///
301 /// Note that this function is special in that it can return non-NaN results for NaN inputs. For
302 /// example, `f64::powi(f64::NAN, 0)` returns `1.0`. However, if an input is a *signaling*
303 /// NaN, then the result is non-deterministically either a NaN or the result that the
304 /// corresponding quiet NaN would produce.
305 ///
306 /// # Unspecified precision
307 ///
308 /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
309 /// can even differ within the same execution from one invocation to the next.
310 ///
311 /// # Examples
312 ///
313 /// ```
314 /// let x = 2.0_f64;
315 /// let abs_difference = (x.powi(2) - (x * x)).abs();
316 /// assert!(abs_difference <= 1e-14);
317 ///
318 /// assert_eq!(f64::powi(f64::NAN, 0), 1.0);
319 /// assert_eq!(f64::powi(0.0, 0), 1.0);
320 /// ```
321 #[rustc_allow_incoherent_impl]
322 #[must_use = "method returns a new number and does not mutate the original value"]
323 #[stable(feature = "rust1", since = "1.0.0")]
324 #[inline]
325 pub fn powi(self, n: i32) -> f64 {
326 core::f64::math::powi(self, n)
327 }
328
329 /// Raises a number to a floating point power.
330 ///
331 /// Note that this function is special in that it can return non-NaN results for NaN inputs. For
332 /// example, `f64::powf(f64::NAN, 0.0)` returns `1.0`. However, if an input is a *signaling*
333 /// NaN, then the result is non-deterministically either a NaN or the result that the
334 /// corresponding quiet NaN would produce.
335 ///
336 /// # Unspecified precision
337 ///
338 /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
339 /// can even differ within the same execution from one invocation to the next.
340 ///
341 /// # Examples
342 ///
343 /// ```
344 /// let x = 2.0_f64;
345 /// let abs_difference = (x.powf(2.0) - (x * x)).abs();
346 /// assert!(abs_difference <= 1e-14);
347 ///
348 /// assert_eq!(f64::powf(1.0, f64::NAN), 1.0);
349 /// assert_eq!(f64::powf(f64::NAN, 0.0), 1.0);
350 /// assert_eq!(f64::powf(0.0, 0.0), 1.0);
351 /// ```
352 #[rustc_allow_incoherent_impl]
353 #[must_use = "method returns a new number and does not mutate the original value"]
354 #[stable(feature = "rust1", since = "1.0.0")]
355 #[inline]
356 pub fn powf(self, n: f64) -> f64 {
357 intrinsics::powf64(self, n)
358 }
359
360 /// Returns the square root of a number.
361 ///
362 /// Returns NaN if `self` is a negative number other than `-0.0`.
363 ///
364 /// # Precision
365 ///
366 /// The result of this operation is guaranteed to be the rounded
367 /// infinite-precision result. It is specified by IEEE 754 as `squareRoot`
368 /// and guaranteed not to change.
369 ///
370 /// # Examples
371 ///
372 /// ```
373 /// let positive = 4.0_f64;
374 /// let negative = -4.0_f64;
375 /// let negative_zero = -0.0_f64;
376 ///
377 /// assert_eq!(positive.sqrt(), 2.0);
378 /// assert!(negative.sqrt().is_nan());
379 /// assert!(negative_zero.sqrt() == negative_zero);
380 /// ```
381 #[doc(alias = "squareRoot")]
382 #[rustc_allow_incoherent_impl]
383 #[must_use = "method returns a new number and does not mutate the original value"]
384 #[stable(feature = "rust1", since = "1.0.0")]
385 #[inline]
386 pub fn sqrt(self) -> f64 {
387 core::f64::math::sqrt(self)
388 }
389
390 /// Returns `e^(self)`, (the exponential function).
391 ///
392 /// # Unspecified precision
393 ///
394 /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
395 /// can even differ within the same execution from one invocation to the next.
396 ///
397 /// # Examples
398 ///
399 /// ```
400 /// let one = 1.0_f64;
401 /// // e^1
402 /// let e = one.exp();
403 ///
404 /// // ln(e) - 1 == 0
405 /// let abs_difference = (e.ln() - 1.0).abs();
406 ///
407 /// assert!(abs_difference < 1e-10);
408 /// ```
409 #[rustc_allow_incoherent_impl]
410 #[must_use = "method returns a new number and does not mutate the original value"]
411 #[stable(feature = "rust1", since = "1.0.0")]
412 #[inline]
413 pub fn exp(self) -> f64 {
414 intrinsics::expf64(self)
415 }
416
417 /// Returns `2^(self)`.
418 ///
419 /// # Unspecified precision
420 ///
421 /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
422 /// can even differ within the same execution from one invocation to the next.
423 ///
424 /// # Examples
425 ///
426 /// ```
427 /// let f = 2.0_f64;
428 ///
429 /// // 2^2 - 4 == 0
430 /// let abs_difference = (f.exp2() - 4.0).abs();
431 ///
432 /// assert!(abs_difference < 1e-10);
433 /// ```
434 #[rustc_allow_incoherent_impl]
435 #[must_use = "method returns a new number and does not mutate the original value"]
436 #[stable(feature = "rust1", since = "1.0.0")]
437 #[inline]
438 pub fn exp2(self) -> f64 {
439 intrinsics::exp2f64(self)
440 }
441
442 /// Returns the natural logarithm of the number.
443 ///
444 /// This returns NaN when the number is negative, and negative infinity when number is zero.
445 ///
446 /// # Unspecified precision
447 ///
448 /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
449 /// can even differ within the same execution from one invocation to the next.
450 ///
451 /// # Examples
452 ///
453 /// ```
454 /// let one = 1.0_f64;
455 /// // e^1
456 /// let e = one.exp();
457 ///
458 /// // ln(e) - 1 == 0
459 /// let abs_difference = (e.ln() - 1.0).abs();
460 ///
461 /// assert!(abs_difference < 1e-10);
462 /// ```
463 ///
464 /// Non-positive values:
465 /// ```
466 /// assert_eq!(0_f64.ln(), f64::NEG_INFINITY);
467 /// assert!((-42_f64).ln().is_nan());
468 /// ```
469 #[rustc_allow_incoherent_impl]
470 #[must_use = "method returns a new number and does not mutate the original value"]
471 #[stable(feature = "rust1", since = "1.0.0")]
472 #[inline]
473 pub fn ln(self) -> f64 {
474 intrinsics::logf64(self)
475 }
476
477 /// Returns the logarithm of the number with respect to an arbitrary base.
478 ///
479 /// This returns NaN when the number is negative, and negative infinity when number is zero.
480 ///
481 /// The result might not be correctly rounded owing to implementation details;
482 /// `self.log2()` can produce more accurate results for base 2, and
483 /// `self.log10()` can produce more accurate results for base 10.
484 ///
485 /// # Unspecified precision
486 ///
487 /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and
488 /// can even differ within the same execution from one invocation to the next.
489 ///
490 /// # Examples
491 ///
492 /// ```
493 /// let twenty_five = 25.0_f64;
494 ///
495 /// // log5(25) - 2 == 0
496 /// let abs_difference = (twenty_five.log(5.0) - 2.0).abs();
497 ///
498 /// assert!(abs_difference < 1e-10);
499 /// ```
500 ///