num_traits/
float.rs

1use core::mem;
2use core::num::FpCategory;
3use core::ops::Neg;
4
5use core::f32;
6use core::f64;
7
8use {Num, NumCast, ToPrimitive};
9
10#[cfg(all(not(feature = "std"), feature = "libm"))]
11use libm;
12
13/// Generic trait for floating point numbers that works with `no_std`.
14///
15/// This trait implements a subset of the `Float` trait.
16pub trait FloatCore: Num + NumCast + Neg<Output = Self> + PartialOrd + Copy {
17    /// Returns positive infinity.
18    ///
19    /// # Examples
20    ///
21    /// ```
22    /// use num_traits::float::FloatCore;
23    /// use std::{f32, f64};
24    ///
25    /// fn check<T: FloatCore>(x: T) {
26    ///     assert!(T::infinity() == x);
27    /// }
28    ///
29    /// check(f32::INFINITY);
30    /// check(f64::INFINITY);
31    /// ```
32    fn infinity() -> Self;
33
34    /// Returns negative infinity.
35    ///
36    /// # Examples
37    ///
38    /// ```
39    /// use num_traits::float::FloatCore;
40    /// use std::{f32, f64};
41    ///
42    /// fn check<T: FloatCore>(x: T) {
43    ///     assert!(T::neg_infinity() == x);
44    /// }
45    ///
46    /// check(f32::NEG_INFINITY);
47    /// check(f64::NEG_INFINITY);
48    /// ```
49    fn neg_infinity() -> Self;
50
51    /// Returns NaN.
52    ///
53    /// # Examples
54    ///
55    /// ```
56    /// use num_traits::float::FloatCore;
57    ///
58    /// fn check<T: FloatCore>() {
59    ///     let n = T::nan();
60    ///     assert!(n != n);
61    /// }
62    ///
63    /// check::<f32>();
64    /// check::<f64>();
65    /// ```
66    fn nan() -> Self;
67
68    /// Returns `-0.0`.
69    ///
70    /// # Examples
71    ///
72    /// ```
73    /// use num_traits::float::FloatCore;
74    /// use std::{f32, f64};
75    ///
76    /// fn check<T: FloatCore>(n: T) {
77    ///     let z = T::neg_zero();
78    ///     assert!(z.is_zero());
79    ///     assert!(T::one() / z == n);
80    /// }
81    ///
82    /// check(f32::NEG_INFINITY);
83    /// check(f64::NEG_INFINITY);
84    /// ```
85    fn neg_zero() -> Self;
86
87    /// Returns the smallest finite value that this type can represent.
88    ///
89    /// # Examples
90    ///
91    /// ```
92    /// use num_traits::float::FloatCore;
93    /// use std::{f32, f64};
94    ///
95    /// fn check<T: FloatCore>(x: T) {
96    ///     assert!(T::min_value() == x);
97    /// }
98    ///
99    /// check(f32::MIN);
100    /// check(f64::MIN);
101    /// ```
102    fn min_value() -> Self;
103
104    /// Returns the smallest positive, normalized value that this type can represent.
105    ///
106    /// # Examples
107    ///
108    /// ```
109    /// use num_traits::float::FloatCore;
110    /// use std::{f32, f64};
111    ///
112    /// fn check<T: FloatCore>(x: T) {
113    ///     assert!(T::min_positive_value() == x);
114    /// }
115    ///
116    /// check(f32::MIN_POSITIVE);
117    /// check(f64::MIN_POSITIVE);
118    /// ```
119    fn min_positive_value() -> Self;
120
121    /// Returns epsilon, a small positive value.
122    ///
123    /// # Examples
124    ///
125    /// ```
126    /// use num_traits::float::FloatCore;
127    /// use std::{f32, f64};
128    ///
129    /// fn check<T: FloatCore>(x: T) {
130    ///     assert!(T::epsilon() == x);
131    /// }
132    ///
133    /// check(f32::EPSILON);
134    /// check(f64::EPSILON);
135    /// ```
136    fn epsilon() -> Self;
137
138    /// Returns the largest finite value that this type can represent.
139    ///
140    /// # Examples
141    ///
142    /// ```
143    /// use num_traits::float::FloatCore;
144    /// use std::{f32, f64};
145    ///
146    /// fn check<T: FloatCore>(x: T) {
147    ///     assert!(T::max_value() == x);
148    /// }
149    ///
150    /// check(f32::MAX);
151    /// check(f64::MAX);
152    /// ```
153    fn max_value() -> Self;
154
155    /// Returns `true` if the number is NaN.
156    ///
157    /// # Examples
158    ///
159    /// ```
160    /// use num_traits::float::FloatCore;
161    /// use std::{f32, f64};
162    ///
163    /// fn check<T: FloatCore>(x: T, p: bool) {
164    ///     assert!(x.is_nan() == p);
165    /// }
166    ///
167    /// check(f32::NAN, true);
168    /// check(f32::INFINITY, false);
169    /// check(f64::NAN, true);
170    /// check(0.0f64, false);
171    /// ```
172    #[inline]
173    fn is_nan(self) -> bool {
174        self != self
175    }
176
177    /// Returns `true` if the number is infinite.
178    ///
179    /// # Examples
180    ///
181    /// ```
182    /// use num_traits::float::FloatCore;
183    /// use std::{f32, f64};
184    ///
185    /// fn check<T: FloatCore>(x: T, p: bool) {
186    ///     assert!(x.is_infinite() == p);
187    /// }
188    ///
189    /// check(f32::INFINITY, true);
190    /// check(f32::NEG_INFINITY, true);
191    /// check(f32::NAN, false);
192    /// check(f64::INFINITY, true);
193    /// check(f64::NEG_INFINITY, true);
194    /// check(0.0f64, false);
195    /// ```
196    #[inline]
197    fn is_infinite(self) -> bool {
198        self == Self::infinity() || self == Self::neg_infinity()
199    }
200
201    /// Returns `true` if the number is neither infinite or NaN.
202    ///
203    /// # Examples
204    ///
205    /// ```
206    /// use num_traits::float::FloatCore;
207    /// use std::{f32, f64};
208    ///
209    /// fn check<T: FloatCore>(x: T, p: bool) {
210    ///     assert!(x.is_finite() == p);
211    /// }
212    ///
213    /// check(f32::INFINITY, false);
214    /// check(f32::MAX, true);
215    /// check(f64::NEG_INFINITY, false);
216    /// check(f64::MIN_POSITIVE, true);
217    /// check(f64::NAN, false);
218    /// ```
219    #[inline]
220    fn is_finite(self) -> bool {
221        !(self.is_nan() || self.is_infinite())
222    }
223
224    /// Returns `true` if the number is neither zero, infinite, subnormal or NaN.
225    ///
226    /// # Examples
227    ///
228    /// ```
229    /// use num_traits::float::FloatCore;
230    /// use std::{f32, f64};
231    ///
232    /// fn check<T: FloatCore>(x: T, p: bool) {
233    ///     assert!(x.is_normal() == p);
234    /// }
235    ///
236    /// check(f32::INFINITY, false);
237    /// check(f32::MAX, true);
238    /// check(f64::NEG_INFINITY, false);
239    /// check(f64::MIN_POSITIVE, true);
240    /// check(0.0f64, false);
241    /// ```
242    #[inline]
243    fn is_normal(self) -> bool {
244        self.classify() == FpCategory::Normal
245    }
246
247    /// Returns the floating point category of the number. If only one property
248    /// is going to be tested, it is generally faster to use the specific
249    /// predicate instead.
250    ///
251    /// # Examples
252    ///
253    /// ```
254    /// use num_traits::float::FloatCore;
255    /// use std::{f32, f64};
256    /// use std::num::FpCategory;
257    ///
258    /// fn check<T: FloatCore>(x: T, c: FpCategory) {
259    ///     assert!(x.classify() == c);
260    /// }
261    ///
262    /// check(f32::INFINITY, FpCategory::Infinite);
263    /// check(f32::MAX, FpCategory::Normal);
264    /// check(f64::NAN, FpCategory::Nan);
265    /// check(f64::MIN_POSITIVE, FpCategory::Normal);
266    /// check(f64::MIN_POSITIVE / 2.0, FpCategory::Subnormal);
267    /// check(0.0f64, FpCategory::Zero);
268    /// ```
269    fn classify(self) -> FpCategory;
270
271    /// Returns the largest integer less than or equal to a number.
272    ///
273    /// # Examples
274    ///
275    /// ```
276    /// use num_traits::float::FloatCore;
277    /// use std::{f32, f64};
278    ///
279    /// fn check<T: FloatCore>(x: T, y: T) {
280    ///     assert!(x.floor() == y);
281    /// }
282    ///
283    /// check(f32::INFINITY, f32::INFINITY);
284    /// check(0.9f32, 0.0);
285    /// check(1.0f32, 1.0);
286    /// check(1.1f32, 1.0);
287    /// check(-0.0f64, 0.0);
288    /// check(-0.9f64, -1.0);
289    /// check(-1.0f64, -1.0);
290    /// check(-1.1f64, -2.0);
291    /// check(f64::MIN, f64::MIN);
292    /// ```
293    #[inline]
294    fn floor(self) -> Self {
295        let f = self.fract();
296        if f.is_nan() || f.is_zero() {
297            self
298        } else if self < Self::zero() {
299            self - f - Self::one()
300        } else {
301            self - f
302        }
303    }
304
305    /// Returns the smallest integer greater than or equal to a number.
306    ///
307    /// # Examples
308    ///
309    /// ```
310    /// use num_traits::float::FloatCore;
311    /// use std::{f32, f64};
312    ///
313    /// fn check<T: FloatCore>(x: T, y: T) {
314    ///     assert!(x.ceil() == y);
315    /// }
316    ///
317    /// check(f32::INFINITY, f32::INFINITY);
318    /// check(0.9f32, 1.0);
319    /// check(1.0f32, 1.0);
320    /// check(1.1f32, 2.0);
321    /// check(-0.0f64, 0.0);
322    /// check(-0.9f64, -0.0);
323    /// check(-1.0f64, -1.0);
324    /// check(-1.1f64, -1.0);
325    /// check(f64::MIN, f64::MIN);
326    /// ```
327    #[inline]
328    fn ceil(self) -> Self {
329        let f = self.fract();
330        if f.is_nan() || f.is_zero() {
331            self
332        } else if self > Self::zero() {
333            self - f + Self::one()
334        } else {
335            self - f
336        }
337    }
338
339    /// Returns the nearest integer to a number. Round half-way cases away from `0.0`.
340    ///
341    /// # Examples
342    ///
343    /// ```
344    /// use num_traits::float::FloatCore;
345    /// use std::{f32, f64};
346    ///
347    /// fn check<T: FloatCore>(x: T, y: T) {
348    ///     assert!(x.round() == y);
349    /// }
350    ///
351    /// check(f32::INFINITY, f32::INFINITY);
352    /// check(0.4f32, 0.0);
353    /// check(0.5f32, 1.0);
354    /// check(0.6f32, 1.0);
355    /// check(-0.4f64, 0.0);
356    /// check(-0.5f64, -1.0);
357    /// check(-0.6f64, -1.0);
358    /// check(f64::MIN, f64::MIN);
359    /// ```
360    #[inline]
361    fn round(self) -> Self {
362        let one = Self::one();
363        let h = Self::from(0.5).expect("Unable to cast from 0.5");
364        let f = self.fract();
365        if f.is_nan() || f.is_zero() {
366            self
367        } else if self > Self::zero() {
368            if f < h {
369                self - f
370            } else {
371                self - f + one
372            }
373        } else {
374            if -f < h {
375                self - f
376            } else {
377                self - f - one
378            }
379        }
380    }
381
382    /// Return the integer part of a number.
383    ///
384    /// # Examples
385    ///
386    /// ```
387    /// use num_traits::float::FloatCore;
388    /// use std::{f32, f64};
389    ///
390    /// fn check<T: FloatCore>(x: T, y: T) {
391    ///     assert!(x.trunc() == y);
392    /// }
393    ///
394    /// check(f32::INFINITY, f32::INFINITY);
395    /// check(0.9f32, 0.0);
396    /// check(1.0f32, 1.0);
397    /// check(1.1f32, 1.0);
398    /// check(-0.0f64, 0.0);
399    /// check(-0.9f64, -0.0);
400    /// check(-1.0f64, -1.0);
401    /// check(-1.1f64, -1.0);
402    /// check(f64::MIN, f64::MIN);
403    /// ```
404    #[inline]
405    fn trunc(self) -> Self {
406        let f = self.fract();
407        if f.is_nan() {
408            self
409        } else {
410            self - f
411        }
412    }
413
414    /// Returns the fractional part of a number.
415    ///
416    /// # Examples
417    ///
418    /// ```
419    /// use num_traits::float::FloatCore;
420    /// use std::{f32, f64};
421    ///
422    /// fn check<T: FloatCore>(x: T, y: T) {
423    ///     assert!(x.fract() == y);
424    /// }
425    ///
426    /// check(f32::MAX, 0.0);
427    /// check(0.75f32, 0.75);
428    /// check(1.0f32, 0.0);
429    /// check(1.25f32, 0.25);
430    /// check(-0.0f64, 0.0);
431    /// check(-0.75f64, -0.75);
432    /// check(-1.0f64, 0.0);
433    /// check(-1.25f64, -0.25);
434    /// check(f64::MIN, 0.0);
435    /// ```
436    #[inline]
437    fn fract(self) -> Self {
438        if self.is_zero() {
439            Self::zero()
440        } else {
441            self % Self::one()
442        }
443    }
444
445    /// Computes the absolute value of `self`. Returns `FloatCore::nan()` if the
446    /// number is `FloatCore::nan()`.
447    ///
448    /// # Examples
449    ///
450    /// ```
451    /// use num_traits::float::FloatCore;
452    /// use std::{f32, f64};
453    ///
454    /// fn check<T: FloatCore>(x: T, y: T) {
455    ///     assert!(x.abs() == y);
456    /// }
457    ///
458    /// check(f32::INFINITY, f32::INFINITY);
459    /// check(1.0f32, 1.0);
460    /// check(0.0f64, 0.0);
461    /// check(-0.0f64, 0.0);
462    /// check(-1.0f64, 1.0);
463    /// check(f64::MIN, f64::MAX);
464    /// ```
465    #[inline]
466    fn abs(self) -> Self {
467        if self.is_sign_positive() {
468            return self;
469        }
470        if self.is_sign_negative() {
471            return -self;
472        }
473        Self::nan()
474    }
475
476    /// Returns a number that represents the sign of `self`.
477    ///
478    /// - `1.0` if the number is positive, `+0.0` or `FloatCore::infinity()`
479    /// - `-1.0` if the number is negative, `-0.0` or `FloatCore::neg_infinity()`
480    /// - `FloatCore::nan()` if the number is `FloatCore::nan()`
481    ///
482    /// # Examples
483    ///
484    /// ```
485    /// use num_traits::float::FloatCore;
486    /// use std::{f32, f64};
487    ///
488    /// fn check<T: FloatCore>(x: T, y: T) {
489    ///     assert!(x.signum() == y);
490    /// }
491    ///
492    /// check(f32::INFINITY, 1.0);
493    /// check(3.0f32, 1.0);
494    /// check(0.0f32, 1.0);
495    /// check(-0.0f64, -1.0);
496    /// check(-3.0f64, -1.0);
497    /// check(f64::MIN, -1.0);
498    /// ```
499    #[inline]
500    fn signum(self) -> Self {
501        if self.is_nan() {
502            Self::nan()
503        } else if self.is_sign_negative() {
504            -Self::one()
505        } else {
506            Self::one()
507        }
508    }
509
510    /// Returns `true` if `self` is positive, including `+0.0` and
511    /// `FloatCore::infinity()`, and since Rust 1.20 also
512    /// `FloatCore::nan()`.
513    ///
514    /// # Examples
515    ///
516    /// ```
517    /// use num_traits::float::FloatCore;
518    /// use std::{f32, f64};
519    ///
520    /// fn check<T: FloatCore>(x: T, p: bool) {
521    ///     assert!(x.is_sign_positive() == p);
522    /// }
523    ///
524    /// check(f32::INFINITY, true);
525    /// check(f32::MAX, true);
526    /// check(0.0f32, true);
527    /// check(-0.0f64, false);
528    /// check(f64::NEG_INFINITY, false);
529    /// check(f64::MIN_POSITIVE, true);
530    /// check(-f64::NAN, false);
531    /// ```
532    #[inline]
533    fn is_sign_positive(self) -> bool {
534        !self.is_sign_negative()
535    }
536
537    /// Returns `true` if `self` is negative, including `-0.0` and
538    /// `FloatCore::neg_infinity()`, and since Rust 1.20 also
539    /// `-FloatCore::nan()`.
540    ///
541    /// # Examples
542    ///
543    /// ```
544    /// use num_traits::float::FloatCore;
545    /// use std::{f32, f64};
546    ///
547    /// fn check<T: FloatCore>(x: T, p: bool) {
548    ///     assert!(x.is_sign_negative() == p);
549    /// }
550    ///
551    /// check(f32::INFINITY, false);
552    /// check(f32::MAX, false);
553    /// check(0.0f32, false);
554    /// check(-0.0f64, true);
555    /// check(f64::NEG_INFINITY, true);
556    /// check(f64::MIN_POSITIVE, false);
557    /// check(f64::NAN, false);
558    /// ```
559    #[inline]
560    fn is_sign_negative(self) -> bool {
561        let (_, _, sign) = self.integer_decode();
562        sign < 0
563    }
564
565    /// Returns the minimum of the two numbers.
566    ///
567    /// If one of the arguments is NaN, then the other argument is returned.
568    ///
569    /// # Examples
570    ///
571    /// ```
572    /// use num_traits::float::FloatCore;
573    /// use std::{f32, f64};
574    ///
575    /// fn check<T: FloatCore>(x: T, y: T, min: T) {
576    ///     assert!(x.min(y) == min);
577    /// }
578    ///
579    /// check(1.0f32, 2.0, 1.0);
580    /// check(f32::NAN, 2.0, 2.0);
581    /// check(1.0f64, -2.0, -2.0);
582    /// check(1.0f64, f64::NAN, 1.0);
583    /// ```
584    #[inline]
585    fn min(self, other: Self) -> Self {
586        if self.is_nan() {
587            return other;
588        }
589        if other.is_nan() {
590            return self;
591        }
592        if self < other {
593            self
594        } else {
595            other
596        }
597    }
598
599    /// Returns the maximum of the two numbers.
600    ///
601    /// If one of the arguments is NaN, then the other argument is returned.
602    ///
603    /// # Examples
604    ///
605    /// ```
606    /// use num_traits::float::FloatCore;
607    /// use std::{f32, f64};
608    ///
609    /// fn check<T: FloatCore>(x: T, y: T, min: T) {
610    ///     assert!(x.max(y) == min);
611    /// }
612    ///
613    /// check(1.0f32, 2.0, 2.0);
614    /// check(1.0f32, f32::NAN, 1.0);
615    /// check(-1.0f64, 2.0, 2.0);
616    /// check(-1.0f64, f64::NAN, -1.0);
617    /// ```
618    #[inline]
619    fn max(self, other: Self) -> Self {
620        if self.is_nan() {
621            return other;
622        }
623        if other.is_nan() {
624            return self;
625        }
626        if self > other {
627            self
628        } else {
629            other
630        }
631    }
632
633    /// Returns the reciprocal (multiplicative inverse) of the number.
634    ///
635    /// # Examples
636    ///
637    /// ```
638    /// use num_traits::float::FloatCore;
639    /// use std::{f32, f64};
640    ///
641    /// fn check<T: FloatCore>(x: T, y: T) {
642    ///     assert!(x.recip() == y);
643    ///     assert!(y.recip() == x);
644    /// }
645    ///
646    /// check(f32::INFINITY, 0.0);
647    /// check(2.0f32, 0.5);
648    /// check(-0.25f64, -4.0);
649    /// check(-0.0f64, f64::NEG_INFINITY);
650    /// ```
651    #[inline]
652    fn recip(self) -> Self {
653        Self::one() / self
654    }
655
656    /// Raise a number to an integer power.
657    ///
658    /// Using this function is generally faster than using `powf`
659    ///
660    /// # Examples
661    ///
662    /// ```
663    /// use num_traits::float::FloatCore;
664    ///
665    /// fn check<T: FloatCore>(x: T, exp: i32, powi: T) {
666    ///     assert!(x.powi(exp) == powi);
667    /// }
668    ///
669    /// check(9.0f32, 2, 81.0);
670    /// check(1.0f32, -2, 1.0);
671    /// check(10.0f64, 20, 1e20);
672    /// check(4.0f64, -2, 0.0625);
673    /// check(-1.0f64, std::i32::MIN, 1.0);
674    /// ```
675    #[inline]
676    fn powi(mut self, mut exp: i32) -> Self {
677        if exp < 0 {
678            exp = exp.wrapping_neg();
679            self = self.recip();
680        }
681        // It should always be possible to convert a positive `i32` to a `usize`.
682        // Note, `i32::MIN` will wrap and still be negative, so we need to convert
683        // to `u32` without sign-extension before growing to `usize`.
684        super::pow(self, (exp as u32).to_usize().unwrap())
685    }
686
687    /// Converts to degrees, assuming the number is in radians.
688    ///
689    /// # Examples
690    ///
691    /// ```
692    /// use num_traits::float::FloatCore;
693    /// use std::{f32, f64};
694    ///
695    /// fn check<T: FloatCore>(rad: T, deg: T) {
696    ///     assert!(rad.to_degrees() == deg);
697    /// }
698    ///
699    /// check(0.0f32, 0.0);
700    /// check(f32::consts::PI, 180.0);
701    /// check(f64::consts::FRAC_PI_4, 45.0);
702    /// check(f64::INFINITY, f64::INFINITY);
703    /// ```
704    fn to_degrees(self) -> Self;
705
706    /// Converts to radians, assuming the number is in degrees.
707    ///
708    /// # Examples
709    ///
710    /// ```
711    /// use num_traits::float::FloatCore;
712    /// use std::{f32, f64};
713    ///
714    /// fn check<T: FloatCore>(deg: T, rad: T) {
715    ///     assert!(deg.to_radians() == rad);
716    /// }
717    ///
718    /// check(0.0f32, 0.0);
719    /// check(180.0, f32::consts::PI);
720    /// check(45.0, f64::consts::FRAC_PI_4);
721    /// check(f64::INFINITY, f64::INFINITY);
722    /// ```
723    fn to_radians(self) -> Self;
724
725    /// Returns the mantissa, base 2 exponent, and sign as integers, respectively.
726    /// The original number can be recovered by `sign * mantissa * 2 ^ exponent`.
727    ///
728    /// # Examples
729    ///
730    /// ```
731    /// use num_traits::float::FloatCore;
732    /// use std::{f32, f64};
733    ///
734    /// fn check<T: FloatCore>(x: T, m: u64, e: i16, s:i8) {
735    ///     let (mantissa, exponent, sign) = x.integer_decode();
736    ///     assert_eq!(mantissa, m);
737    ///     assert_eq!(exponent, e);
738    ///     assert_eq!(sign, s);
739    /// }
740    ///
741    /// check(2.0f32, 1 << 23, -22, 1);
742    /// check(-2.0f32, 1 << 23, -22, -1);
743    /// check(f32::INFINITY, 1 << 23, 105, 1);
744    /// check(f64::NEG_INFINITY, 1 << 52, 972, -1);
745    /// ```
746    fn integer_decode(self) -> (u64, i16, i8);
747}
748
749impl FloatCore for f32 {
750    constant! {
751        infinity() -> f32::INFINITY;
752        neg_infinity() -> f32::NEG_INFINITY;
753        nan() -> f32::NAN;
754        neg_zero() -> -0.0;
755        min_value() -> f32::MIN;
756        min_positive_value() -> f32::MIN_POSITIVE;
757        epsilon() -> f32::EPSILON;
758        max_value() -> f32::MAX;
759    }
760
761    #[inline]
762    fn integer_decode(self) -> (u64, i16, i8) {
763        integer_decode_f32(self)
764    }
765
766    #[inline]
767    #[cfg(not(feature = "std"))]
768    fn classify(self) -> FpCategory {
769        const EXP_MASK: u32 = 0x7f800000;
770        const MAN_MASK: u32 = 0x007fffff;
771
772        // Safety: this identical to the implementation of f32::to_bits(),
773        // which is only available starting at Rust 1.20
774        let bits: u32 = unsafe { mem::transmute(self) };
775        match (bits & MAN_MASK, bits & EXP_MASK) {
776            (0, 0) => FpCategory::Zero,
777            (_, 0) => FpCategory::Subnormal,
778            (0, EXP_MASK) => FpCategory::Infinite,
779            (_, EXP_MASK) => FpCategory::Nan,
780            _ => FpCategory::Normal,
781        }
782    }
783
784    #[inline]
785    #[cfg(not(feature = "std"))]
786    fn to_degrees(self) -> Self {
787        // Use a constant for better precision.
788        const PIS_IN_180: f32 = 57.2957795130823208767981548141051703_f32;
789        self * PIS_IN_180
790    }
791
792    #[inline]
793    #[cfg(not(feature = "std"))]
794    fn to_radians(self) -> Self {
795        self * (f32::consts::PI / 180.0)
796    }
797
798    #[cfg(feature = "std")]
799    forward! {
800        Self::is_nan(self) -> bool;
801        Self::is_infinite(self) -> bool;
802        Self::is_finite(self) -> bool;
803        Self::is_normal(self) -> bool;
804        Self::classify(self) -> FpCategory;
805        Self::floor(self) -> Self;
806        Self::ceil(self) -> Self;
807        Self::round(self) -> Self;
808        Self::trunc(self) -> Self;
809        Self::fract(self) -> Self;
810        Self::abs(self) -> Self;
811        Self::signum(self) -> Self;
812        Self::is_sign_positive(self) -> bool;
813        Self::is_sign_negative(self) -> bool;
814        Self::min(self, other: Self) -> Self;
815        Self::max(self, other: Self) -> Self;
816        Self::recip(self) -> Self;
817        Self::powi(self, n: i32) -> Self;
818        Self::to_degrees(self) -> Self;
819        Self::to_radians(self) -> Self;
820    }
821}
822
823impl FloatCore for f64 {
824    constant! {
825        infinity() -> f64::INFINITY;
826        neg_infinity() -> f64::NEG_INFINITY;
827        nan() -> f64::NAN;
828        neg_zero() -> -0.0;
829        min_value() -> f64::MIN;
830        min_positive_value() -> f64::MIN_POSITIVE;
831        epsilon() -> f64::EPSILON;
832        max_value() -> f64::MAX;
833    }
834
835    #[inline]
836    fn integer_decode(self) -> (u64, i16, i8) {
837        integer_decode_f64(self)
838    }
839
840    #[inline]
841    #[cfg(not(feature = "std"))]
842    fn classify(self) -> FpCategory {
843        const EXP_MASK: u64 = 0x7ff0000000000000;
844        const MAN_MASK: u64 = 0x000fffffffffffff;
845
846        // Safety: this identical to the implementation of f64::to_bits(),
847        // which is only available starting at Rust 1.20
848        let bits: u64 = unsafe { mem::transmute(self) };
849        match (bits & MAN_MASK, bits & EXP_MASK) {
850            (0, 0) => FpCategory::Zero,
851            (_, 0) => FpCategory::Subnormal,
852            (0, EXP_MASK) => FpCategory::Infinite,
853            (_, EXP_MASK) => FpCategory::Nan,
854            _ => FpCategory::Normal,
855        }
856    }
857
858    #[inline]
859    #[cfg(not(feature = "std"))]
860    fn to_degrees(self) -> Self {
861        // The division here is correctly rounded with respect to the true
862        // value of 180/π. (This differs from f32, where a constant must be
863        // used to ensure a correctly rounded result.)
864        self * (180.0 / f64::consts::PI)
865    }
866
867    #[inline]
868    #[cfg(not(feature = "std"))]
869    fn to_radians(self) -> Self {
870        self * (f64::consts::PI / 180.0)
871    }
872
873    #[cfg(feature = "std")]
874    forward! {
875        Self::is_nan(self) -> bool;
876        Self::is_infinite(self) -> bool;
877        Self::is_finite(self) -> bool;
878        Self::is_normal(self) -> bool;
879        Self::classify(self) -> FpCategory;
880        Self::floor(self) -> Self;
881        Self::ceil(self) -> Self;
882        Self::round(self) -> Self;
883        Self::trunc(self) -> Self;
884        Self::fract(self) -> Self;
885        Self::abs(self) -> Self;
886        Self::signum(self) -> Self;
887        Self::is_sign_positive(self) -> bool;
888        Self::is_sign_negative(self) -> bool;
889        Self::min(self, other: Self) -> Self;
890        Self::max(self, other: Self) -> Self;
891        Self::recip(self) -> Self;
892        Self::powi(self, n: i32) -> Self;
893        Self::to_degrees(self) -> Self;
894        Self::to_radians(self) -> Self;
895    }
896}
897
898// FIXME: these doctests aren't actually helpful, because they're using and
899// testing the inherent methods directly, not going through `Float`.
900
901/// Generic trait for floating point numbers
902///
903/// This trait is only available with the `std` feature, or with the `libm` feature otherwise.
904#[cfg(any(feature = "std", feature = "libm"))]
905pub trait Float: Num + Copy + NumCast + PartialOrd + Neg<Output = Self> {
906    /// Returns the `NaN` value.
907    ///
908    /// ```
909    /// use num_traits::Float;
910    ///
911    /// let nan: f32 = Float::nan();
912    ///
913    /// assert!(nan.is_nan());
914    /// ```
915    fn nan() -> Self;
916    /// Returns the infinite value.
917    ///
918    /// ```
919    /// use num_traits::Float;
920    /// use std::f32;
921    ///
922    /// let infinity: f32 = Float::infinity();
923    ///
924    /// assert!(infinity.is_infinite());
925    /// assert!(!infinity.is_finite());
926    /// assert!(infinity > f32::MAX);
927    /// ```
928    fn infinity() -> Self;
929    /// Returns the negative infinite value.
930    ///
931    /// ```
932    /// use num_traits::Float;
933    /// use std::f32;
934    ///
935    /// let neg_infinity: f32 = Float::neg_infinity();
936    ///
937    /// assert!(neg_infinity.is_infinite());
938    /// assert!(!neg_infinity.is_finite());
939    /// assert!(neg_infinity < f32::MIN);
940    /// ```
941    fn neg_infinity() -> Self;
942    /// Returns `-0.0`.
943    ///
944    /// ```
945    /// use num_traits::{Zero, Float};
946    ///
947    /// let inf: f32 = Float::infinity();
948    /// let zero: f32 = Zero::zero();
949    /// let neg_zero: f32 = Float::neg_zero();
950    ///
951    /// assert_eq!(zero, neg_zero);
952    /// assert_eq!(7.0f32/inf, zero);
953    /// assert_eq!(zero * 10.0, zero);
954    /// ```
955    fn neg_zero() -> Self;
956
957    /// Returns the smallest finite value that this type can represent.
958    ///
959    /// ```
960    /// use num_traits::Float;
961    /// use std::f64;
962    ///
963    /// let x: f64 = Float::min_value();
964    ///
965    /// assert_eq!(x, f64::MIN);
966    /// ```
967    fn min_value() -> Self;
968
969    /// Returns the smallest positive, normalized value that this type can represent.
970    ///
971    /// ```
972    /// use num_traits::Float;
973    /// use std::f64;
974    ///
975    /// let x: f64 = Float::min_positive_value();
976    ///
977    /// assert_eq!(x, f64::MIN_POSITIVE);
978    /// ```
979    fn min_positive_value() -> Self;
980
981    /// Returns epsilon, a small positive value.
982    ///
983    /// ```
984    /// use num_traits::Float;
985    /// use std::f64;
986    ///
987    /// let x: f64 = Float::epsilon();
988    ///
989    /// assert_eq!(x, f64::EPSILON);
990    /// ```
991    ///
992    /// # Panics
993    ///
994    /// The default implementation will panic if `f32::EPSILON` cannot
995    /// be cast to `Self`.
996    fn epsilon() -> Self {
997        Self::from(f32::EPSILON).expect("Unable to cast from f32::EPSILON")
998    }
999
1000    /// Returns the largest finite value that this type can represent.
1001    ///
1002    /// ```
1003    /// use num_traits::Float;
1004    /// use std::f64;
1005    ///
1006    /// let x: f64 = Float::max_value();
1007    /// assert_eq!(x, f64::MAX);
1008    /// ```
1009    fn max_value() -> Self;
1010
1011    /// Returns `true` if this value is `NaN` and false otherwise.
1012    ///
1013    /// ```
1014    /// use num_traits::Float;
1015    /// use std::f64;
1016    ///
1017    /// let nan = f64::NAN;
1018    /// let f = 7.0;
1019    ///
1020    /// assert!(nan.is_nan());
1021    /// assert!(!f.is_nan());
1022    /// ```
1023    fn is_nan(self) -> bool;
1024
1025    /// Returns `true` if this value is positive infinity or negative infinity and
1026    /// false otherwise.
1027    ///
1028    /// ```
1029    /// use num_traits::Float;
1030    /// use std::f32;
1031    ///
1032    /// let f = 7.0f32;
1033    /// let inf: f32 = Float::infinity();
1034    /// let neg_inf: f32 = Float::neg_infinity();
1035    /// let nan: f32 = f32::NAN;
1036    ///
1037    /// assert!(!f.is_infinite());
1038    /// assert!(!nan.is_infinite());
1039    ///
1040    /// assert!(inf.is_infinite());
1041    /// assert!(neg_inf.is_infinite());
1042    /// ```
1043    fn is_infinite(self) -> bool;
1044
1045    /// Returns `true` if this number is neither infinite nor `NaN`.
1046    ///
1047    /// ```
1048    /// use num_traits::Float;
1049    /// use std::f32;
1050    ///
1051    /// let f = 7.0f32;
1052    /// let inf: f32 = Float::infinity();
1053    /// let neg_inf: f32 = Float::neg_infinity();
1054    /// let nan: f32 = f32::NAN;
1055    ///
1056    /// assert!(f.is_finite());
1057    ///
1058    /// assert!(!nan.is_finite());
1059    /// assert!(!inf.is_finite());
1060    /// assert!(!neg_inf.is_finite());
1061    /// ```
1062    fn is_finite(self) -> bool;
1063
1064    /// Returns `true` if the number is neither zero, infinite,
1065    /// [subnormal][subnormal], or `NaN`.
1066    ///
1067    /// ```
1068    /// use num_traits::Float;
1069    /// use std::f32;
1070    ///
1071    /// let min = f32::MIN_POSITIVE; // 1.17549435e-38f32
1072    /// let max = f32::MAX;
1073    /// let lower_than_min = 1.0e-40_f32;
1074    /// let zero = 0.0f32;
1075    ///
1076    /// assert!(min.is_normal());
1077    /// assert!(max.is_normal());
1078    ///
1079    /// assert!(!zero.is_normal());
1080    /// assert!(!f32::NAN.is_normal());
1081    /// assert!(!f32::INFINITY.is_normal());
1082    /// // Values between `0` and `min` are Subnormal.
1083    /// assert!(!lower_than_min.is_normal());
1084    /// ```
1085    /// [subnormal]: http://en.wikipedia.org/wiki/Denormal_number
1086    fn is_normal(self) -> bool;
1087
1088    /// Returns the floating point category of the number. If only one property
1089    /// is going to be tested, it is generally faster to use the specific
1090    /// predicate instead.
1091    ///
1092    /// ```
1093    /// use num_traits::Float;
1094    /// use std::num::FpCategory;
1095    /// use std::f32;
1096    ///
1097    /// let num = 12.4f32;
1098    /// let inf = f32::INFINITY;
1099    ///
1100    /// assert_eq!(num.classify(), FpCategory::Normal);
1101    /// assert_eq!(inf.classify(), FpCategory::Infinite);
1102    /// ```
1103    fn classify(self) -> FpCategory;
1104
1105    /// Returns the largest integer less than or equal to a number.
1106    ///
1107    /// ```
1108    /// use num_traits::Float;
1109    ///
1110    /// let f = 3.99;
1111    /// let g = 3.0;
1112    ///
1113    /// assert_eq!(f.floor(), 3.0);
1114    /// assert_eq!(g.floor(), 3.0);
1115    /// ```
1116    fn floor(self) -> Self;
1117
1118    /// Returns the smallest integer greater than or equal to a number.
1119    ///
1120    /// ```
1121    /// use num_traits::Float;
1122    ///
1123    /// let f = 3.01;
1124    /// let g = 4.0;
1125    ///
1126    /// assert_eq!(f.ceil(), 4.0);
1127    /// assert_eq!(g.ceil(), 4.0);
1128    /// ```
1129    fn ceil(self) -> Self;
1130
1131    /// Returns the nearest integer to a number. Round half-way cases away from
1132    /// `0.0`.
1133    ///
1134    /// ```
1135    /// use num_traits::Float;
1136    ///
1137    /// let f = 3.3;
1138    /// let g = -3.3;
1139    ///
1140    /// assert_eq!(f.round(), 3.0);
1141    /// assert_eq!(g.round(), -3.0);
1142    /// ```
1143    fn round(self) -> Self;
1144
1145    /// Return the integer part of a number.
1146    ///
1147    /// ```
1148    /// use num_traits::Float;
1149    ///
1150    /// let f = 3.3;
1151    /// let g = -3.7;
1152    ///
1153    /// assert_eq!(f.trunc(), 3.0);
1154    /// assert_eq!(g.trunc(), -3.0);
1155    /// ```
1156    fn trunc(self) -> Self;
1157
1158    /// Returns the fractional part of a number.
1159    ///
1160    /// ```
1161    /// use num_traits::Float;
1162    ///
1163    /// let x = 3.5;
1164    /// let y = -3.5;
1165    /// let abs_difference_x = (x.fract() - 0.5).abs();
1166    /// let abs_difference_y = (y.fract() - (-0.5)).abs();
1167    ///
1168    /// assert!(abs_difference_x < 1e-10);
1169    /// assert!(abs_difference_y < 1e-10);
1170    /// ```
1171    fn fract(self) -> Self;
1172
1173    /// Computes the absolute value of `self`. Returns `Float::nan()` if the
1174    /// number is `Float::nan()`.
1175    ///
1176    /// ```
1177    /// use num_traits::Float;
1178    /// use std::f64;
1179    ///
1180    /// let x = 3.5;
1181    /// let y = -3.5;
1182    ///
1183    /// let abs_difference_x = (x.abs() - x).abs();
1184    /// let abs_difference_y = (y.abs() - (-y)).abs();
1185    ///
1186    /// assert!(abs_difference_x < 1e-10);
1187    /// assert!(abs_difference_y < 1e-10);
1188    ///
1189    /// assert!(f64::NAN.abs().is_nan());
1190    /// ```
1191    fn abs(self) -> Self;
1192
1193    /// Returns a number that represents the sign of `self`.
1194    ///
1195    /// - `1.0` if the number is positive, `+0.0` or `Float::infinity()`
1196    /// - `-1.0` if the number is negative, `-0.0` or `Float::neg_infinity()`
1197    /// - `Float::nan()` if the number is `Float::nan()`
1198    ///
1199    /// ```
1200    /// use num_traits::Float;
1201    /// use std::f64;
1202    ///
1203    /// let f = 3.5;
1204    ///
1205    /// assert_eq!(f.signum(), 1.0);
1206    /// assert_eq!(f64::NEG_INFINITY.signum(), -1.0);
1207    ///
1208    /// assert!(f64::NAN.signum().is_nan());
1209    /// ```
1210    fn signum(self) -> Self;
1211
1212    /// Returns `true` if `self` is positive, including `+0.0`,
1213    /// `Float::infinity()`, and since Rust 1.20 also `Float::nan()`.
1214    ///
1215    /// ```
1216    /// use num_traits::Float;
1217    /// use std::f64;
1218    ///
1219    /// let neg_nan: f64 = -f64::NAN;
1220    ///
1221    /// let f = 7.0;
1222    /// let g = -7.0;
1223    ///
1224    /// assert!(f.is_sign_positive());
1225    /// assert!(!g.is_sign_positive());
1226    /// assert!(!neg_nan.is_sign_positive());
1227    /// ```
1228    fn is_sign_positive(self) -> bool;
1229
1230    /// Returns `true` if `self` is negative, including `-0.0`,
1231    /// `Float::neg_infinity()`, and since Rust 1.20 also `-Float::nan()`.
1232    ///
1233    /// ```
1234    /// use num_traits::Float;
1235    /// use std::f64;
1236    ///
1237    /// let nan: f64 = f64::NAN;
1238    ///
1239    /// let f = 7.0;
1240    /// let g = -7.0;
1241    ///
1242    /// assert!(!f.is_sign_negative());
1243    /// assert!(g.is_sign_negative());
1244    /// assert!(!nan.is_sign_negative());
1245    /// ```
1246    fn is_sign_negative(self) -> bool;
1247
1248    /// Fused multiply-add. Computes `(self * a) + b` with only one rounding
1249    /// error, yielding a more accurate result than an unfused multiply-add.
1250    ///
1251    /// Using `mul_add` can be more performant than an unfused multiply-add if
1252    /// the target architecture has a dedicated `fma` CPU instruction.
1253    ///
1254    /// ```
1255    /// use num_traits::Float;
1256    ///
1257    /// let m = 10.0;
1258    /// let x = 4.0;
1259    /// let b = 60.0;
1260    ///
1261    /// // 100.0
1262    /// let abs_difference = (m.mul_add(x, b) - (m*x + b)).abs();
1263    ///
1264    /// assert!(abs_difference < 1e-10);
1265    /// ```
1266    fn mul_add(self, a: Self, b: Self) -> Self;
1267    /// Take the reciprocal (inverse) of a number, `1/x`.
1268    ///
1269    /// ```
1270    /// use num_traits::Float;
1271    ///
1272    /// let x = 2.0;
1273    /// let abs_difference = (x.recip() - (1.0/x)).abs();
1274    ///
1275    /// assert!(abs_difference < 1e-10);
1276    /// ```
1277    fn recip(self) -> Self;
1278
1279    /// Raise a number to an integer power.
1280    ///
1281    /// Using this function is generally faster than using `powf`
1282    ///
1283    /// ```
1284    /// use num_traits::Float;
1285    ///
1286    /// let x = 2.0;
1287    /// let abs_difference = (x.powi(2) - x*x).abs();
1288    ///
1289    /// assert!(abs_difference < 1e-10);
1290    /// ```
1291    fn powi(self, n: i32) -> Self;
1292
1293    /// Raise a number to a floating point power.
1294    ///
1295    /// ```
1296    /// use num_traits::Float;
1297    ///
1298    /// let x = 2.0;
1299    /// let abs_difference = (x.powf(2.0) - x*x).abs();
1300    ///
1301    /// assert!(abs_difference < 1e-10);
1302    /// ```
1303    fn powf(self, n: Self) -> Self;
1304
1305    /// Take the square root of a number.
1306    ///
1307    /// Returns NaN if `self` is a negative number.
1308    ///
1309    /// ```
1310    /// use num_traits::Float;
1311    ///
1312    /// let positive = 4.0;
1313    /// let negative = -4.0;
1314    ///
1315    /// let abs_difference = (positive.sqrt() - 2.0).abs();
1316    ///
1317    /// assert!(abs_difference < 1e-10);
1318    /// assert!(negative.sqrt().is_nan());
1319    /// ```
1320    fn sqrt(self) -> Self;
1321
1322    /// Returns `e^(self)`, (the exponential function).
1323    ///
1324    /// ```
1325    /// use num_traits::Float;
1326    ///
1327    /// let one = 1.0;
1328    /// // e^1
1329    /// let e = one.exp();
1330    ///
1331    /// // ln(e) - 1 == 0
1332    /// let abs_difference = (e.ln() - 1.0).abs();
1333    ///
1334    /// assert!(abs_difference < 1e-10);
1335    /// ```
1336    fn exp(self) -> Self;
1337
1338    /// Returns `2^(self)`.
1339    ///
1340    /// ```
1341    /// use num_traits::Float;
1342    ///
1343    /// let f = 2.0;
1344    ///
1345    /// // 2^2 - 4 == 0
1346    /// let abs_difference = (f.exp2() - 4.0).abs();
1347    ///
1348    /// assert!(abs_difference < 1e-10);
1349    /// ```
1350    fn exp2(self) -> Self;
1351
1352    /// Returns the natural logarithm of the number.
1353    ///
1354    /// ```
1355    /// use num_traits::Float;
1356    ///
1357    /// let one = 1.0;
1358    /// // e^1
1359    /// let e = one.exp();
1360    ///
1361    /// // ln(e) - 1 == 0
1362    /// let abs_difference = (e.ln() - 1.0).abs();
1363    ///
1364    /// assert!(abs_difference < 1e-10);
1365    /// ```
1366    fn ln(self) -> Self;
1367
1368    /// Returns the logarithm of the number with respect to an arbitrary base.
1369    ///
1370    /// ```
1371    /// use num_traits::Float;
1372    ///
1373    /// let ten = 10.0;
1374    /// let two = 2.0;
1375    ///
1376    /// // log10(10) - 1 == 0
1377    /// let abs_difference_10 = (ten.log(10.0) - 1.0).abs();
1378    ///
1379    /// // log2(2) - 1 == 0
1380    /// let abs_difference_2 = (two.log(2.0) - 1.0).abs();
1381    ///
1382    /// assert!(abs_difference_10 < 1e-10);
1383    /// assert!(abs_difference_2 < 1e-10);
1384    /// ```
1385    fn log(self, base: Self) -> Self;
1386
1387    /// Returns the base 2 logarithm of the number.
1388    ///
1389    /// ```
1390    /// use num_traits::Float;
1391    ///
1392    /// let two = 2.0;
1393    ///
1394    /// // log2(2) - 1 == 0
1395    /// let abs_difference = (two.log2() - 1.0).abs();
1396    ///
1397    /// assert!(abs_difference < 1e-10);
1398    /// ```
1399    fn log2(self) -> Self;
1400
1401    /// Returns the base 10 logarithm of the number.
1402    ///
1403    /// ```
1404    /// use num_traits::Float;
1405    ///
1406    /// let ten = 10.0;
1407    ///
1408    /// // log10(10) - 1 == 0
1409    /// let abs_difference = (ten.log10() - 1.0).abs();
1410    ///
1411    /// assert!(abs_difference < 1e-10);
1412    /// ```
1413    fn log10(self) -> Self;
1414
1415    /// Converts radians to degrees.
1416    ///
1417    /// ```
1418    /// use std::f64::consts;
1419    ///
1420    /// let angle = consts::PI;
1421    ///
1422    /// let abs_difference = (angle.to_degrees() - 180.0).abs();
1423    ///
1424    /// assert!(abs_difference < 1e-10);
1425    /// ```
1426    #[inline]
1427    fn to_degrees(self) -> Self {
1428        let halfpi = Self::zero().acos();
1429        let ninety = Self::from(90u8).unwrap();
1430        self * ninety / halfpi
1431    }
1432
1433    /// Converts degrees to radians.
1434    ///
1435    /// ```
1436    /// use std::f64::consts;
1437    ///
1438    /// let angle = 180.0_f64;
1439    ///
1440    /// let abs_difference = (angle.to_radians() - consts::PI).abs();
1441    ///
1442    /// assert!(abs_difference < 1e-10);
1443    /// ```
1444    #[inline]
1445    fn to_radians(self) -> Self {
1446        let halfpi = Self::zero().acos();
1447        let ninety = Self::from(90u8).unwrap();
1448        self * halfpi / ninety
1449    }
1450
1451    /// Returns the maximum of the two numbers.
1452    ///
1453    /// ```
1454    /// use num_traits::Float;
1455    ///
1456    /// let x = 1.0;
1457    /// let y = 2.0;
1458    ///
1459    /// assert_eq!(x.max(y), y);
1460    /// ```
1461    fn max(self, other: Self) -> Self;
1462
1463    /// Returns the minimum of the two numbers.
1464    ///
1465    /// ```
1466    /// use num_traits::Float;
1467    ///
1468    /// let x = 1.0;
1469    /// let y = 2.0;
1470    ///
1471    /// assert_eq!(x.min(y), x);
1472    /// ```
1473    fn min(self, other: Self) -> Self;
1474
1475    /// The positive difference of two numbers.
1476    ///
1477    /// * If `self <= other`: `0:0`
1478    /// * Else: `self - other`
1479    ///
1480    /// ```
1481    /// use num_traits::Float;
1482    ///
1483    /// let x = 3.0;
1484    /// let y = -3.0;
1485    ///
1486    /// let abs_difference_x = (x.abs_sub(1.0) - 2.0).abs();
1487    /// let abs_difference_y = (y.abs_sub(1.0) - 0.0).abs();
1488    ///
1489    /// assert!(abs_difference_x < 1e-10);
1490    /// assert!(abs_difference_y < 1e-10);
1491    /// ```
1492    fn abs_sub(self, other: Self) -> Self;
1493
1494    /// Take the cubic root of a number.
1495    ///
1496    /// ```
1497    /// use num_traits::Float;
1498    ///
1499    /// let x = 8.0;
1500    ///
1501    /// // x^(1/3) - 2 == 0
1502    /// let abs_difference = (x.cbrt() - 2.0).abs();
1503    ///
1504    /// assert!(abs_difference < 1e-10);
1505    /// ```
1506    fn cbrt(self) -> Self;
1507
1508    /// Calculate the length of the hypotenuse of a right-angle triangle given
1509    /// legs of length `x` and `y`.
1510    ///
1511    /// ```
1512    /// use num_traits::Float;
1513    ///
1514    /// let x = 2.0;
1515    /// let y = 3.0;
1516    ///
1517    /// // sqrt(x^2 + y^2)
1518    /// let abs_difference = (x.hypot(y) - (x.powi(2) + y.powi(2)).sqrt()).abs();
1519    ///
1520    /// assert!(abs_difference < 1e-10);
1521    /// ```
1522    fn hypot(self, other: Self) -> Self;
1523
1524    /// Computes the sine of a number (in radians).
1525    ///
1526    /// ```
1527    /// use num_traits::Float;
1528    /// use std::f64;
1529    ///
1530    /// let x = f64::consts::PI/2.0;
1531    ///
1532    /// let abs_difference = (x.sin() - 1.0).abs();
1533    ///
1534    /// assert!(abs_difference < 1e-10);
1535    /// ```
1536    fn sin(self) -> Self;
1537
1538    /// Computes the cosine of a number (in radians).
1539    ///
1540    /// ```
1541    /// use num_traits::Float;
1542    /// use std::f64;
1543    ///
1544    /// let x = 2.0*f64::consts::PI;
1545    ///
1546    /// let abs_difference = (x.cos() - 1.0).abs();
1547    ///
1548    /// assert!(abs_difference < 1e-10);
1549    /// ```
1550    fn cos(self) -> Self;
1551
1552    /// Computes the tangent of a number (in radians).
1553    ///
1554    /// ```
1555    /// use num_traits::Float;
1556    /// use std::f64;
1557    ///
1558    /// let x = f64::consts::PI/4.0;
1559    /// let abs_difference = (x.tan() - 1.0).abs();
1560    ///
1561    /// assert!(abs_difference < 1e-14);
1562    /// ```
1563    fn tan(self) -> Self;
1564
1565    /// Computes the arcsine of a number. Return value is in radians in
1566    /// the range [-pi/2, pi/2] or NaN if the number is outside the range
1567    /// [-1, 1].
1568    ///
1569    /// ```
1570    /// use num_traits::Float;
1571    /// use std::f64;
1572    ///
1573    /// let f = f64::consts::PI / 2.0;
1574    ///
1575    /// // asin(sin(pi/2))
1576    /// let abs_difference = (f.sin().asin() - f64::consts::PI / 2.0).abs();
1577    ///
1578    /// assert!(abs_difference < 1e-10);
1579    /// ```
1580    fn asin(self) -> Self;
1581
1582    /// Computes the arccosine of a number. Return value is in radians in
1583    /// the range [0, pi] or NaN if the number is outside the range
1584    /// [-1, 1].
1585    ///
1586    /// ```
1587    /// use num_traits::Float;
1588    /// use std::f64;
1589    ///
1590    /// let f = f64::consts::PI / 4.0;
1591    ///
1592    /// // acos(cos(pi/4))
1593    /// let abs_difference = (f.cos().acos() - f64::consts::PI / 4.0).abs();
1594    ///
1595    /// assert!(abs_difference < 1e-10);
1596    /// ```
1597    fn acos(self) -> Self;
1598
1599    /// Computes the arctangent of a number. Return value is in radians in the
1600    /// range [-pi/2, pi/2];
1601    ///
1602    /// ```
1603    /// use num_traits::Float;
1604    ///
1605    /// let f = 1.0;
1606    ///
1607    /// // atan(tan(1))
1608    /// let abs_difference = (f.tan().atan() - 1.0).abs();
1609    ///
1610    /// assert!(abs_difference < 1e-10);
1611    /// ```
1612    fn atan(self) -> Self;
1613
1614    /// Computes the four quadrant arctangent of `self` (`y`) and `other` (`x`).
1615    ///
1616    /// * `x = 0`, `y = 0`: `0`
1617    /// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]`
1618    /// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]`
1619    /// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)`
1620    ///
1621    /// ```
1622    /// use num_traits::Float;
1623    /// use std::f64;
1624    ///
1625    /// let pi = f64::consts::PI;
1626    /// // All angles from horizontal right (+x)
1627    /// // 45 deg counter-clockwise
1628    /// let x1 = 3.0;
1629    /// let y1 = -3.0;
1630    ///
1631    /// // 135 deg clockwise
1632    /// let x2 = -3.0;
1633    /// let y2 = 3.0;
1634    ///
1635    /// let abs_difference_1 = (y1.atan2(x1) - (-pi/4.0)).abs();
1636    /// let abs_difference_2 = (y2.atan2(x2) - 3.0*pi/4.0).abs();
1637    ///
1638    /// assert!(abs_difference_1 < 1e-10);
1639    /// assert!(abs_difference_2 < 1e-10);
1640    /// ```
1641    fn atan2(self, other: Self) -> Self;
1642
1643    /// Simultaneously computes the sine and cosine of the number, `x`. Returns
1644    /// `(sin(x), cos(x))`.
1645    ///
1646    /// ```
1647    /// use num_traits::Float;
1648    /// use std::f64;
1649    ///
1650    /// let x = f64::consts::PI/4.0;
1651    /// let f = x.sin_cos();
1652    ///
1653    /// let abs_difference_0 = (f.0 - x.sin()).abs();
1654    /// let abs_difference_1 = (f.1 - x.cos()).abs();
1655    ///
1656    /// assert!(abs_difference_0 < 1e-10);
1657    /// assert!(abs_difference_0 < 1e-10);
1658    /// ```
1659    fn sin_cos(self) -> (Self, Self);
1660
1661    /// Returns `e^(self) - 1` in a way that is accurate even if the
1662    /// number is close to zero.
1663    ///
1664    /// ```
1665    /// use num_traits::Float;
1666    ///
1667    /// let x = 7.0;
1668    ///
1669    /// // e^(ln(7)) - 1
1670    /// let abs_difference = (x.ln().exp_m1() - 6.0).abs();
1671    ///
1672    /// assert!(abs_difference < 1e-10);
1673    /// ```
1674    fn exp_m1(self) -> Self;
1675
1676    /// Returns `ln(1+n)` (natural logarithm) more accurately than if
1677    /// the operations were performed separately.
1678    ///
1679    /// ```
1680    /// use num_traits::Float;
1681    /// use std::f64;
1682    ///
1683    /// let x = f64::consts::E - 1.0;
1684    ///
1685    /// // ln(1 + (e - 1)) == ln(e) == 1
1686    /// let abs_difference = (x.ln_1p() - 1.0).abs();
1687    ///
1688    /// assert!(abs_difference < 1e-10);
1689    /// ```
1690    fn ln_1p(self) -> Self;
1691
1692    /// Hyperbolic sine function.
1693    ///
1694    /// ```
1695    /// use num_traits::Float;
1696    /// use std::f64;
1697    ///
1698    /// let e = f64::consts::E;
1699    /// let x = 1.0;
1700    ///
1701    /// let f = x.sinh();
1702    /// // Solving sinh() at 1 gives `(e^2-1)/(2e)`
1703    /// let g = (e*e - 1.0)/(2.0*e);
1704    /// let abs_difference = (f - g).abs();
1705    ///
1706    /// assert!(abs_difference < 1e-10);
1707    /// ```
1708    fn sinh(self) -> Self;
1709
1710    /// Hyperbolic cosine function.
1711    ///
1712    /// ```
1713    /// use num_traits::Float;
1714    /// use std::f64;
1715    ///
1716    /// let e = f64::consts::E;
1717    /// let x = 1.0;
1718    /// let f = x.cosh();
1719    /// // Solving cosh() at 1 gives this result
1720    /// let g = (e*e + 1.0)/(2.0*e);
1721    /// let abs_difference = (f - g).abs();
1722    ///
1723    /// // Same result
1724    /// assert!(abs_difference < 1.0e-10);
1725    /// ```
1726    fn cosh(self) -> Self;
1727
1728    /// Hyperbolic tangent function.
1729    ///
1730    /// ```
1731    /// use num_traits::Float;
1732    /// use std::f64;
1733    ///
1734    /// let e = f64::consts::E;
1735    /// let x = 1.0;
1736    ///
1737    /// let f = x.tanh();
1738    /// // Solving tanh() at 1 gives `(1 - e^(-2))/(1 + e^(-2))`
1739    /// let g = (1.0 - e.powi(-2))/(1.0 + e.powi(-2));
1740    /// let abs_difference = (f - g).abs();
1741    ///
1742    /// assert!(abs_difference < 1.0e-10);
1743    /// ```
1744    fn tanh(self) -> Self;
1745
1746    /// Inverse hyperbolic sine function.
1747    ///
1748    /// ```
1749    /// use num_traits::Float;
1750    ///
1751    /// let x = 1.0;
1752    /// let f = x.sinh().asinh();
1753    ///
1754    /// let abs_difference = (f - x).abs();
1755    ///
1756    /// assert!(abs_difference < 1.0e-10);
1757    /// ```
1758    fn asinh(self) -> Self;
1759
1760    /// Inverse hyperbolic cosine function.
1761    ///
1762    /// ```
1763    /// use num_traits::Float;
1764    ///
1765    /// let x = 1.0;
1766    /// let f = x.cosh().acosh();
1767    ///
1768    /// let abs_difference = (f - x).abs();
1769    ///
1770    /// assert!(abs_difference < 1.0e-10);
1771    /// ```
1772    fn acosh(self) -> Self;
1773
1774    /// Inverse hyperbolic tangent function.
1775    ///
1776    /// ```
1777    /// use num_traits::Float;
1778    /// use std::f64;
1779    ///
1780    /// let e = f64::consts::E;
1781    /// let f = e.tanh().atanh();
1782    ///
1783    /// let abs_difference = (f - e).abs();
1784    ///
1785    /// assert!(abs_difference < 1.0e-10);
1786    /// ```
1787    fn atanh(self) -> Self;
1788
1789    /// Returns the mantissa, base 2 exponent, and sign as integers, respectively.
1790    /// The original number can be recovered by `sign * mantissa * 2 ^ exponent`.
1791    ///
1792    /// ```
1793    /// use num_traits::Float;
1794    ///
1795    /// let num = 2.0f32;
1796    ///
1797    /// // (8388608, -22, 1)
1798    /// let (mantissa, exponent, sign) = Float::integer_decode(num);
1799    /// let sign_f = sign as f32;
1800    /// let mantissa_f = mantissa as f32;
1801    /// let exponent_f = num.powf(exponent as f32);
1802    ///
1803    /// // 1 * 8388608 * 2^(-22) == 2
1804    /// let abs_difference = (sign_f * mantissa_f * exponent_f - num).abs();
1805    ///
1806    /// assert!(abs_difference < 1e-10);
1807    /// ```
1808    fn integer_decode(self) -> (u64, i16, i8);
1809}
1810
1811#[cfg(feature = "std")]
1812macro_rules! float_impl_std {
1813    ($T:ident $decode:ident) => {
1814        impl Float for $T {
1815            constant! {
1816                nan() -> $T::NAN;
1817                infinity() -> $T::INFINITY;
1818                neg_infinity() -> $T::NEG_INFINITY;
1819                neg_zero() -> -0.0;
1820                min_value() -> $T::MIN;
1821                min_positive_value() -> $T::MIN_POSITIVE;
1822                epsilon() -> $T::EPSILON;
1823                max_value() -> $T::MAX;
1824            }
1825
1826            #[inline]
1827            #[allow(deprecated)]
1828            fn abs_sub(self, other: Self) -> Self {
1829                <$T>::abs_sub(self, other)
1830            }
1831
1832            #[inline]
1833            fn integer_decode(self) -> (u64, i16, i8) {
1834                $decode(self)
1835            }
1836
1837            forward! {
1838                Self::is_nan(self) -> bool;
1839                Self::is_infinite(self) -> bool;
1840                Self::is_finite(self) -> bool;
1841                Self::is_normal(self) -> bool;
1842                Self::classify(self) -> FpCategory;
1843                Self::floor(self) -> Self;
1844                Self::ceil(self) -> Self;
1845                Self::round(self) -> Self;
1846                Self::trunc(self) -> Self;
1847                Self::fract(self) -> Self;
1848                Self::abs(self) -> Self;
1849                Self::signum(self) -> Self;
1850                Self::is_sign_positive(self) -> bool;
1851                Self::is_sign_negative(self) -> bool;
1852                Self::mul_add(self, a: Self, b: Self) -> Self;
1853                Self::recip(self) -> Self;
1854                Self::powi(self, n: i32) -> Self;
1855                Self::powf(self, n: Self) -> Self;
1856                Self::sqrt(self) -> Self;
1857                Self::exp(self) -> Self;
1858                Self::exp2(self) -> Self;
1859                Self::ln(self) -> Self;
1860                Self::log(self, base: Self) -> Self;
1861                Self::log2(self) -> Self;
1862                Self::log10(self) -> Self;
1863                Self::to_degrees(self) -> Self;
1864                Self::to_radians(self) -> Self;
1865                Self::max(self, other: Self) -> Self;
1866                Self::min(self, other: Self) -> Self;
1867                Self::cbrt(self) -> Self;
1868                Self::hypot(self, other: Self) -> Self;
1869                Self::sin(self) -> Self;
1870                Self::cos(self) -> Self;
1871                Self::tan(self) -> Self;
1872                Self::asin(self) -> Self;
1873                Self::acos(self) -> Self;
1874                Self::atan(self) -> Self;
1875                Self::atan2(self, other: Self) -> Self;
1876                Self::sin_cos(self) -> (Self, Self);
1877                Self::exp_m1(self) -> Self;
1878                Self::ln_1p(self) -> Self;
1879                Self::sinh(self) -> Self;
1880                Self::cosh(self) -> Self;
1881                Self::tanh(self) -> Self;
1882                Self::asinh(self) -> Self;
1883                Self::acosh(self) -> Self;
1884                Self::atanh(self) -> Self;
1885            }
1886        }
1887    };
1888}
1889
1890#[cfg(all(not(feature = "std"), feature = "libm"))]
1891macro_rules! float_impl_libm {
1892    ($T:ident $decode:ident) => {
1893        constant! {
1894            nan() -> $T::NAN;
1895            infinity() -> $T::INFINITY;
1896            neg_infinity() -> $T::NEG_INFINITY;
1897            neg_zero() -> -0.0;
1898            min_value() -> $T::MIN;
1899            min_positive_value() -> $T::MIN_POSITIVE;
1900            epsilon() -> $T::EPSILON;
1901            max_value() -> $T::MAX;
1902        }
1903
1904        #[inline]
1905        fn integer_decode(self) -> (u64, i16, i8) {
1906            $decode(self)
1907        }
1908
1909        #[inline]
1910        fn fract(self) -> Self {
1911            self - FloatCore::trunc(self)
1912        }
1913
1914        #[inline]
1915        fn log(self, base: Self) -> Self {
1916            self.ln() / base.ln()
1917        }
1918
1919        forward! {
1920            FloatCore::is_nan(self) -> bool;
1921            FloatCore::is_infinite(self) -> bool;
1922            FloatCore::is_finite(self) -> bool;
1923            FloatCore::is_normal(self) -> bool;
1924            FloatCore::classify(self) -> FpCategory;
1925            FloatCore::signum(self) -> Self;
1926            FloatCore::is_sign_positive(self) -> bool;
1927            FloatCore::is_sign_negative(self) -> bool;
1928            FloatCore::recip(self) -> Self;
1929            FloatCore::powi(self, n: i32) -> Self;
1930            FloatCore::to_degrees(self) -> Self;
1931            FloatCore::to_radians(self) -> Self;
1932            FloatCore::max(self, other: Self) -> Self;
1933            FloatCore::min(self, other: Self) -> Self;
1934        }
1935    };
1936}
1937
1938fn integer_decode_f32(f: f32) -> (u64, i16, i8) {
1939    // Safety: this identical to the implementation of f32::to_bits(),
1940    // which is only available starting at Rust 1.20
1941    let bits: u32 = unsafe { mem::transmute(f) };
1942    let sign: i8 = if bits >> 31 == 0 { 1 } else { -1 };
1943    let mut exponent: i16 = ((bits >> 23) & 0xff) as i16;
1944    let mantissa = if exponent == 0 {
1945        (bits & 0x7fffff) << 1
1946    } else {
1947        (bits & 0x7fffff) | 0x800000
1948    };
1949    // Exponent bias + mantissa shift
1950    exponent -= 127 + 23;
1951    (mantissa as u64, exponent, sign)
1952}
1953
1954fn integer_decode_f64(f: f64) -> (u64, i16, i8) {
1955    // Safety: this identical to the implementation of f64::to_bits(),
1956    // which is only available starting at Rust 1.20
1957    let bits: u64 = unsafe { mem::transmute(f) };
1958    let sign: i8 = if bits >> 63 == 0 { 1 } else { -1 };
1959    let mut exponent: i16 = ((bits >> 52) & 0x7ff) as i16;
1960    let mantissa = if exponent == 0 {
1961        (bits & 0xfffffffffffff) << 1
1962    } else {
1963        (bits & 0xfffffffffffff) | 0x10000000000000
1964    };
1965    // Exponent bias + mantissa shift
1966    exponent -= 1023 + 52;
1967    (mantissa, exponent, sign)
1968}
1969
1970#[cfg(feature = "std")]
1971float_impl_std!(f32 integer_decode_f32);
1972#[cfg(feature = "std")]
1973float_impl_std!(f64 integer_decode_f64);
1974
1975#[cfg(all(not(feature = "std"), feature = "libm"))]
1976impl Float for f32 {
1977    float_impl_libm!(f32 integer_decode_f32);
1978
1979    #[inline]
1980    #[allow(deprecated)]
1981    fn abs_sub(self, other: Self) -> Self {
1982        libm::fdimf(self, other)
1983    }
1984    #[inline]
1985    fn floor(self) -> Self {
1986        libm::floorf(self)
1987    }
1988    #[inline]
1989    fn ceil(self) -> Self {
1990        libm::ceilf(self)
1991    }
1992    #[inline]
1993    fn round(self) -> Self {
1994        libm::roundf(self)
1995    }
1996    #[inline]
1997    fn trunc(self) -> Self {
1998        libm::truncf(self)
1999    }
2000    #[inline]
2001    fn abs(self) -> Self {
2002        libm::fabsf(self)
2003    }
2004    #[inline]
2005    fn mul_add(self, a: Self, b: Self) -> Self {
2006        libm::fmaf(self, a, b)
2007    }
2008    #[inline]
2009    fn powf(self, n: Self) -> Self {
2010        libm::powf(self, n)
2011    }
2012    #[inline]
2013    fn sqrt(self) -> Self {
2014        libm::sqrtf(self)
2015    }
2016    #[inline]
2017    fn exp(self) -> Self {
2018        libm::expf(self)
2019    }
2020    #[inline]
2021    fn exp2(self) -> Self {
2022        libm::exp2f(self)
2023    }
2024    #[inline]
2025    fn ln(self) -> Self {
2026        libm::logf(self)
2027    }
2028    #[inline]
2029    fn log2(self) -> Self {
2030        libm::log2f(self)
2031    }
2032    #[inline]
2033    fn log10(self) -> Self {
2034        libm::log10f(self)
2035    }
2036    #[inline]
2037    fn cbrt(self) -> Self {
2038        libm::cbrtf(self)
2039    }
2040    #[inline]
2041    fn hypot(self, other: Self) -> Self {
2042        libm::hypotf(self, other)
2043    }
2044    #[inline]
2045    fn sin(self) -> Self {
2046        libm::sinf(self)
2047    }
2048    #[inline]
2049    fn cos(self) -> Self {
2050        libm::cosf(self)
2051    }
2052    #[inline]
2053    fn tan(self) -> Self {
2054        libm::tanf(self)
2055    }
2056    #[inline]
2057    fn asin(self) -> Self {
2058        libm::asinf(self)
2059    }
2060    #[inline]
2061    fn acos(self) -> Self {
2062        libm::acosf(self)
2063    }
2064    #[inline]
2065    fn atan(self) -> Self {
2066        libm::atanf(self)
2067    }
2068    #[inline]
2069    fn atan2(self, other: Self) -> Self {
2070        libm::atan2f(self, other)
2071    }
2072    #[inline]
2073    fn sin_cos(self) -> (Self, Self) {
2074        libm::sincosf(self)
2075    }
2076    #[inline]
2077    fn exp_m1(self) -> Self {
2078        libm::expm1f(self)
2079    }
2080    #[inline]
2081    fn ln_1p(self) -> Self {
2082        libm::log1pf(self)
2083    }
2084    #[inline]
2085    fn sinh(self) -> Self {
2086        libm::sinhf(self)
2087    }
2088    #[inline]
2089    fn cosh(self) -> Self {
2090        libm::coshf(self)
2091    }
2092    #[inline]
2093    fn tanh(self) -> Self {
2094        libm::tanhf(self)
2095    }
2096    #[inline]
2097    fn asinh(self) -> Self {
2098        libm::asinhf(self)
2099    }
2100    #[inline]
2101    fn acosh(self) -> Self {
2102        libm::acoshf(self)
2103    }
2104    #[inline]
2105    fn atanh(self) -> Self {
2106        libm::atanhf(self)
2107    }
2108}
2109
2110#[cfg(all(not(feature = "std"), feature = "libm"))]
2111impl Float for f64 {
2112    float_impl_libm!(f64 integer_decode_f64);
2113
2114    #[inline]
2115    #[allow(deprecated)]
2116    fn abs_sub(self, other: Self) -> Self {
2117        libm::fdim(self, other)
2118    }
2119    #[inline]
2120    fn floor(self) -> Self {
2121        libm::floor(self)
2122    }
2123    #[inline]
2124    fn ceil(self) -> Self {
2125        libm::ceil(self)
2126    }
2127    #[inline]
2128    fn round(self) -> Self {
2129        libm::round(self)
2130    }
2131    #[inline]
2132    fn trunc(self) -> Self {
2133        libm::trunc(self)
2134    }
2135    #[inline]
2136    fn abs(self) -> Self {
2137        libm::fabs(self)
2138    }
2139    #[inline]
2140    fn mul_add(self, a: Self, b: Self) -> Self {
2141        libm::fma(self, a, b)
2142    }
2143    #[inline]
2144    fn powf(self, n: Self) -> Self {
2145        libm::pow(self, n)
2146    }
2147    #[inline]
2148    fn sqrt(self) -> Self {
2149        libm::sqrt(self)
2150    }
2151    #[inline]
2152    fn exp(self) -> Self {
2153        libm::exp(self)
2154    }
2155    #[inline]
2156    fn exp2(self) -> Self {
2157        libm::exp2(self)
2158    }
2159    #[inline]
2160    fn ln(self) -> Self {
2161        libm::log(self)
2162    }
2163    #[inline]
2164    fn log2(self) -> Self {
2165        libm::log2(self)
2166    }
2167    #[inline]
2168    fn log10(self) -> Self {
2169        libm::log10(self)
2170    }
2171    #[inline]
2172    fn cbrt(self) -> Self {
2173        libm::cbrt(self)
2174    }
2175    #[inline]
2176    fn hypot(self, other: Self) -> Self {
2177        libm::hypot(self, other)
2178    }
2179    #[inline]
2180    fn sin(self) -> Self {
2181        libm::sin(self)
2182    }
2183    #[inline]
2184    fn cos(self) -> Self {
2185        libm::cos(self)
2186    }
2187    #[inline]
2188    fn tan(self) -> Self {
2189        libm::tan(self)
2190    }
2191    #[inline]
2192    fn asin(self) -> Self {
2193        libm::asin(self)
2194    }
2195    #[inline]
2196    fn acos(self) -> Self {
2197        libm::acos(self)
2198    }
2199    #[inline]
2200    fn atan(self) -> Self {
2201        libm::atan(self)
2202    }
2203    #[inline]
2204    fn atan2(self, other: Self) -> Self {
2205        libm::atan2(self, other)
2206    }
2207    #[inline]
2208    fn sin_cos(self) -> (Self, Self) {
2209        libm::sincos(self)
2210    }
2211    #[inline]
2212    fn exp_m1(self) -> Self {
2213        libm::expm1(self)
2214    }
2215    #[inline]
2216    fn ln_1p(self) -> Self {
2217        libm::log1p(self)
2218    }
2219    #[inline]
2220    fn sinh(self) -> Self {
2221        libm::sinh(self)
2222    }
2223    #[inline]
2224    fn cosh(self) -> Self {
2225        libm::cosh(self)
2226    }
2227    #[inline]
2228    fn tanh(self) -> Self {
2229        libm::tanh(self)
2230    }
2231    #[inline]
2232    fn asinh(self) -> Self {
2233        libm::asinh(self)
2234    }
2235    #[inline]
2236    fn acosh(self) -> Self {
2237        libm::acosh(self)
2238    }
2239    #[inline]
2240    fn atanh(self) -> Self {
2241        libm::atanh(self)
2242    }
2243}
2244
2245macro_rules! float_const_impl {
2246    ($(#[$doc:meta] $constant:ident,)+) => (
2247        #[allow(non_snake_case)]
2248        pub trait FloatConst {
2249            $(#[$doc] fn $constant() -> Self;)+
2250        }
2251        float_const_impl! { @float f32, $($constant,)+ }
2252        float_const_impl! { @float f64, $($constant,)+ }
2253    );
2254    (@float $T:ident, $($constant:ident,)+) => (
2255        impl FloatConst for $T {
2256            constant! {
2257                $( $constant() -> $T::consts::$constant; )+
2258            }
2259        }
2260    );
2261}
2262
2263float_const_impl! {
2264    #[doc = "Return Euler’s number."]
2265    E,
2266    #[doc = "Return `1.0 / π`."]
2267    FRAC_1_PI,
2268    #[doc = "Return `1.0 / sqrt(2.0)`."]
2269    FRAC_1_SQRT_2,
2270    #[doc = "Return `2.0 / π`."]
2271    FRAC_2_PI,
2272    #[doc = "Return `2.0 / sqrt(π)`."]
2273    FRAC_2_SQRT_PI,
2274    #[doc = "Return `π / 2.0`."]
2275    FRAC_PI_2,
2276    #[doc = "Return `π / 3.0`."]
2277    FRAC_PI_3,
2278    #[doc = "Return `π / 4.0`."]
2279    FRAC_PI_4,
2280    #[doc = "Return `π / 6.0`."]
2281    FRAC_PI_6,
2282    #[doc = "Return `π / 8.0`."]
2283    FRAC_PI_8,
2284    #[doc = "Return `ln(10.0)`."]
2285    LN_10,
2286    #[doc = "Return `ln(2.0)`."]
2287    LN_2,
2288    #[doc = "Return `log10(e)`."]
2289    LOG10_E,
2290    #[doc = "Return `log2(e)`."]
2291    LOG2_E,
2292    #[doc = "Return Archimedes’ constant."]
2293    PI,
2294    #[doc = "Return `sqrt(2.0)`."]
2295    SQRT_2,
2296}
2297
2298#[cfg(test)]
2299mod tests {
2300    use core::f64::consts;
2301
2302    const DEG_RAD_PAIRS: [(f64, f64); 7] = [
2303        (0.0, 0.),
2304        (22.5, consts::FRAC_PI_8),
2305        (30.0, consts::FRAC_PI_6),
2306        (45.0, consts::FRAC_PI_4),
2307        (60.0, consts::FRAC_PI_3),
2308        (90.0, consts::FRAC_PI_2),
2309        (180.0, consts::PI),
2310    ];
2311
2312    #[test]
2313    fn convert_deg_rad() {
2314        use float::FloatCore;
2315
2316        for &(deg, rad) in &DEG_RAD_PAIRS {
2317            assert!((FloatCore::to_degrees(rad) - deg).abs() < 1e-6);
2318            assert!((FloatCore::to_radians(deg) - rad).abs() < 1e-6);
2319
2320            let (deg, rad) = (deg as f32, rad as f32);
2321            assert!((FloatCore::to_degrees(rad) - deg).abs() < 1e-5);
2322            assert!((FloatCore::to_radians(deg) - rad).abs() < 1e-5);
2323        }
2324    }
2325
2326    #[cfg(any(feature = "std", feature = "libm"))]
2327    #[test]
2328    fn convert_deg_rad_std() {
2329        for &(deg, rad) in &DEG_RAD_PAIRS {
2330            use Float;
2331
2332            assert!((Float::to_degrees(rad) - deg).abs() < 1e-6);
2333            assert!((Float::to_radians(deg) - rad).abs() < 1e-6);
2334
2335            let (deg, rad) = (deg as f32, rad as f32);
2336            assert!((Float::to_degrees(rad) - deg).abs() < 1e-5);
2337            assert!((Float::to_radians(deg) - rad).abs() < 1e-5);
2338        }
2339    }
2340
2341    #[test]
2342    // This fails with the forwarded `std` implementation in Rust 1.8.
2343    // To avoid the failure, the test is limited to `no_std` builds.
2344    #[cfg(not(feature = "std"))]
2345    fn to_degrees_rounding() {
2346        use float::FloatCore;
2347
2348        assert_eq!(
2349            FloatCore::to_degrees(1_f32),
2350            57.2957795130823208767981548141051703
2351        );
2352    }
2353}