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}