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