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