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