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