std/num/
f32.rs

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