Skip to main content

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