malachite_base/num/basic/floats.rs
1// Copyright © 2026 Mikhail Hogrefe
2//
3// This file is part of Malachite.
4//
5// Malachite is free software: you can redistribute it and/or modify it under the terms of the GNU
6// Lesser General Public License (LGPL) as published by the Free Software Foundation; either version
7// 3 of the License, or (at your option) any later version. See <https://www.gnu.org/licenses/>.
8
9use crate::comparison::traits::{Max, Min};
10use crate::named::Named;
11use crate::num::arithmetic::traits::{
12 Abs, AbsAssign, AddMul, AddMulAssign, Ceiling, CeilingAssign, CeilingLogBase2,
13 CeilingLogBasePowerOf2, CheckedLogBase2, CheckedLogBasePowerOf2, Floor, FloorAssign,
14 FloorLogBase2, FloorLogBasePowerOf2, IsPowerOf2, Ln, NegAssign, NextPowerOf2,
15 NextPowerOf2Assign, Pow, PowAssign, PowerOf2, Reciprocal, ReciprocalAssign, Sign, Sqrt,
16 SqrtAssign, Square, SquareAssign, SubMul, SubMulAssign,
17};
18use crate::num::basic::traits::{
19 GaussConstant, Infinity, LemniscateConstant, Ln2, Log2E, NaN, NegativeInfinity, NegativeOne,
20 NegativeZero, One, OneHalf, OneOverPi, OneOverSqrtPi, OneOverSqrtTau, Phi, Pi, PiOver2,
21 PiOver3, PiOver4, PiOver6, PiOver8, PrimeConstant, ProuhetThueMorseConstant, Sqrt2, Sqrt2Over2,
22 Sqrt3, Sqrt3Over3, SqrtPi, Tau, Two, TwoOverPi, TwoOverSqrtPi, Zero,
23};
24use crate::num::comparison::traits::{EqAbs, PartialOrdAbs};
25use crate::num::conversion::traits::{
26 ConvertibleFrom, ExactInto, IntegerMantissaAndExponent, IsInteger, RawMantissaAndExponent,
27 RoundingFrom, RoundingInto, SciMantissaAndExponent, WrappingFrom,
28};
29use crate::num::float::FmtRyuString;
30use crate::num::logic::traits::{BitAccess, LowMask, SignificantBits, TrailingZeros};
31use core::cmp::Ordering::*;
32use core::fmt::{Debug, Display, LowerExp, UpperExp};
33use core::iter::{Product, Sum};
34use core::num::FpCategory;
35use core::ops::{
36 Add, AddAssign, Div, DivAssign, Mul, MulAssign, Neg, Rem, RemAssign, Sub, SubAssign,
37};
38use core::panic::RefUnwindSafe;
39use core::str::FromStr;
40
41/// This trait defines functions on primitive float types: [`f32`] and [`f64`].
42///
43/// Many of the functions here concern exponents and mantissas. We define three ways to express a
44/// float, each with its own exponent and mantissa. In the following, let $x$ be an arbitrary
45/// positive, finite, non-zero, non-NaN float. Let $M$ and $E$ be the mantissa width and exponent
46/// width of the floating point type; for [`f32`]s, this is 23 and 8, and for [`f64`]s it's 52 and
47/// 11.
48///
49/// In the following we assume that $x$ is positive, but you can easily extend these definitions to
50/// negative floats by first taking their absolute value.
51///
52/// # raw form
53/// The raw exponent and raw mantissa are the actual bit patterns used to represent the components
54/// of $x$. The raw exponent $e_r$ is an integer in $[0, 2^E-2]$ and the raw mantissa $m_r$ is an
55/// integer in $[0, 2^M-1]$. Since we are dealing with a nonzero $x$, we forbid $e_r$ and $m_r$ from
56/// both being zero. We have
57/// $$
58/// x = \\begin{cases}
59/// 2^{2-2^{E-1}-M}m_r & \text{if} \quad e_r = 0, \\\\
60/// 2^{e_r-2^{E-1}+1}(2^{-M}m_r+1) & \textrm{otherwise},
61/// \\end{cases}
62/// $$
63/// $$
64/// e_r = \\begin{cases}
65/// 0 & \text{if} \quad x < 2^{2-2^{E-1}}, \\\\
66/// \lfloor \log_2 x \rfloor + 2^{E-1} - 1 & \textrm{otherwise},
67/// \\end{cases}
68/// $$
69/// $$
70/// m_r = \\begin{cases}
71/// 2^{M+2^{E-1}-2}x & \text{if} \quad x < 2^{2-2^{E-1}}, \\\\
72/// 2^M \left ( \frac{x}{2^{\lfloor \log_2 x \rfloor}}-1\right ) & \textrm{otherwise}.
73/// \\end{cases}
74/// $$
75///
76/// # scientific form
77/// We can write $x = 2^{e_s}m_s$, where $e_s$ is an integer and $m_s$ is a rational number with $1
78/// \leq m_s < 2$. If $x$ is a valid float, the scientific mantissa $m_s$ is always exactly
79/// representable as a float of the same type. We have
80/// $$
81/// x = 2^{e_s}m_s,
82/// $$
83/// $$
84/// e_s = \lfloor \log_2 x \rfloor,
85/// $$
86/// $$
87/// m_s = \frac{x}{2^{\lfloor \log_2 x \rfloor}}.
88/// $$
89///
90/// # integer form
91/// We can also write $x = 2^{e_i}m_i$, where $e_i$ is an integer and $m_i$ is an odd integer. We
92/// have
93/// $$
94/// x = 2^{e_i}m_i,
95/// $$
96/// $e_i$ is the unique integer such that $x/2^{e_i}$is an odd integer, and
97/// $$
98/// m_i = \frac{x}{2^{e_i}}.
99/// $$
100pub trait PrimitiveFloat:
101 'static
102 + Abs<Output = Self>
103 + AbsAssign
104 + Add<Output = Self>
105 + AddAssign<Self>
106 + AddMul<Output = Self>
107 + AddMulAssign<Self, Self>
108 + Ceiling<Output = Self>
109 + CeilingAssign
110 + CeilingLogBase2<Output = i64>
111 + CeilingLogBasePowerOf2<u64, Output = i64>
112 + CheckedLogBase2<Output = i64>
113 + CheckedLogBasePowerOf2<u64, Output = i64>
114 + ConvertibleFrom<u8>
115 + ConvertibleFrom<u16>
116 + ConvertibleFrom<u32>
117 + ConvertibleFrom<u64>
118 + ConvertibleFrom<u128>
119 + ConvertibleFrom<usize>
120 + ConvertibleFrom<i8>
121 + ConvertibleFrom<i16>
122 + ConvertibleFrom<i32>
123 + ConvertibleFrom<i64>
124 + ConvertibleFrom<i128>
125 + ConvertibleFrom<isize>
126 + Copy
127 + Debug
128 + Default
129 + Display
130 + Div<Output = Self>
131 + DivAssign
132 + EqAbs<Self>
133 + Floor<Output = Self>
134 + FloorAssign
135 + FloorLogBase2<Output = i64>
136 + FloorLogBasePowerOf2<u64, Output = i64>
137 + FmtRyuString
138 + From<f32>
139 + FromStr
140 + Infinity
141 + IntegerMantissaAndExponent<u64, i64>
142 + Into<f64>
143 + IsInteger
144 + IsPowerOf2
145 + Log2E
146 + Ln
147 + Ln2
148 + LowerExp
149 + Min
150 + Max
151 + Mul<Output = Self>
152 + MulAssign<Self>
153 + Named
154 + NaN
155 + NegativeInfinity
156 + NegativeZero
157 + Neg<Output = Self>
158 + NegAssign
159 + NegativeOne
160 + NextPowerOf2<Output = Self>
161 + NextPowerOf2Assign
162 + One
163 + PartialEq<Self>
164 + PartialOrd<Self>
165 + PartialOrdAbs<Self>
166 + Phi
167 + Pi
168 + Pow<i64, Output = Self>
169 + Pow<Self, Output = Self>
170 + PowAssign<i64>
171 + PowAssign<Self>
172 + PowerOf2<i64>
173 + PowerOf2<u64>
174 + PrimeConstant
175 + Product
176 + RawMantissaAndExponent<u64, u64>
177 + Reciprocal<Output = Self>
178 + ReciprocalAssign
179 + RefUnwindSafe
180 + Rem<Output = Self>
181 + RemAssign<Self>
182 + RoundingFrom<u8>
183 + RoundingFrom<u16>
184 + RoundingFrom<u32>
185 + RoundingFrom<u64>
186 + RoundingFrom<u128>
187 + RoundingFrom<usize>
188 + RoundingFrom<i8>
189 + RoundingFrom<i16>
190 + RoundingFrom<i32>
191 + RoundingFrom<i64>
192 + RoundingFrom<i128>
193 + RoundingFrom<isize>
194 + RoundingInto<u8>
195 + RoundingInto<u16>
196 + RoundingInto<u32>
197 + RoundingInto<u64>
198 + RoundingInto<u128>
199 + RoundingInto<usize>
200 + RoundingInto<i8>
201 + RoundingInto<i16>
202 + RoundingInto<i32>
203 + RoundingInto<i64>
204 + RoundingInto<i128>
205 + RoundingInto<isize>
206 + SciMantissaAndExponent<Self, i64>
207 + Sign
208 + Sized
209 + Sqrt<Output = Self>
210 + SqrtAssign
211 + Sqrt2
212 + Sqrt2Over2
213 + Sqrt3
214 + Sqrt3Over3
215 + Square<Output = Self>
216 + SquareAssign
217 + Sub<Output = Self>
218 + SubAssign<Self>
219 + SubMul<Output = Self>
220 + SubMulAssign<Self, Self>
221 + Sum<Self>
222 + ProuhetThueMorseConstant
223 + Two
224 + UpperExp
225 + Zero
226{
227 /// The number of bits taken up by the type.
228 ///
229 /// This is $M+E+1$. The three terms in the sum correspond to the width of the mantissa, the
230 /// width of the exponent, and the sign bit.
231 /// - For [`f32`]s, this is 32.
232 /// - For [`f64`]s, this is 64.
233 const WIDTH: u64;
234 /// The number of bits taken up by the exponent.
235 /// - For [`f32`]s, this is 8.
236 /// - For [`f64`]s, this is 11.
237 const EXPONENT_WIDTH: u64 = Self::WIDTH - Self::MANTISSA_WIDTH - 1;
238 /// The number of bits taken up by the mantissa.
239 /// - For [`f32`]s, this is 23.
240 /// - For [`f64`]s, this is 52.
241 const MANTISSA_WIDTH: u64;
242 /// The smallest possible exponent of a float in the normal range. Any floats with smaller
243 /// exponents are subnormal and thus have reduced precision. This is $2-2^{E-1}$.
244 /// - For [`f32`]s, this is -126.
245 /// - For [`f64`]s, this is -1022.
246 const MIN_NORMAL_EXPONENT: i64 = -(1 << (Self::EXPONENT_WIDTH - 1)) + 2;
247 /// The smallest possible exponent of a float. This is $2-2^{E-1}-M$.
248 /// - For [`f32`]s, this is -149.
249 /// - For [`f64`]s, this is -1074.
250 const MIN_EXPONENT: i64 = Self::MIN_NORMAL_EXPONENT - (Self::MANTISSA_WIDTH as i64);
251 /// The largest possible exponent of a float. This is $2^{E-1}-1$.
252 /// - For [`f32`]s, this is 127.
253 /// - For [`f64`]s, this is 1023.
254 const MAX_EXPONENT: i64 = (1 << (Self::EXPONENT_WIDTH - 1)) - 1;
255 /// The smallest positive float. This is $2^{2-2^{E-1}-M}$.
256 /// - For [`f32`]s, this is $2^{-149}$, or `1.0e-45`.
257 /// - For [`f64`]s, this is $2^{-1074}$, or `5.0e-324`.
258 const MIN_POSITIVE_SUBNORMAL: Self;
259 /// The largest float in the subnormal range. This is $2^{2-2^{E-1}-M}(2^M-1)$.
260 /// - For [`f32`]s, this is $2^{-149}(2^{23}-1)$, or `1.1754942e-38`.
261 /// - For [`f64`]s, this is $2^{-1074}(2^{52}-1)$, or `2.225073858507201e-308`.
262 const MAX_SUBNORMAL: Self;
263 /// The smallest positive normal float. This is $2^{2-2^{E-1}}$.
264 /// - For [`f32`]s, this is $2^{-126}$, or `1.1754944e-38`.
265 /// - For [`f64`]s, this is $2^{-1022}$, or `2.2250738585072014e-308`.
266 const MIN_POSITIVE_NORMAL: Self;
267 /// The largest finite float. This is $2^{2^{E-1}-1}(2-2^{-M})$.
268 /// - For [`f32`]s, this is $2^{127}(2-2^{-23})$, or `3.4028235e38`.
269 /// - For [`f64`]s, this is $2^{1023}(2-2^{-52})$, or `1.7976931348623157e308`.
270 const MAX_FINITE: Self;
271 /// The smallest positive integer that cannot be represented as a float. This is $2^{M+1}+1$.
272 /// - For [`f32`]s, this is $2^{24}+1$, or 16777217.
273 /// - For [`f64`]s, this is $2^{53}+1$, or 9007199254740993.
274 const SMALLEST_UNREPRESENTABLE_UINT: u64;
275 /// If you list all floats in increasing order, excluding NaN and giving negative and positive
276 /// zero separate adjacent spots, this will be index of the last element, positive infinity. It
277 /// is $2^{M+1}(2^E-1)+1$.
278 /// - For [`f32`]s, this is $2^{32}-2^{24}+1$, or 4278190081.
279 /// - For [`f64`]s, this is $2^{64}-2^{53}+1$, or 18437736874454810625.
280 const LARGEST_ORDERED_REPRESENTATION: u64;
281
282 fn is_nan(self) -> bool;
283
284 fn is_infinite(self) -> bool;
285
286 fn is_finite(self) -> bool;
287
288 fn is_normal(self) -> bool;
289
290 fn is_sign_positive(self) -> bool;
291
292 fn is_sign_negative(self) -> bool;
293
294 fn classify(self) -> FpCategory;
295
296 fn to_bits(self) -> u64;
297
298 fn from_bits(v: u64) -> Self;
299
300 /// Tests whether `self` is negative zero.
301 ///
302 /// # Worst-case complexity
303 /// Constant time and additional memory.
304 ///
305 /// # Examples
306 /// ```
307 /// use malachite_base::num::basic::floats::PrimitiveFloat;
308 ///
309 /// assert!((-0.0).is_negative_zero());
310 /// assert!(!0.0.is_negative_zero());
311 /// assert!(!1.0.is_negative_zero());
312 /// assert!(!f32::NAN.is_negative_zero());
313 /// assert!(!f32::INFINITY.is_negative_zero());
314 /// ```
315 #[inline]
316 fn is_negative_zero(self) -> bool {
317 self.sign() == Less && self == Self::ZERO
318 }
319
320 /// If `self` is negative zero, returns positive zero; otherwise, returns `self`.
321 ///
322 /// # Worst-case complexity
323 /// Constant time and additional memory.
324 ///
325 /// # Examples
326 /// ```
327 /// use malachite_base::num::basic::floats::PrimitiveFloat;
328 /// use malachite_base::num::float::NiceFloat;
329 ///
330 /// assert_eq!(NiceFloat((-0.0).abs_negative_zero()), NiceFloat(0.0));
331 /// assert_eq!(NiceFloat(0.0.abs_negative_zero()), NiceFloat(0.0));
332 /// assert_eq!(NiceFloat(1.0.abs_negative_zero()), NiceFloat(1.0));
333 /// assert_eq!(NiceFloat((-1.0).abs_negative_zero()), NiceFloat(-1.0));
334 /// assert_eq!(NiceFloat(f32::NAN.abs_negative_zero()), NiceFloat(f32::NAN));
335 /// ```
336 #[inline]
337 fn abs_negative_zero(self) -> Self {
338 if self == Self::ZERO { Self::ZERO } else { self }
339 }
340
341 /// If `self` is negative zero, replaces it with positive zero; otherwise, leaves `self`
342 /// unchanged.
343 ///
344 /// # Worst-case complexity
345 /// Constant time and additional memory.
346 ///
347 /// # Examples
348 /// ```
349 /// use malachite_base::num::basic::floats::PrimitiveFloat;
350 /// use malachite_base::num::float::NiceFloat;
351 ///
352 /// let mut f = -0.0;
353 /// f.abs_negative_zero_assign();
354 /// assert_eq!(NiceFloat(f), NiceFloat(0.0));
355 ///
356 /// let mut f = 0.0;
357 /// f.abs_negative_zero_assign();
358 /// assert_eq!(NiceFloat(f), NiceFloat(0.0));
359 ///
360 /// let mut f = 1.0;
361 /// f.abs_negative_zero_assign();
362 /// assert_eq!(NiceFloat(f), NiceFloat(1.0));
363 ///
364 /// let mut f = -1.0;
365 /// f.abs_negative_zero_assign();
366 /// assert_eq!(NiceFloat(f), NiceFloat(-1.0));
367 ///
368 /// let mut f = f32::NAN;
369 /// f.abs_negative_zero_assign();
370 /// assert_eq!(NiceFloat(f), NiceFloat(f32::NAN));
371 /// ```
372 #[inline]
373 fn abs_negative_zero_assign(&mut self) {
374 if *self == Self::ZERO {
375 *self = Self::ZERO;
376 }
377 }
378
379 /// Returns the smallest float larger than `self`.
380 ///
381 /// Passing `-0.0` returns `0.0`; passing `NaN` or positive infinity panics.
382 ///
383 /// # Worst-case complexity
384 /// Constant time and additional memory.
385 ///
386 /// # Panics
387 /// Panics if `self` is `NaN` or positive infinity.
388 ///
389 /// # Examples
390 /// ```
391 /// use malachite_base::num::basic::floats::PrimitiveFloat;
392 /// use malachite_base::num::float::NiceFloat;
393 ///
394 /// assert_eq!(NiceFloat((-0.0f32).next_higher()), NiceFloat(0.0));
395 /// assert_eq!(NiceFloat(0.0f32.next_higher()), NiceFloat(1.0e-45));
396 /// assert_eq!(NiceFloat(1.0f32.next_higher()), NiceFloat(1.0000001));
397 /// assert_eq!(NiceFloat((-1.0f32).next_higher()), NiceFloat(-0.99999994));
398 /// ```
399 fn next_higher(self) -> Self {
400 assert!(!self.is_nan());
401 if self.sign() == Greater {
402 assert_ne!(self, Self::INFINITY);
403 Self::from_bits(self.to_bits() + 1)
404 } else if self == Self::ZERO {
405 // negative zero -> positive zero
406 Self::ZERO
407 } else {
408 Self::from_bits(self.to_bits() - 1)
409 }
410 }
411
412 /// Returns the largest float smaller than `self`.
413 ///
414 /// Passing `0.0` returns `-0.0`; passing `NaN` or negative infinity panics.
415 ///
416 /// # Worst-case complexity
417 /// Constant time and additional memory.
418 ///
419 /// # Panics
420 /// Panics if `self` is `NaN` or negative infinity.
421 ///
422 /// # Examples
423 /// ```
424 /// use malachite_base::num::basic::floats::PrimitiveFloat;
425 /// use malachite_base::num::float::NiceFloat;
426 ///
427 /// assert_eq!(NiceFloat(0.0f32.next_lower()), NiceFloat(-0.0));
428 /// assert_eq!(NiceFloat((-0.0f32).next_lower()), NiceFloat(-1.0e-45));
429 /// assert_eq!(NiceFloat(1.0f32.next_lower()), NiceFloat(0.99999994));
430 /// assert_eq!(NiceFloat((-1.0f32).next_lower()), NiceFloat(-1.0000001));
431 /// ```
432 fn next_lower(self) -> Self {
433 assert!(!self.is_nan());
434 if self.sign() == Less {
435 assert_ne!(self, Self::NEGATIVE_INFINITY);
436 Self::from_bits(self.to_bits() + 1)
437 } else if self == Self::ZERO {
438 // positive zero -> negative zero
439 Self::NEGATIVE_ZERO
440 } else {
441 Self::from_bits(self.to_bits() - 1)
442 }
443 }
444
445 /// Maps `self` to an integer. The map preserves ordering, and adjacent floats are mapped to
446 /// adjacent integers.
447 ///
448 /// Negative infinity is mapped to 0, and positive infinity is mapped to the largest value,
449 /// [`LARGEST_ORDERED_REPRESENTATION`](PrimitiveFloat::LARGEST_ORDERED_REPRESENTATION). Negative
450 /// and positive zero are mapped to distinct adjacent values. Passing in `NaN` panics.
451 ///
452 /// The inverse operation is
453 /// [`from_ordered_representation`](PrimitiveFloat::from_ordered_representation).
454 ///
455 /// # Worst-case complexity
456 /// Constant time and additional memory.
457 ///
458 /// # Panics
459 /// Panics if `self` is `NaN`.
460 ///
461 /// # Examples
462 /// ```
463 /// use malachite_base::num::basic::floats::PrimitiveFloat;
464 /// use malachite_base::num::basic::traits::NegativeInfinity;
465 ///
466 /// assert_eq!(f32::NEGATIVE_INFINITY.to_ordered_representation(), 0);
467 /// assert_eq!((-0.0f32).to_ordered_representation(), 2139095040);
468 /// assert_eq!(0.0f32.to_ordered_representation(), 2139095041);
469 /// assert_eq!(1.0f32.to_ordered_representation(), 3204448257);
470 /// assert_eq!(f32::INFINITY.to_ordered_representation(), 4278190081);
471 /// ```
472 fn to_ordered_representation(self) -> u64 {
473 assert!(!self.is_nan());
474 let bits = self.to_bits();
475 if self.sign() == Greater {
476 (u64::low_mask(Self::EXPONENT_WIDTH) << Self::MANTISSA_WIDTH) + bits + 1
477 } else {
478 (u64::low_mask(Self::EXPONENT_WIDTH + 1) << Self::MANTISSA_WIDTH) - bits
479 }
480 }
481
482 /// Maps a non-negative integer, less than or equal to
483 /// [`LARGEST_ORDERED_REPRESENTATION`](PrimitiveFloat::LARGEST_ORDERED_REPRESENTATION), to a
484 /// float. The map preserves ordering, and adjacent integers are mapped to adjacent floats.
485 ///
486 /// Zero is mapped to negative infinity, and
487 /// [`LARGEST_ORDERED_REPRESENTATION`](PrimitiveFloat::LARGEST_ORDERED_REPRESENTATION) is mapped
488 /// to positive infinity. Negative and positive zero are produced by two distinct adjacent
489 /// integers. `NaN` is never produced.
490 ///
491 /// The inverse operation is
492 /// [`to_ordered_representation`](PrimitiveFloat::to_ordered_representation).
493 ///
494 /// # Worst-case complexity
495 /// Constant time and additional memory.
496 ///
497 /// # Panics
498 /// Panics if `self` is greater than
499 /// [`LARGEST_ORDERED_REPRESENTATION`](PrimitiveFloat::LARGEST_ORDERED_REPRESENTATION).
500 ///
501 /// # Examples
502 /// ```
503 /// use malachite_base::num::basic::floats::PrimitiveFloat;
504 /// use malachite_base::num::basic::traits::NegativeInfinity;
505 ///
506 /// assert_eq!(f32::from_ordered_representation(0), f32::NEGATIVE_INFINITY);
507 /// assert_eq!(f32::from_ordered_representation(2139095040), -0.0f32);
508 /// assert_eq!(f32::from_ordered_representation(2139095041), 0.0f32);
509 /// assert_eq!(f32::from_ordered_representation(3204448257), 1.0f32);
510 /// assert_eq!(f32::from_ordered_representation(4278190081), f32::INFINITY);
511 /// ```
512 fn from_ordered_representation(n: u64) -> Self {
513 let zero_exp = u64::low_mask(Self::EXPONENT_WIDTH) << Self::MANTISSA_WIDTH;
514 let f = if n <= zero_exp {
515 Self::from_bits((u64::low_mask(Self::EXPONENT_WIDTH + 1) << Self::MANTISSA_WIDTH) - n)
516 } else {
517 let f = Self::from_bits(n - zero_exp - 1);
518 assert_eq!(f.sign(), Greater);
519 f
520 };
521 assert!(!f.is_nan());
522 f
523 }
524
525 /// Returns the precision of a nonzero finite floating-point number.
526 ///
527 /// The precision is the number of significant bits of the integer mantissa. For example, the
528 /// positive floats with precision 1 are the powers of 2, those with precision 2 are 3 times a
529 /// power of 2, those with precision 3 are 5 or 7 times a power of 2, and so on.
530 ///
531 /// # Worst-case complexity
532 /// Constant time and additional memory.
533 ///
534 /// # Panics
535 /// Panics if `self` is zero, infinite, or `NaN`.
536 ///
537 /// # Examples
538 /// ```
539 /// use malachite_base::num::basic::floats::PrimitiveFloat;
540 ///
541 /// assert_eq!(1.0.precision(), 1);
542 /// assert_eq!(2.0.precision(), 1);
543 /// assert_eq!(3.0.precision(), 2);
544 /// assert_eq!(1.5.precision(), 2);
545 /// assert_eq!(1.234f32.precision(), 23);
546 /// ```
547 fn precision(self) -> u64 {
548 assert!(self.is_finite());
549 assert!(self != Self::ZERO);
550 let (mut mantissa, exponent) = self.raw_mantissa_and_exponent();
551 if exponent == 0 {
552 mantissa.significant_bits() - TrailingZeros::trailing_zeros(mantissa)
553 } else {
554 mantissa.set_bit(Self::MANTISSA_WIDTH);
555 Self::MANTISSA_WIDTH + 1 - TrailingZeros::trailing_zeros(mantissa)
556 }
557 }
558
559 /// Given a scientific exponent, returns the largest possible precision for a float with that
560 /// exponent.
561 ///
562 /// See the documentation of the [`precision`](PrimitiveFloat::precision) function for a
563 /// definition of precision.
564 ///
565 /// For exponents greater than or equal to
566 /// [`MIN_NORMAL_EXPONENT`](PrimitiveFloat::MIN_NORMAL_EXPONENT), the maximum precision is one
567 /// more than the mantissa width. For smaller exponents (corresponding to the subnormal range),
568 /// the precision is lower.
569 ///
570 /// # Worst-case complexity
571 /// Constant time and additional memory.
572 ///
573 /// # Panics
574 /// Panics if `exponent` is less than [`MIN_EXPONENT`](PrimitiveFloat::MIN_EXPONENT) or greater
575 /// than [`MAX_EXPONENT`](PrimitiveFloat::MAX_EXPONENT).
576 ///
577 /// # Examples
578 /// ```
579 /// use malachite_base::num::basic::floats::PrimitiveFloat;
580 ///
581 /// assert_eq!(f32::max_precision_for_sci_exponent(0), 24);
582 /// assert_eq!(f32::max_precision_for_sci_exponent(127), 24);
583 /// assert_eq!(f32::max_precision_for_sci_exponent(-149), 1);
584 /// assert_eq!(f32::max_precision_for_sci_exponent(-148), 2);
585 /// assert_eq!(f32::max_precision_for_sci_exponent(-147), 3);
586 /// ```
587 fn max_precision_for_sci_exponent(exponent: i64) -> u64 {
588 assert!(exponent >= Self::MIN_EXPONENT);
589 assert!(exponent <= Self::MAX_EXPONENT);
590 if exponent >= Self::MIN_NORMAL_EXPONENT {
591 Self::MANTISSA_WIDTH + 1
592 } else {
593 u64::wrapping_from(exponent - Self::MIN_EXPONENT) + 1
594 }
595 }
596}
597
598/// Defines basic trait implementations for floating-point types.
599macro_rules! impl_basic_traits_primitive_float {
600 (
601 $t: ident,
602 $width: expr,
603 $min_positive_subnormal: expr,
604 $max_subnormal: expr,
605 $min_positive_normal: expr,
606 $prouhet_thue_morse_constant: expr,
607 $prime_constant: expr,
608 $sqrt_3: expr,
609 $sqrt_3_over_3: expr,
610 $phi: expr,
611 $sqrt_pi: expr,
612 $one_over_sqrt_pi: expr,
613 $one_over_sqrt_tau: expr,
614 $gauss_constant: expr,
615 $lemniscate_constant: expr
616 ) => {
617 impl PrimitiveFloat for $t {
618 const WIDTH: u64 = $width;
619 const MANTISSA_WIDTH: u64 = ($t::MANTISSA_DIGITS as u64) - 1;
620
621 const MAX_FINITE: Self = $t::MAX;
622 const MIN_POSITIVE_SUBNORMAL: Self = $min_positive_subnormal;
623 const MAX_SUBNORMAL: Self = $max_subnormal;
624 const MIN_POSITIVE_NORMAL: Self = $min_positive_normal;
625 const SMALLEST_UNREPRESENTABLE_UINT: u64 = (1 << (Self::MANTISSA_WIDTH + 1)) + 1;
626 // We can't shift by $width when $width is 64, so we shift by $width - 1 and then by 1
627 const LARGEST_ORDERED_REPRESENTATION: u64 = (1u64 << ($width - 1) << 1)
628 .wrapping_sub(((1 << Self::MANTISSA_WIDTH) - 1) << 1)
629 - 1;
630
631 #[inline]
632 fn is_nan(self) -> bool {
633 $t::is_nan(self)
634 }
635
636 #[inline]
637 fn is_infinite(self) -> bool {
638 $t::is_infinite(self)
639 }
640
641 #[inline]
642 fn is_finite(self) -> bool {
643 $t::is_finite(self)
644 }
645
646 #[inline]
647 fn is_normal(self) -> bool {
648 $t::is_normal(self)
649 }
650
651 #[inline]
652 fn is_sign_positive(self) -> bool {
653 $t::is_sign_positive(self)
654 }
655
656 #[inline]
657 fn is_sign_negative(self) -> bool {
658 $t::is_sign_negative(self)
659 }
660
661 #[inline]
662 fn classify(self) -> FpCategory {
663 $t::classify(self)
664 }
665
666 #[inline]
667 fn to_bits(self) -> u64 {
668 u64::wrapping_from($t::to_bits(self))
669 }
670
671 #[inline]
672 fn from_bits(v: u64) -> $t {
673 $t::from_bits(v.exact_into())
674 }
675 }
676
677 impl_named!($t);
678
679 /// The constant 0.
680 impl Zero for $t {
681 const ZERO: $t = 0.0;
682 }
683
684 /// The constant 1.
685 impl One for $t {
686 const ONE: $t = 1.0;
687 }
688
689 /// The constant 2.
690 impl Two for $t {
691 const TWO: $t = 2.0;
692 }
693
694 /// The constant 1/2.
695 impl OneHalf for $t {
696 const ONE_HALF: $t = 0.5;
697 }
698
699 /// The constant -1.0 for primitive floating-point types.
700 impl NegativeOne for $t {
701 const NEGATIVE_ONE: $t = -1.0;
702 }
703
704 /// The constant -0.0 for primitive floating-point types.
705 impl NegativeZero for $t {
706 const NEGATIVE_ZERO: $t = -0.0;
707 }
708
709 /// The constant Infinity for primitive floating-point types.
710 impl Infinity for $t {
711 const INFINITY: $t = $t::INFINITY;
712 }
713
714 /// The constant -Infinity for primitive floating-point types.
715 impl NegativeInfinity for $t {
716 const NEGATIVE_INFINITY: $t = $t::NEG_INFINITY;
717 }
718
719 /// The constant NaN for primitive floating-point types.
720 impl NaN for $t {
721 const NAN: $t = $t::NAN;
722 }
723
724 /// The lowest value representable by this type, negative infinity.
725 impl Min for $t {
726 const MIN: $t = $t::NEGATIVE_INFINITY;
727 }
728
729 /// The highest value representable by this type, positive infinity.
730 impl Max for $t {
731 const MAX: $t = $t::INFINITY;
732 }
733
734 /// The Prouhet-Thue-Morse constant.
735 impl ProuhetThueMorseConstant for $t {
736 const PROUHET_THUE_MORSE_CONSTANT: $t = $prouhet_thue_morse_constant;
737 }
738
739 /// The prime constant.
740 impl PrimeConstant for $t {
741 const PRIME_CONSTANT: $t = $prime_constant;
742 }
743
744 /// $\ln 2$.
745 impl Ln2 for $t {
746 const LN_2: $t = core::$t::consts::LN_2;
747 }
748
749 /// $\log_2 e$.
750 impl Log2E for $t {
751 const LOG_2_E: $t = core::$t::consts::LOG2_E;
752 }
753
754 /// $\sqrt{2}$.
755 impl Sqrt2 for $t {
756 const SQRT_2: $t = core::$t::consts::SQRT_2;
757 }
758
759 /// $\sqrt{3}$.
760 impl Sqrt3 for $t {
761 const SQRT_3: $t = $sqrt_3;
762 }
763
764 /// $\sqrt{2}/2=\sqrt{1/2}=1/\sqrt{2}$.
765 impl Sqrt2Over2 for $t {
766 const SQRT_2_OVER_2: $t = core::$t::consts::FRAC_1_SQRT_2;
767 }
768
769 /// $\sqrt{3}/3=\sqrt{1/3}=1/\sqrt{3}$.
770 impl Sqrt3Over3 for $t {
771 const SQRT_3_OVER_3: $t = $sqrt_3_over_3;
772 }
773
774 /// $\varphi$, the golden ratio.
775 impl Phi for $t {
776 const PHI: $t = $phi;
777 }
778
779 /// $\pi$.
780 impl Pi for $t {
781 const PI: $t = core::$t::consts::PI;
782 }
783
784 /// $\tau=2\pi$.
785 impl Tau for $t {
786 const TAU: $t = core::$t::consts::TAU;
787 }
788
789 /// $\pi/2$.
790 impl PiOver2 for $t {
791 const PI_OVER_2: $t = core::$t::consts::FRAC_PI_2;
792 }
793
794 /// $\pi/3$.
795 impl PiOver3 for $t {
796 const PI_OVER_3: $t = core::$t::consts::FRAC_PI_3;
797 }
798
799 /// $\pi/4$.
800 impl PiOver4 for $t {
801 const PI_OVER_4: $t = core::$t::consts::FRAC_PI_4;
802 }
803
804 /// $\pi/6$.
805 impl PiOver6 for $t {
806 const PI_OVER_6: $t = core::$t::consts::FRAC_PI_6;
807 }
808
809 /// $\pi/8$.
810 impl PiOver8 for $t {
811 const PI_OVER_8: $t = core::$t::consts::FRAC_PI_8;
812 }
813
814 /// $1/\pi$.
815 impl OneOverPi for $t {
816 const ONE_OVER_PI: $t = core::$t::consts::FRAC_1_PI;
817 }
818
819 /// $\sqrt{\pi}$.
820 impl SqrtPi for $t {
821 const SQRT_PI: $t = $sqrt_pi;
822 }
823
824 /// $1/\sqrt{\pi}$.
825 impl OneOverSqrtPi for $t {
826 const ONE_OVER_SQRT_PI: $t = $one_over_sqrt_pi;
827 }
828
829 /// $1/\sqrt{\tau}$.
830 impl OneOverSqrtTau for $t {
831 const ONE_OVER_SQRT_TAU: $t = $one_over_sqrt_tau;
832 }
833
834 /// $2/\pi$.
835 impl TwoOverPi for $t {
836 const TWO_OVER_PI: $t = core::$t::consts::FRAC_2_PI;
837 }
838
839 /// $2/\sqrt{\pi}$.
840 impl TwoOverSqrtPi for $t {
841 const TWO_OVER_SQRT_PI: $t = core::$t::consts::FRAC_2_SQRT_PI;
842 }
843
844 /// $G=1/\mathrm{AGM}(1,\sqrt{2})$.
845 impl GaussConstant for $t {
846 const GAUSS_CONSTANT: $t = $gauss_constant;
847 }
848
849 /// $\varpi=\pi G$.
850 impl LemniscateConstant for $t {
851 const LEMNISCATE_CONSTANT: $t = $lemniscate_constant;
852 }
853 };
854}
855impl_basic_traits_primitive_float!(
856 f32,
857 32,
858 1.0e-45,
859 1.1754942e-38,
860 1.1754944e-38,
861 0.41245404,
862 0.4146825,
863 1.7320508,
864 0.57735026,
865 1.618034,
866 1.7724539,
867 0.5641896,
868 0.3989423,
869 0.83462685,
870 2.6220574
871);
872impl_basic_traits_primitive_float!(
873 f64,
874 64,
875 5.0e-324,
876 2.225073858507201e-308,
877 2.2250738585072014e-308,
878 0.4124540336401076,
879 0.41468250985111166,
880 1.7320508075688772,
881 0.5773502691896257,
882 1.618033988749895,
883 1.772453850905516,
884 0.5641895835477563,
885 0.3989422804014327,
886 0.8346268416740732,
887 2.6220575542921196
888);