1 #[cfg(feature = "std")]
2 use std::mem;
3 #[cfg(feature = "std")]
4 use std::ops::Neg;
5 #[cfg(feature = "std")]
6 use std::num::FpCategory;
7
8 // Used for default implementation of `epsilon`
9 #[cfg(feature = "std")]
10 use std::f32;
11
12 #[cfg(feature = "std")]
13 use {Num, NumCast};
14
15 // FIXME: these doctests aren't actually helpful, because they're using and
16 // testing the inherent methods directly, not going through `Float`.
17
18 /// Generic trait for floating point numbers
19 ///
20 /// This trait is only available with the `std` feature.
21 #[cfg(feature = "std")]
22 pub trait Float
23 : Num
24 + Copy
25 + NumCast
26 + PartialOrd
27 + Neg<Output = Self>
28 {
29 /// Returns the `NaN` value.
30 ///
31 /// ```
32 /// use num_traits::Float;
33 ///
34 /// let nan: f32 = Float::nan();
35 ///
36 /// assert!(nan.is_nan());
37 /// ```
nan() -> Self38 fn nan() -> Self;
39 /// Returns the infinite value.
40 ///
41 /// ```
42 /// use num_traits::Float;
43 /// use std::f32;
44 ///
45 /// let infinity: f32 = Float::infinity();
46 ///
47 /// assert!(infinity.is_infinite());
48 /// assert!(!infinity.is_finite());
49 /// assert!(infinity > f32::MAX);
50 /// ```
infinity() -> Self51 fn infinity() -> Self;
52 /// Returns the negative infinite value.
53 ///
54 /// ```
55 /// use num_traits::Float;
56 /// use std::f32;
57 ///
58 /// let neg_infinity: f32 = Float::neg_infinity();
59 ///
60 /// assert!(neg_infinity.is_infinite());
61 /// assert!(!neg_infinity.is_finite());
62 /// assert!(neg_infinity < f32::MIN);
63 /// ```
neg_infinity() -> Self64 fn neg_infinity() -> Self;
65 /// Returns `-0.0`.
66 ///
67 /// ```
68 /// use num_traits::{Zero, Float};
69 ///
70 /// let inf: f32 = Float::infinity();
71 /// let zero: f32 = Zero::zero();
72 /// let neg_zero: f32 = Float::neg_zero();
73 ///
74 /// assert_eq!(zero, neg_zero);
75 /// assert_eq!(7.0f32/inf, zero);
76 /// assert_eq!(zero * 10.0, zero);
77 /// ```
neg_zero() -> Self78 fn neg_zero() -> Self;
79
80 /// Returns the smallest finite value that this type can represent.
81 ///
82 /// ```
83 /// use num_traits::Float;
84 /// use std::f64;
85 ///
86 /// let x: f64 = Float::min_value();
87 ///
88 /// assert_eq!(x, f64::MIN);
89 /// ```
min_value() -> Self90 fn min_value() -> Self;
91
92 /// Returns the smallest positive, normalized value that this type can represent.
93 ///
94 /// ```
95 /// use num_traits::Float;
96 /// use std::f64;
97 ///
98 /// let x: f64 = Float::min_positive_value();
99 ///
100 /// assert_eq!(x, f64::MIN_POSITIVE);
101 /// ```
min_positive_value() -> Self102 fn min_positive_value() -> Self;
103
104 /// Returns epsilon, a small positive value.
105 ///
106 /// ```
107 /// use num_traits::Float;
108 /// use std::f64;
109 ///
110 /// let x: f64 = Float::epsilon();
111 ///
112 /// assert_eq!(x, f64::EPSILON);
113 /// ```
114 ///
115 /// # Panics
116 ///
117 /// The default implementation will panic if `f32::EPSILON` cannot
118 /// be cast to `Self`.
epsilon() -> Self119 fn epsilon() -> Self {
120 Self::from(f32::EPSILON).expect("Unable to cast from f32::EPSILON")
121 }
122
123 /// Returns the largest finite value that this type can represent.
124 ///
125 /// ```
126 /// use num_traits::Float;
127 /// use std::f64;
128 ///
129 /// let x: f64 = Float::max_value();
130 /// assert_eq!(x, f64::MAX);
131 /// ```
max_value() -> Self132 fn max_value() -> Self;
133
134 /// Returns `true` if this value is `NaN` and false otherwise.
135 ///
136 /// ```
137 /// use num_traits::Float;
138 /// use std::f64;
139 ///
140 /// let nan = f64::NAN;
141 /// let f = 7.0;
142 ///
143 /// assert!(nan.is_nan());
144 /// assert!(!f.is_nan());
145 /// ```
is_nan(self) -> bool146 fn is_nan(self) -> bool;
147
148 /// Returns `true` if this value is positive infinity or negative infinity and
149 /// false otherwise.
150 ///
151 /// ```
152 /// use num_traits::Float;
153 /// use std::f32;
154 ///
155 /// let f = 7.0f32;
156 /// let inf: f32 = Float::infinity();
157 /// let neg_inf: f32 = Float::neg_infinity();
158 /// let nan: f32 = f32::NAN;
159 ///
160 /// assert!(!f.is_infinite());
161 /// assert!(!nan.is_infinite());
162 ///
163 /// assert!(inf.is_infinite());
164 /// assert!(neg_inf.is_infinite());
165 /// ```
is_infinite(self) -> bool166 fn is_infinite(self) -> bool;
167
168 /// Returns `true` if this number is neither infinite nor `NaN`.
169 ///
170 /// ```
171 /// use num_traits::Float;
172 /// use std::f32;
173 ///
174 /// let f = 7.0f32;
175 /// let inf: f32 = Float::infinity();
176 /// let neg_inf: f32 = Float::neg_infinity();
177 /// let nan: f32 = f32::NAN;
178 ///
179 /// assert!(f.is_finite());
180 ///
181 /// assert!(!nan.is_finite());
182 /// assert!(!inf.is_finite());
183 /// assert!(!neg_inf.is_finite());
184 /// ```
is_finite(self) -> bool185 fn is_finite(self) -> bool;
186
187 /// Returns `true` if the number is neither zero, infinite,
188 /// [subnormal][subnormal], or `NaN`.
189 ///
190 /// ```
191 /// use num_traits::Float;
192 /// use std::f32;
193 ///
194 /// let min = f32::MIN_POSITIVE; // 1.17549435e-38f32
195 /// let max = f32::MAX;
196 /// let lower_than_min = 1.0e-40_f32;
197 /// let zero = 0.0f32;
198 ///
199 /// assert!(min.is_normal());
200 /// assert!(max.is_normal());
201 ///
202 /// assert!(!zero.is_normal());
203 /// assert!(!f32::NAN.is_normal());
204 /// assert!(!f32::INFINITY.is_normal());
205 /// // Values between `0` and `min` are Subnormal.
206 /// assert!(!lower_than_min.is_normal());
207 /// ```
208 /// [subnormal]: http://en.wikipedia.org/wiki/Denormal_number
is_normal(self) -> bool209 fn is_normal(self) -> bool;
210
211 /// Returns the floating point category of the number. If only one property
212 /// is going to be tested, it is generally faster to use the specific
213 /// predicate instead.
214 ///
215 /// ```
216 /// use num_traits::Float;
217 /// use std::num::FpCategory;
218 /// use std::f32;
219 ///
220 /// let num = 12.4f32;
221 /// let inf = f32::INFINITY;
222 ///
223 /// assert_eq!(num.classify(), FpCategory::Normal);
224 /// assert_eq!(inf.classify(), FpCategory::Infinite);
225 /// ```
classify(self) -> FpCategory226 fn classify(self) -> FpCategory;
227
228 /// Returns the largest integer less than or equal to a number.
229 ///
230 /// ```
231 /// use num_traits::Float;
232 ///
233 /// let f = 3.99;
234 /// let g = 3.0;
235 ///
236 /// assert_eq!(f.floor(), 3.0);
237 /// assert_eq!(g.floor(), 3.0);
238 /// ```
floor(self) -> Self239 fn floor(self) -> Self;
240
241 /// Returns the smallest integer greater than or equal to a number.
242 ///
243 /// ```
244 /// use num_traits::Float;
245 ///
246 /// let f = 3.01;
247 /// let g = 4.0;
248 ///
249 /// assert_eq!(f.ceil(), 4.0);
250 /// assert_eq!(g.ceil(), 4.0);
251 /// ```
ceil(self) -> Self252 fn ceil(self) -> Self;
253
254 /// Returns the nearest integer to a number. Round half-way cases away from
255 /// `0.0`.
256 ///
257 /// ```
258 /// use num_traits::Float;
259 ///
260 /// let f = 3.3;
261 /// let g = -3.3;
262 ///
263 /// assert_eq!(f.round(), 3.0);
264 /// assert_eq!(g.round(), -3.0);
265 /// ```
round(self) -> Self266 fn round(self) -> Self;
267
268 /// Return the integer part of a number.
269 ///
270 /// ```
271 /// use num_traits::Float;
272 ///
273 /// let f = 3.3;
274 /// let g = -3.7;
275 ///
276 /// assert_eq!(f.trunc(), 3.0);
277 /// assert_eq!(g.trunc(), -3.0);
278 /// ```
trunc(self) -> Self279 fn trunc(self) -> Self;
280
281 /// Returns the fractional part of a number.
282 ///
283 /// ```
284 /// use num_traits::Float;
285 ///
286 /// let x = 3.5;
287 /// let y = -3.5;
288 /// let abs_difference_x = (x.fract() - 0.5).abs();
289 /// let abs_difference_y = (y.fract() - (-0.5)).abs();
290 ///
291 /// assert!(abs_difference_x < 1e-10);
292 /// assert!(abs_difference_y < 1e-10);
293 /// ```
fract(self) -> Self294 fn fract(self) -> Self;
295
296 /// Computes the absolute value of `self`. Returns `Float::nan()` if the
297 /// number is `Float::nan()`.
298 ///
299 /// ```
300 /// use num_traits::Float;
301 /// use std::f64;
302 ///
303 /// let x = 3.5;
304 /// let y = -3.5;
305 ///
306 /// let abs_difference_x = (x.abs() - x).abs();
307 /// let abs_difference_y = (y.abs() - (-y)).abs();
308 ///
309 /// assert!(abs_difference_x < 1e-10);
310 /// assert!(abs_difference_y < 1e-10);
311 ///
312 /// assert!(f64::NAN.abs().is_nan());
313 /// ```
abs(self) -> Self314 fn abs(self) -> Self;
315
316 /// Returns a number that represents the sign of `self`.
317 ///
318 /// - `1.0` if the number is positive, `+0.0` or `Float::infinity()`
319 /// - `-1.0` if the number is negative, `-0.0` or `Float::neg_infinity()`
320 /// - `Float::nan()` if the number is `Float::nan()`
321 ///
322 /// ```
323 /// use num_traits::Float;
324 /// use std::f64;
325 ///
326 /// let f = 3.5;
327 ///
328 /// assert_eq!(f.signum(), 1.0);
329 /// assert_eq!(f64::NEG_INFINITY.signum(), -1.0);
330 ///
331 /// assert!(f64::NAN.signum().is_nan());
332 /// ```
signum(self) -> Self333 fn signum(self) -> Self;
334
335 /// Returns `true` if `self` is positive, including `+0.0`,
336 /// `Float::infinity()`, and with newer versions of Rust `f64::NAN`.
337 ///
338 /// ```
339 /// use num_traits::Float;
340 /// use std::f64;
341 ///
342 /// let neg_nan: f64 = -f64::NAN;
343 ///
344 /// let f = 7.0;
345 /// let g = -7.0;
346 ///
347 /// assert!(f.is_sign_positive());
348 /// assert!(!g.is_sign_positive());
349 /// assert!(!neg_nan.is_sign_positive());
350 /// ```
is_sign_positive(self) -> bool351 fn is_sign_positive(self) -> bool;
352
353 /// Returns `true` if `self` is negative, including `-0.0`,
354 /// `Float::neg_infinity()`, and with newer versions of Rust `-f64::NAN`.
355 ///
356 /// ```
357 /// use num_traits::Float;
358 /// use std::f64;
359 ///
360 /// let nan: f64 = f64::NAN;
361 ///
362 /// let f = 7.0;
363 /// let g = -7.0;
364 ///
365 /// assert!(!f.is_sign_negative());
366 /// assert!(g.is_sign_negative());
367 /// assert!(!nan.is_sign_negative());
368 /// ```
is_sign_negative(self) -> bool369 fn is_sign_negative(self) -> bool;
370
371 /// Fused multiply-add. Computes `(self * a) + b` with only one rounding
372 /// error. This produces a more accurate result with better performance than
373 /// a separate multiplication operation followed by an add.
374 ///
375 /// ```
376 /// use num_traits::Float;
377 ///
378 /// let m = 10.0;
379 /// let x = 4.0;
380 /// let b = 60.0;
381 ///
382 /// // 100.0
383 /// let abs_difference = (m.mul_add(x, b) - (m*x + b)).abs();
384 ///
385 /// assert!(abs_difference < 1e-10);
386 /// ```
mul_add(self, a: Self, b: Self) -> Self387 fn mul_add(self, a: Self, b: Self) -> Self;
388 /// Take the reciprocal (inverse) of a number, `1/x`.
389 ///
390 /// ```
391 /// use num_traits::Float;
392 ///
393 /// let x = 2.0;
394 /// let abs_difference = (x.recip() - (1.0/x)).abs();
395 ///
396 /// assert!(abs_difference < 1e-10);
397 /// ```
recip(self) -> Self398 fn recip(self) -> Self;
399
400 /// Raise a number to an integer power.
401 ///
402 /// Using this function is generally faster than using `powf`
403 ///
404 /// ```
405 /// use num_traits::Float;
406 ///
407 /// let x = 2.0;
408 /// let abs_difference = (x.powi(2) - x*x).abs();
409 ///
410 /// assert!(abs_difference < 1e-10);
411 /// ```
powi(self, n: i32) -> Self412 fn powi(self, n: i32) -> Self;
413
414 /// Raise a number to a floating point power.
415 ///
416 /// ```
417 /// use num_traits::Float;
418 ///
419 /// let x = 2.0;
420 /// let abs_difference = (x.powf(2.0) - x*x).abs();
421 ///
422 /// assert!(abs_difference < 1e-10);
423 /// ```
powf(self, n: Self) -> Self424 fn powf(self, n: Self) -> Self;
425
426 /// Take the square root of a number.
427 ///
428 /// Returns NaN if `self` is a negative number.
429 ///
430 /// ```
431 /// use num_traits::Float;
432 ///
433 /// let positive = 4.0;
434 /// let negative = -4.0;
435 ///
436 /// let abs_difference = (positive.sqrt() - 2.0).abs();
437 ///
438 /// assert!(abs_difference < 1e-10);
439 /// assert!(negative.sqrt().is_nan());
440 /// ```
sqrt(self) -> Self441 fn sqrt(self) -> Self;
442
443 /// Returns `e^(self)`, (the exponential function).
444 ///
445 /// ```
446 /// use num_traits::Float;
447 ///
448 /// let one = 1.0;
449 /// // e^1
450 /// let e = one.exp();
451 ///
452 /// // ln(e) - 1 == 0
453 /// let abs_difference = (e.ln() - 1.0).abs();
454 ///
455 /// assert!(abs_difference < 1e-10);
456 /// ```
exp(self) -> Self457 fn exp(self) -> Self;
458
459 /// Returns `2^(self)`.
460 ///
461 /// ```
462 /// use num_traits::Float;
463 ///
464 /// let f = 2.0;
465 ///
466 /// // 2^2 - 4 == 0
467 /// let abs_difference = (f.exp2() - 4.0).abs();
468 ///
469 /// assert!(abs_difference < 1e-10);
470 /// ```
exp2(self) -> Self471 fn exp2(self) -> Self;
472
473 /// Returns the natural logarithm of the number.
474 ///
475 /// ```
476 /// use num_traits::Float;
477 ///
478 /// let one = 1.0;
479 /// // e^1
480 /// let e = one.exp();
481 ///
482 /// // ln(e) - 1 == 0
483 /// let abs_difference = (e.ln() - 1.0).abs();
484 ///
485 /// assert!(abs_difference < 1e-10);
486 /// ```
ln(self) -> Self487 fn ln(self) -> Self;
488
489 /// Returns the logarithm of the number with respect to an arbitrary base.
490 ///
491 /// ```
492 /// use num_traits::Float;
493 ///
494 /// let ten = 10.0;
495 /// let two = 2.0;
496 ///
497 /// // log10(10) - 1 == 0
498 /// let abs_difference_10 = (ten.log(10.0) - 1.0).abs();
499 ///
500 /// // log2(2) - 1 == 0
501 /// let abs_difference_2 = (two.log(2.0) - 1.0).abs();
502 ///
503 /// assert!(abs_difference_10 < 1e-10);
504 /// assert!(abs_difference_2 < 1e-10);
505 /// ```
log(self, base: Self) -> Self506 fn log(self, base: Self) -> Self;
507
508 /// Returns the base 2 logarithm of the number.
509 ///
510 /// ```
511 /// use num_traits::Float;
512 ///
513 /// let two = 2.0;
514 ///
515 /// // log2(2) - 1 == 0
516 /// let abs_difference = (two.log2() - 1.0).abs();
517 ///
518 /// assert!(abs_difference < 1e-10);
519 /// ```
log2(self) -> Self520 fn log2(self) -> Self;
521
522 /// Returns the base 10 logarithm of the number.
523 ///
524 /// ```
525 /// use num_traits::Float;
526 ///
527 /// let ten = 10.0;
528 ///
529 /// // log10(10) - 1 == 0
530 /// let abs_difference = (ten.log10() - 1.0).abs();
531 ///
532 /// assert!(abs_difference < 1e-10);
533 /// ```
log10(self) -> Self534 fn log10(self) -> Self;
535
536 /// Converts radians to degrees.
537 ///
538 /// ```
539 /// use std::f64::consts;
540 ///
541 /// let angle = consts::PI;
542 ///
543 /// let abs_difference = (angle.to_degrees() - 180.0).abs();
544 ///
545 /// assert!(abs_difference < 1e-10);
546 /// ```
547 #[inline]
to_degrees(self) -> Self548 fn to_degrees(self) -> Self {
549 let halfpi = Self::zero().acos();
550 let ninety = Self::from(90u8).unwrap();
551 self * ninety / halfpi
552 }
553
554 /// Converts degrees to radians.
555 ///
556 /// ```
557 /// use std::f64::consts;
558 ///
559 /// let angle = 180.0_f64;
560 ///
561 /// let abs_difference = (angle.to_radians() - consts::PI).abs();
562 ///
563 /// assert!(abs_difference < 1e-10);
564 /// ```
565 #[inline]
to_radians(self) -> Self566 fn to_radians(self) -> Self {
567 let halfpi = Self::zero().acos();
568 let ninety = Self::from(90u8).unwrap();
569 self * halfpi / ninety
570 }
571
572 /// Returns the maximum of the two numbers.
573 ///
574 /// ```
575 /// use num_traits::Float;
576 ///
577 /// let x = 1.0;
578 /// let y = 2.0;
579 ///
580 /// assert_eq!(x.max(y), y);
581 /// ```
max(self, other: Self) -> Self582 fn max(self, other: Self) -> Self;
583
584 /// Returns the minimum of the two numbers.
585 ///
586 /// ```
587 /// use num_traits::Float;
588 ///
589 /// let x = 1.0;
590 /// let y = 2.0;
591 ///
592 /// assert_eq!(x.min(y), x);
593 /// ```
min(self, other: Self) -> Self594 fn min(self, other: Self) -> Self;
595
596 /// The positive difference of two numbers.
597 ///
598 /// * If `self <= other`: `0:0`
599 /// * Else: `self - other`
600 ///
601 /// ```
602 /// use num_traits::Float;
603 ///
604 /// let x = 3.0;
605 /// let y = -3.0;
606 ///
607 /// let abs_difference_x = (x.abs_sub(1.0) - 2.0).abs();
608 /// let abs_difference_y = (y.abs_sub(1.0) - 0.0).abs();
609 ///
610 /// assert!(abs_difference_x < 1e-10);
611 /// assert!(abs_difference_y < 1e-10);
612 /// ```
abs_sub(self, other: Self) -> Self613 fn abs_sub(self, other: Self) -> Self;
614
615 /// Take the cubic root of a number.
616 ///
617 /// ```
618 /// use num_traits::Float;
619 ///
620 /// let x = 8.0;
621 ///
622 /// // x^(1/3) - 2 == 0
623 /// let abs_difference = (x.cbrt() - 2.0).abs();
624 ///
625 /// assert!(abs_difference < 1e-10);
626 /// ```
cbrt(self) -> Self627 fn cbrt(self) -> Self;
628
629 /// Calculate the length of the hypotenuse of a right-angle triangle given
630 /// legs of length `x` and `y`.
631 ///
632 /// ```
633 /// use num_traits::Float;
634 ///
635 /// let x = 2.0;
636 /// let y = 3.0;
637 ///
638 /// // sqrt(x^2 + y^2)
639 /// let abs_difference = (x.hypot(y) - (x.powi(2) + y.powi(2)).sqrt()).abs();
640 ///
641 /// assert!(abs_difference < 1e-10);
642 /// ```
hypot(self, other: Self) -> Self643 fn hypot(self, other: Self) -> Self;
644
645 /// Computes the sine of a number (in radians).
646 ///
647 /// ```
648 /// use num_traits::Float;
649 /// use std::f64;
650 ///
651 /// let x = f64::consts::PI/2.0;
652 ///
653 /// let abs_difference = (x.sin() - 1.0).abs();
654 ///
655 /// assert!(abs_difference < 1e-10);
656 /// ```
sin(self) -> Self657 fn sin(self) -> Self;
658
659 /// Computes the cosine of a number (in radians).
660 ///
661 /// ```
662 /// use num_traits::Float;
663 /// use std::f64;
664 ///
665 /// let x = 2.0*f64::consts::PI;
666 ///
667 /// let abs_difference = (x.cos() - 1.0).abs();
668 ///
669 /// assert!(abs_difference < 1e-10);
670 /// ```
cos(self) -> Self671 fn cos(self) -> Self;
672
673 /// Computes the tangent of a number (in radians).
674 ///
675 /// ```
676 /// use num_traits::Float;
677 /// use std::f64;
678 ///
679 /// let x = f64::consts::PI/4.0;
680 /// let abs_difference = (x.tan() - 1.0).abs();
681 ///
682 /// assert!(abs_difference < 1e-14);
683 /// ```
tan(self) -> Self684 fn tan(self) -> Self;
685
686 /// Computes the arcsine of a number. Return value is in radians in
687 /// the range [-pi/2, pi/2] or NaN if the number is outside the range
688 /// [-1, 1].
689 ///
690 /// ```
691 /// use num_traits::Float;
692 /// use std::f64;
693 ///
694 /// let f = f64::consts::PI / 2.0;
695 ///
696 /// // asin(sin(pi/2))
697 /// let abs_difference = (f.sin().asin() - f64::consts::PI / 2.0).abs();
698 ///
699 /// assert!(abs_difference < 1e-10);
700 /// ```
asin(self) -> Self701 fn asin(self) -> Self;
702
703 /// Computes the arccosine of a number. Return value is in radians in
704 /// the range [0, pi] or NaN if the number is outside the range
705 /// [-1, 1].
706 ///
707 /// ```
708 /// use num_traits::Float;
709 /// use std::f64;
710 ///
711 /// let f = f64::consts::PI / 4.0;
712 ///
713 /// // acos(cos(pi/4))
714 /// let abs_difference = (f.cos().acos() - f64::consts::PI / 4.0).abs();
715 ///
716 /// assert!(abs_difference < 1e-10);
717 /// ```
acos(self) -> Self718 fn acos(self) -> Self;
719
720 /// Computes the arctangent of a number. Return value is in radians in the
721 /// range [-pi/2, pi/2];
722 ///
723 /// ```
724 /// use num_traits::Float;
725 ///
726 /// let f = 1.0;
727 ///
728 /// // atan(tan(1))
729 /// let abs_difference = (f.tan().atan() - 1.0).abs();
730 ///
731 /// assert!(abs_difference < 1e-10);
732 /// ```
atan(self) -> Self733 fn atan(self) -> Self;
734
735 /// Computes the four quadrant arctangent of `self` (`y`) and `other` (`x`).
736 ///
737 /// * `x = 0`, `y = 0`: `0`
738 /// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]`
739 /// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]`
740 /// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)`
741 ///
742 /// ```
743 /// use num_traits::Float;
744 /// use std::f64;
745 ///
746 /// let pi = f64::consts::PI;
747 /// // All angles from horizontal right (+x)
748 /// // 45 deg counter-clockwise
749 /// let x1 = 3.0;
750 /// let y1 = -3.0;
751 ///
752 /// // 135 deg clockwise
753 /// let x2 = -3.0;
754 /// let y2 = 3.0;
755 ///
756 /// let abs_difference_1 = (y1.atan2(x1) - (-pi/4.0)).abs();
757 /// let abs_difference_2 = (y2.atan2(x2) - 3.0*pi/4.0).abs();
758 ///
759 /// assert!(abs_difference_1 < 1e-10);
760 /// assert!(abs_difference_2 < 1e-10);
761 /// ```
atan2(self, other: Self) -> Self762 fn atan2(self, other: Self) -> Self;
763
764 /// Simultaneously computes the sine and cosine of the number, `x`. Returns
765 /// `(sin(x), cos(x))`.
766 ///
767 /// ```
768 /// use num_traits::Float;
769 /// use std::f64;
770 ///
771 /// let x = f64::consts::PI/4.0;
772 /// let f = x.sin_cos();
773 ///
774 /// let abs_difference_0 = (f.0 - x.sin()).abs();
775 /// let abs_difference_1 = (f.1 - x.cos()).abs();
776 ///
777 /// assert!(abs_difference_0 < 1e-10);
778 /// assert!(abs_difference_0 < 1e-10);
779 /// ```
sin_cos(self) -> (Self, Self)780 fn sin_cos(self) -> (Self, Self);
781
782 /// Returns `e^(self) - 1` in a way that is accurate even if the
783 /// number is close to zero.
784 ///
785 /// ```
786 /// use num_traits::Float;
787 ///
788 /// let x = 7.0;
789 ///
790 /// // e^(ln(7)) - 1
791 /// let abs_difference = (x.ln().exp_m1() - 6.0).abs();
792 ///
793 /// assert!(abs_difference < 1e-10);
794 /// ```
exp_m1(self) -> Self795 fn exp_m1(self) -> Self;
796
797 /// Returns `ln(1+n)` (natural logarithm) more accurately than if
798 /// the operations were performed separately.
799 ///
800 /// ```
801 /// use num_traits::Float;
802 /// use std::f64;
803 ///
804 /// let x = f64::consts::E - 1.0;
805 ///
806 /// // ln(1 + (e - 1)) == ln(e) == 1
807 /// let abs_difference = (x.ln_1p() - 1.0).abs();
808 ///
809 /// assert!(abs_difference < 1e-10);
810 /// ```
ln_1p(self) -> Self811 fn ln_1p(self) -> Self;
812
813 /// Hyperbolic sine function.
814 ///
815 /// ```
816 /// use num_traits::Float;
817 /// use std::f64;
818 ///
819 /// let e = f64::consts::E;
820 /// let x = 1.0;
821 ///
822 /// let f = x.sinh();
823 /// // Solving sinh() at 1 gives `(e^2-1)/(2e)`
824 /// let g = (e*e - 1.0)/(2.0*e);
825 /// let abs_difference = (f - g).abs();
826 ///
827 /// assert!(abs_difference < 1e-10);
828 /// ```
sinh(self) -> Self829 fn sinh(self) -> Self;
830
831 /// Hyperbolic cosine function.
832 ///
833 /// ```
834 /// use num_traits::Float;
835 /// use std::f64;
836 ///
837 /// let e = f64::consts::E;
838 /// let x = 1.0;
839 /// let f = x.cosh();
840 /// // Solving cosh() at 1 gives this result
841 /// let g = (e*e + 1.0)/(2.0*e);
842 /// let abs_difference = (f - g).abs();
843 ///
844 /// // Same result
845 /// assert!(abs_difference < 1.0e-10);
846 /// ```
cosh(self) -> Self847 fn cosh(self) -> Self;
848
849 /// Hyperbolic tangent function.
850 ///
851 /// ```
852 /// use num_traits::Float;
853 /// use std::f64;
854 ///
855 /// let e = f64::consts::E;
856 /// let x = 1.0;
857 ///
858 /// let f = x.tanh();
859 /// // Solving tanh() at 1 gives `(1 - e^(-2))/(1 + e^(-2))`
860 /// let g = (1.0 - e.powi(-2))/(1.0 + e.powi(-2));
861 /// let abs_difference = (f - g).abs();
862 ///
863 /// assert!(abs_difference < 1.0e-10);
864 /// ```
tanh(self) -> Self865 fn tanh(self) -> Self;
866
867 /// Inverse hyperbolic sine function.
868 ///
869 /// ```
870 /// use num_traits::Float;
871 ///
872 /// let x = 1.0;
873 /// let f = x.sinh().asinh();
874 ///
875 /// let abs_difference = (f - x).abs();
876 ///
877 /// assert!(abs_difference < 1.0e-10);
878 /// ```
asinh(self) -> Self879 fn asinh(self) -> Self;
880
881 /// Inverse hyperbolic cosine function.
882 ///
883 /// ```
884 /// use num_traits::Float;
885 ///
886 /// let x = 1.0;
887 /// let f = x.cosh().acosh();
888 ///
889 /// let abs_difference = (f - x).abs();
890 ///
891 /// assert!(abs_difference < 1.0e-10);
892 /// ```
acosh(self) -> Self893 fn acosh(self) -> Self;
894
895 /// Inverse hyperbolic tangent function.
896 ///
897 /// ```
898 /// use num_traits::Float;
899 /// use std::f64;
900 ///
901 /// let e = f64::consts::E;
902 /// let f = e.tanh().atanh();
903 ///
904 /// let abs_difference = (f - e).abs();
905 ///
906 /// assert!(abs_difference < 1.0e-10);
907 /// ```
atanh(self) -> Self908 fn atanh(self) -> Self;
909
910
911 /// Returns the mantissa, base 2 exponent, and sign as integers, respectively.
912 /// The original number can be recovered by `sign * mantissa * 2 ^ exponent`.
913 /// The floating point encoding is documented in the [Reference][floating-point].
914 ///
915 /// ```
916 /// use num_traits::Float;
917 ///
918 /// let num = 2.0f32;
919 ///
920 /// // (8388608, -22, 1)
921 /// let (mantissa, exponent, sign) = Float::integer_decode(num);
922 /// let sign_f = sign as f32;
923 /// let mantissa_f = mantissa as f32;
924 /// let exponent_f = num.powf(exponent as f32);
925 ///
926 /// // 1 * 8388608 * 2^(-22) == 2
927 /// let abs_difference = (sign_f * mantissa_f * exponent_f - num).abs();
928 ///
929 /// assert!(abs_difference < 1e-10);
930 /// ```
931 /// [floating-point]: ../../../../../reference.html#machine-types
integer_decode(self) -> (u64, i16, i8)932 fn integer_decode(self) -> (u64, i16, i8);
933 }
934
935 #[cfg(feature = "std")]
936 macro_rules! float_impl {
937 ($T:ident $decode:ident) => (
938 impl Float for $T {
939 #[inline]
940 fn nan() -> Self {
941 ::std::$T::NAN
942 }
943
944 #[inline]
945 fn infinity() -> Self {
946 ::std::$T::INFINITY
947 }
948
949 #[inline]
950 fn neg_infinity() -> Self {
951 ::std::$T::NEG_INFINITY
952 }
953
954 #[inline]
955 fn neg_zero() -> Self {
956 -0.0
957 }
958
959 #[inline]
960 fn min_value() -> Self {
961 ::std::$T::MIN
962 }
963
964 #[inline]
965 fn min_positive_value() -> Self {
966 ::std::$T::MIN_POSITIVE
967 }
968
969 #[inline]
970 fn epsilon() -> Self {
971 ::std::$T::EPSILON
972 }
973
974 #[inline]
975 fn max_value() -> Self {
976 ::std::$T::MAX
977 }
978
979 #[inline]
980 fn is_nan(self) -> bool {
981 <$T>::is_nan(self)
982 }
983
984 #[inline]
985 fn is_infinite(self) -> bool {
986 <$T>::is_infinite(self)
987 }
988
989 #[inline]
990 fn is_finite(self) -> bool {
991 <$T>::is_finite(self)
992 }
993
994 #[inline]
995 fn is_normal(self) -> bool {
996 <$T>::is_normal(self)
997 }
998
999 #[inline]
1000 fn classify(self) -> FpCategory {
1001 <$T>::classify(self)
1002 }
1003
1004 #[inline]
1005 fn floor(self) -> Self {
1006 <$T>::floor(self)
1007 }
1008
1009 #[inline]
1010 fn ceil(self) -> Self {
1011 <$T>::ceil(self)
1012 }
1013
1014 #[inline]
1015 fn round(self) -> Self {
1016 <$T>::round(self)
1017 }
1018
1019 #[inline]
1020 fn trunc(self) -> Self {
1021 <$T>::trunc(self)
1022 }
1023
1024 #[inline]
1025 fn fract(self) -> Self {
1026 <$T>::fract(self)
1027 }
1028
1029 #[inline]
1030 fn abs(self) -> Self {
1031 <$T>::abs(self)
1032 }
1033
1034 #[inline]
1035 fn signum(self) -> Self {
1036 <$T>::signum(self)
1037 }
1038
1039 #[inline]
1040 fn is_sign_positive(self) -> bool {
1041 <$T>::is_sign_positive(self)
1042 }
1043
1044 #[inline]
1045 fn is_sign_negative(self) -> bool {
1046 <$T>::is_sign_negative(self)
1047 }
1048
1049 #[inline]
1050 fn mul_add(self, a: Self, b: Self) -> Self {
1051 <$T>::mul_add(self, a, b)
1052 }
1053
1054 #[inline]
1055 fn recip(self) -> Self {
1056 <$T>::recip(self)
1057 }
1058
1059 #[inline]
1060 fn powi(self, n: i32) -> Self {
1061 <$T>::powi(self, n)
1062 }
1063
1064 #[inline]
1065 fn powf(self, n: Self) -> Self {
1066 <$T>::powf(self, n)
1067 }
1068
1069 #[inline]
1070 fn sqrt(self) -> Self {
1071 <$T>::sqrt(self)
1072 }
1073
1074 #[inline]
1075 fn exp(self) -> Self {
1076 <$T>::exp(self)
1077 }
1078
1079 #[inline]
1080 fn exp2(self) -> Self {
1081 <$T>::exp2(self)
1082 }
1083
1084 #[inline]
1085 fn ln(self) -> Self {
1086 <$T>::ln(self)
1087 }
1088
1089 #[inline]
1090 fn log(self, base: Self) -> Self {
1091 <$T>::log(self, base)
1092 }
1093
1094 #[inline]
1095 fn log2(self) -> Self {
1096 <$T>::log2(self)
1097 }
1098
1099 #[inline]
1100 fn log10(self) -> Self {
1101 <$T>::log10(self)
1102 }
1103
1104 #[inline]
1105 fn to_degrees(self) -> Self {
1106 // NB: `f32` didn't stabilize this until 1.7
1107 // <$T>::to_degrees(self)
1108 self * (180. / ::std::$T::consts::PI)
1109 }
1110
1111 #[inline]
1112 fn to_radians(self) -> Self {
1113 // NB: `f32` didn't stabilize this until 1.7
1114 // <$T>::to_radians(self)
1115 self * (::std::$T::consts::PI / 180.)
1116 }
1117
1118 #[inline]
1119 fn max(self, other: Self) -> Self {
1120 <$T>::max(self, other)
1121 }
1122
1123 #[inline]
1124 fn min(self, other: Self) -> Self {
1125 <$T>::min(self, other)
1126 }
1127
1128 #[inline]
1129 #[allow(deprecated)]
1130 fn abs_sub(self, other: Self) -> Self {
1131 <$T>::abs_sub(self, other)
1132 }
1133
1134 #[inline]
1135 fn cbrt(self) -> Self {
1136 <$T>::cbrt(self)
1137 }
1138
1139 #[inline]
1140 fn hypot(self, other: Self) -> Self {
1141 <$T>::hypot(self, other)
1142 }
1143
1144 #[inline]
1145 fn sin(self) -> Self {
1146 <$T>::sin(self)
1147 }
1148
1149 #[inline]
1150 fn cos(self) -> Self {
1151 <$T>::cos(self)
1152 }
1153
1154 #[inline]
1155 fn tan(self) -> Self {
1156 <$T>::tan(self)
1157 }
1158
1159 #[inline]
1160 fn asin(self) -> Self {
1161 <$T>::asin(self)
1162 }
1163
1164 #[inline]
1165 fn acos(self) -> Self {
1166 <$T>::acos(self)
1167 }
1168
1169 #[inline]
1170 fn atan(self) -> Self {
1171 <$T>::atan(self)
1172 }
1173
1174 #[inline]
1175 fn atan2(self, other: Self) -> Self {
1176 <$T>::atan2(self, other)
1177 }
1178
1179 #[inline]
1180 fn sin_cos(self) -> (Self, Self) {
1181 <$T>::sin_cos(self)
1182 }
1183
1184 #[inline]
1185 fn exp_m1(self) -> Self {
1186 <$T>::exp_m1(self)
1187 }
1188
1189 #[inline]
1190 fn ln_1p(self) -> Self {
1191 <$T>::ln_1p(self)
1192 }
1193
1194 #[inline]
1195 fn sinh(self) -> Self {
1196 <$T>::sinh(self)
1197 }
1198
1199 #[inline]
1200 fn cosh(self) -> Self {
1201 <$T>::cosh(self)
1202 }
1203
1204 #[inline]
1205 fn tanh(self) -> Self {
1206 <$T>::tanh(self)
1207 }
1208
1209 #[inline]
1210 fn asinh(self) -> Self {
1211 <$T>::asinh(self)
1212 }
1213
1214 #[inline]
1215 fn acosh(self) -> Self {
1216 <$T>::acosh(self)
1217 }
1218
1219 #[inline]
1220 fn atanh(self) -> Self {
1221 <$T>::atanh(self)
1222 }
1223
1224 #[inline]
1225 fn integer_decode(self) -> (u64, i16, i8) {
1226 $decode(self)
1227 }
1228 }
1229 )
1230 }
1231
1232 #[cfg(feature = "std")]
integer_decode_f32(f: f32) -> (u64, i16, i8)1233 fn integer_decode_f32(f: f32) -> (u64, i16, i8) {
1234 let bits: u32 = unsafe { mem::transmute(f) };
1235 let sign: i8 = if bits >> 31 == 0 {
1236 1
1237 } else {
1238 -1
1239 };
1240 let mut exponent: i16 = ((bits >> 23) & 0xff) as i16;
1241 let mantissa = if exponent == 0 {
1242 (bits & 0x7fffff) << 1
1243 } else {
1244 (bits & 0x7fffff) | 0x800000
1245 };
1246 // Exponent bias + mantissa shift
1247 exponent -= 127 + 23;
1248 (mantissa as u64, exponent, sign)
1249 }
1250
1251 #[cfg(feature = "std")]
integer_decode_f64(f: f64) -> (u64, i16, i8)1252 fn integer_decode_f64(f: f64) -> (u64, i16, i8) {
1253 let bits: u64 = unsafe { mem::transmute(f) };
1254 let sign: i8 = if bits >> 63 == 0 {
1255 1
1256 } else {
1257 -1
1258 };
1259 let mut exponent: i16 = ((bits >> 52) & 0x7ff) as i16;
1260 let mantissa = if exponent == 0 {
1261 (bits & 0xfffffffffffff) << 1
1262 } else {
1263 (bits & 0xfffffffffffff) | 0x10000000000000
1264 };
1265 // Exponent bias + mantissa shift
1266 exponent -= 1023 + 52;
1267 (mantissa, exponent, sign)
1268 }
1269
1270 #[cfg(feature = "std")]
1271 float_impl!(f32 integer_decode_f32);
1272 #[cfg(feature = "std")]
1273 float_impl!(f64 integer_decode_f64);
1274
1275 macro_rules! float_const_impl {
1276 ($(#[$doc:meta] $constant:ident,)+) => (
1277 #[allow(non_snake_case)]
1278 pub trait FloatConst {
1279 $(#[$doc] fn $constant() -> Self;)+
1280 }
1281 float_const_impl! { @float f32, $($constant,)+ }
1282 float_const_impl! { @float f64, $($constant,)+ }
1283 );
1284 (@float $T:ident, $($constant:ident,)+) => (
1285 impl FloatConst for $T {
1286 $(
1287 #[inline]
1288 fn $constant() -> Self {
1289 ::core::$T::consts::$constant
1290 }
1291 )+
1292 }
1293 );
1294 }
1295
1296 float_const_impl! {
1297 #[doc = "Return Euler’s number."]
1298 E,
1299 #[doc = "Return `1.0 / π`."]
1300 FRAC_1_PI,
1301 #[doc = "Return `1.0 / sqrt(2.0)`."]
1302 FRAC_1_SQRT_2,
1303 #[doc = "Return `2.0 / π`."]
1304 FRAC_2_PI,
1305 #[doc = "Return `2.0 / sqrt(π)`."]
1306 FRAC_2_SQRT_PI,
1307 #[doc = "Return `π / 2.0`."]
1308 FRAC_PI_2,
1309 #[doc = "Return `π / 3.0`."]
1310 FRAC_PI_3,
1311 #[doc = "Return `π / 4.0`."]
1312 FRAC_PI_4,
1313 #[doc = "Return `π / 6.0`."]
1314 FRAC_PI_6,
1315 #[doc = "Return `π / 8.0`."]
1316 FRAC_PI_8,
1317 #[doc = "Return `ln(10.0)`."]
1318 LN_10,
1319 #[doc = "Return `ln(2.0)`."]
1320 LN_2,
1321 #[doc = "Return `log10(e)`."]
1322 LOG10_E,
1323 #[doc = "Return `log2(e)`."]
1324 LOG2_E,
1325 #[doc = "Return Archimedes’ constant."]
1326 PI,
1327 #[doc = "Return `sqrt(2.0)`."]
1328 SQRT_2,
1329 }
1330
1331 #[cfg(all(test, feature = "std"))]
1332 mod tests {
1333 use Float;
1334
1335 #[test]
convert_deg_rad()1336 fn convert_deg_rad() {
1337 use core::f64::consts;
1338
1339 const DEG_RAD_PAIRS: [(f64, f64); 7] = [
1340 (0.0, 0.),
1341 (22.5, consts::FRAC_PI_8),
1342 (30.0, consts::FRAC_PI_6),
1343 (45.0, consts::FRAC_PI_4),
1344 (60.0, consts::FRAC_PI_3),
1345 (90.0, consts::FRAC_PI_2),
1346 (180.0, consts::PI),
1347 ];
1348
1349 for &(deg, rad) in &DEG_RAD_PAIRS {
1350 assert!((Float::to_degrees(rad) - deg).abs() < 1e-6);
1351 assert!((Float::to_radians(deg) - rad).abs() < 1e-6);
1352
1353 let (deg, rad) = (deg as f32, rad as f32);
1354 assert!((Float::to_degrees(rad) - deg).abs() < 1e-6);
1355 assert!((Float::to_radians(deg) - rad).abs() < 1e-6);
1356 }
1357 }
1358 }
1359