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