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 + PrimeConstant
167 + Product
168 + RawMantissaAndExponent<u64, u64>
169 + Reciprocal<Output = Self>
170 + ReciprocalAssign
171 + RefUnwindSafe
172 + Rem<Output = Self>
173 + RemAssign<Self>
174 + RoundingFrom<u8>
175 + RoundingFrom<u16>
176 + RoundingFrom<u32>
177 + RoundingFrom<u64>
178 + RoundingFrom<u128>
179 + RoundingFrom<usize>
180 + RoundingFrom<i8>
181 + RoundingFrom<i16>
182 + RoundingFrom<i32>
183 + RoundingFrom<i64>
184 + RoundingFrom<i128>
185 + RoundingFrom<isize>
186 + RoundingInto<u8>
187 + RoundingInto<u16>
188 + RoundingInto<u32>
189 + RoundingInto<u64>
190 + RoundingInto<u128>
191 + RoundingInto<usize>
192 + RoundingInto<i8>
193 + RoundingInto<i16>
194 + RoundingInto<i32>
195 + RoundingInto<i64>
196 + RoundingInto<i128>
197 + RoundingInto<isize>
198 + SciMantissaAndExponent<Self, i64>
199 + Sign
200 + Sized
201 + Sqrt<Output = Self>
202 + SqrtAssign
203 + Square<Output = Self>
204 + SquareAssign
205 + Sub<Output = Self>
206 + SubAssign<Self>
207 + SubMul<Output = Self>
208 + SubMulAssign<Self, Self>
209 + Sum<Self>
210 + ThueMorseConstant
211 + Two
212 + UpperExp
213 + Zero
214{
215 /// The number of bits taken up by the type.
216 ///
217 /// This is $M+E+1$. The three terms in the sum correspond to the width of the mantissa, the
218 /// width of the exponent, and the sign bit.
219 /// - For [`f32`]s, this is 32.
220 /// - For [`f64`]s, this is 64.
221 const WIDTH: u64;
222 /// The number of bits taken up by the exponent.
223 /// - For [`f32`]s, this is 8.
224 /// - For [`f64`]s, this is 11.
225 const EXPONENT_WIDTH: u64 = Self::WIDTH - Self::MANTISSA_WIDTH - 1;
226 /// The number of bits taken up by the mantissa.
227 /// - For [`f32`]s, this is 23.
228 /// - For [`f64`]s, this is 52.
229 const MANTISSA_WIDTH: u64;
230 /// The smallest possible exponent of a float in the normal range. Any floats with smaller
231 /// exponents are subnormal and thus have reduced precision. This is $2-2^{E-1}$.
232 /// - For [`f32`]s, this is -126.
233 /// - For [`f64`]s, this is -1022.
234 const MIN_NORMAL_EXPONENT: i64 = -(1 << (Self::EXPONENT_WIDTH - 1)) + 2;
235 /// The smallest possible exponent of a float. This is $2-2^{E-1}-M$.
236 /// - For [`f32`]s, this is -149.
237 /// - For [`f64`]s, this is -1074.
238 const MIN_EXPONENT: i64 = Self::MIN_NORMAL_EXPONENT - (Self::MANTISSA_WIDTH as i64);
239 /// The largest possible exponent of a float. This is $2^{E-1}-1$.
240 /// - For [`f32`]s, this is 127.
241 /// - For [`f64`]s, this is 1023.
242 const MAX_EXPONENT: i64 = (1 << (Self::EXPONENT_WIDTH - 1)) - 1;
243 /// The smallest positive float. This is $2^{2-2^{E-1}-M}$.
244 /// - For [`f32`]s, this is $2^{-149}$, or `1.0e-45`.
245 /// - For [`f64`]s, this is $2^{-1074}$, or `5.0e-324`.
246 const MIN_POSITIVE_SUBNORMAL: Self;
247 /// The largest float in the subnormal range. This is $2^{2-2^{E-1}-M}(2^M-1)$.
248 /// - For [`f32`]s, this is $2^{-149}(2^{23}-1)$, or `1.1754942e-38`.
249 /// - For [`f64`]s, this is $2^{-1074}(2^{52}-1)$, or `2.225073858507201e-308`.
250 const MAX_SUBNORMAL: Self;
251 /// The smallest positive normal float. This is $2^{2-2^{E-1}}$.
252 /// - For [`f32`]s, this is $2^{-126}$, or `1.1754944e-38`.
253 /// - For [`f64`]s, this is $2^{-1022}$, or `2.2250738585072014e-308`.
254 const MIN_POSITIVE_NORMAL: Self;
255 /// The largest finite float. This is $2^{2^{E-1}-1}(2-2^{-M})$.
256 /// - For [`f32`]s, this is $2^{127}(2-2^{-23})$, or `3.4028235e38`.
257 /// - For [`f64`]s, this is $2^{1023}(2-2^{-52})$, or `1.7976931348623157e308`.
258 const MAX_FINITE: Self;
259 /// The smallest positive integer that cannot be represented as a float. This is $2^{M+1}+1$.
260 /// - For [`f32`]s, this is $2^{24}+1$, or 16777217.
261 /// - For [`f64`]s, this is $2^{53}+1$, or 9007199254740993.
262 const SMALLEST_UNREPRESENTABLE_UINT: u64;
263 /// If you list all floats in increasing order, excluding NaN and giving negative and positive
264 /// zero separate adjacent spots, this will be index of the last element, positive infinity. It
265 /// is $2^{M+1}(2^E-1)+1$.
266 /// - For [`f32`]s, this is $2^{32}-2^{24}+1$, or 4278190081.
267 /// - For [`f64`]s, this is $2^{64}-2^{53}+1$, or 18437736874454810625.
268 const LARGEST_ORDERED_REPRESENTATION: u64;
269
270 fn is_nan(self) -> bool;
271
272 fn is_infinite(self) -> bool;
273
274 fn is_finite(self) -> bool;
275
276 fn is_normal(self) -> bool;
277
278 fn is_sign_positive(self) -> bool;
279
280 fn is_sign_negative(self) -> bool;
281
282 fn classify(self) -> FpCategory;
283
284 fn to_bits(self) -> u64;
285
286 fn from_bits(v: u64) -> Self;
287
288 /// Tests whether `self` is negative zero.
289 ///
290 /// # Worst-case complexity
291 /// Constant time and additional memory.
292 ///
293 /// # Examples
294 /// ```
295 /// use malachite_base::num::basic::floats::PrimitiveFloat;
296 ///
297 /// assert!((-0.0).is_negative_zero());
298 /// assert!(!0.0.is_negative_zero());
299 /// assert!(!1.0.is_negative_zero());
300 /// assert!(!f32::NAN.is_negative_zero());
301 /// assert!(!f32::INFINITY.is_negative_zero());
302 /// ```
303 #[inline]
304 fn is_negative_zero(self) -> bool {
305 self.sign() == Less && self == Self::ZERO
306 }
307
308 /// If `self` is negative zero, returns positive zero; otherwise, returns `self`.
309 ///
310 /// # Worst-case complexity
311 /// Constant time and additional memory.
312 ///
313 /// # Examples
314 /// ```
315 /// use malachite_base::num::basic::floats::PrimitiveFloat;
316 /// use malachite_base::num::float::NiceFloat;
317 ///
318 /// assert_eq!(NiceFloat((-0.0).abs_negative_zero()), NiceFloat(0.0));
319 /// assert_eq!(NiceFloat(0.0.abs_negative_zero()), NiceFloat(0.0));
320 /// assert_eq!(NiceFloat(1.0.abs_negative_zero()), NiceFloat(1.0));
321 /// assert_eq!(NiceFloat((-1.0).abs_negative_zero()), NiceFloat(-1.0));
322 /// assert_eq!(NiceFloat(f32::NAN.abs_negative_zero()), NiceFloat(f32::NAN));
323 /// ```
324 #[inline]
325 fn abs_negative_zero(self) -> Self {
326 if self == Self::ZERO { Self::ZERO } else { self }
327 }
328
329 /// If `self` is negative zero, replaces it with positive zero; otherwise, leaves `self`
330 /// unchanged.
331 ///
332 /// # Worst-case complexity
333 /// Constant time and additional memory.
334 ///
335 /// # Examples
336 /// ```
337 /// use malachite_base::num::basic::floats::PrimitiveFloat;
338 /// use malachite_base::num::float::NiceFloat;
339 ///
340 /// let mut f = -0.0;
341 /// f.abs_negative_zero_assign();
342 /// assert_eq!(NiceFloat(f), NiceFloat(0.0));
343 ///
344 /// let mut f = 0.0;
345 /// f.abs_negative_zero_assign();
346 /// assert_eq!(NiceFloat(f), NiceFloat(0.0));
347 ///
348 /// let mut f = 1.0;
349 /// f.abs_negative_zero_assign();
350 /// assert_eq!(NiceFloat(f), NiceFloat(1.0));
351 ///
352 /// let mut f = -1.0;
353 /// f.abs_negative_zero_assign();
354 /// assert_eq!(NiceFloat(f), NiceFloat(-1.0));
355 ///
356 /// let mut f = f32::NAN;
357 /// f.abs_negative_zero_assign();
358 /// assert_eq!(NiceFloat(f), NiceFloat(f32::NAN));
359 /// ```
360 #[inline]
361 fn abs_negative_zero_assign(&mut self) {
362 if *self == Self::ZERO {
363 *self = Self::ZERO;
364 }
365 }
366
367 /// Returns the smallest float larger than `self`.
368 ///
369 /// Passing `-0.0` returns `0.0`; passing `NaN` or positive infinity panics.
370 ///
371 /// # Worst-case complexity
372 /// Constant time and additional memory.
373 ///
374 /// # Panics
375 /// Panics if `self` is `NaN` or positive infinity.
376 ///
377 /// # Examples
378 /// ```
379 /// use malachite_base::num::basic::floats::PrimitiveFloat;
380 /// use malachite_base::num::float::NiceFloat;
381 ///
382 /// assert_eq!(NiceFloat((-0.0f32).next_higher()), NiceFloat(0.0));
383 /// assert_eq!(NiceFloat(0.0f32.next_higher()), NiceFloat(1.0e-45));
384 /// assert_eq!(NiceFloat(1.0f32.next_higher()), NiceFloat(1.0000001));
385 /// assert_eq!(NiceFloat((-1.0f32).next_higher()), NiceFloat(-0.99999994));
386 /// ```
387 fn next_higher(self) -> Self {
388 assert!(!self.is_nan());
389 if self.sign() == Greater {
390 assert_ne!(self, Self::INFINITY);
391 Self::from_bits(self.to_bits() + 1)
392 } else if self == Self::ZERO {
393 // negative zero -> positive zero
394 Self::ZERO
395 } else {
396 Self::from_bits(self.to_bits() - 1)
397 }
398 }
399
400 /// Returns the largest float smaller than `self`.
401 ///
402 /// Passing `0.0` returns `-0.0`; passing `NaN` or negative infinity panics.
403 ///
404 /// # Worst-case complexity
405 /// Constant time and additional memory.
406 ///
407 /// # Panics
408 /// Panics if `self` is `NaN` or negative infinity.
409 ///
410 /// # Examples
411 /// ```
412 /// use malachite_base::num::basic::floats::PrimitiveFloat;
413 /// use malachite_base::num::float::NiceFloat;
414 ///
415 /// assert_eq!(NiceFloat(0.0f32.next_lower()), NiceFloat(-0.0));
416 /// assert_eq!(NiceFloat((-0.0f32).next_lower()), NiceFloat(-1.0e-45));
417 /// assert_eq!(NiceFloat(1.0f32.next_lower()), NiceFloat(0.99999994));
418 /// assert_eq!(NiceFloat((-1.0f32).next_lower()), NiceFloat(-1.0000001));
419 /// ```
420 fn next_lower(self) -> Self {
421 assert!(!self.is_nan());
422 if self.sign() == Less {
423 assert_ne!(self, Self::NEGATIVE_INFINITY);
424 Self::from_bits(self.to_bits() + 1)
425 } else if self == Self::ZERO {
426 // positive zero -> negative zero
427 Self::NEGATIVE_ZERO
428 } else {
429 Self::from_bits(self.to_bits() - 1)
430 }
431 }
432
433 /// Maps `self` to an integer. The map preserves ordering, and adjacent floats are mapped to
434 /// adjacent integers.
435 ///
436 /// Negative infinity is mapped to 0, and positive infinity is mapped to the largest value,
437 /// [`LARGEST_ORDERED_REPRESENTATION`](PrimitiveFloat::LARGEST_ORDERED_REPRESENTATION). Negative
438 /// and positive zero are mapped to distinct adjacent values. Passing in `NaN` panics.
439 ///
440 /// The inverse operation is
441 /// [`from_ordered_representation`](PrimitiveFloat::from_ordered_representation).
442 ///
443 /// # Worst-case complexity
444 /// Constant time and additional memory.
445 ///
446 /// # Panics
447 /// Panics if `self` is `NaN`.
448 ///
449 /// # Examples
450 /// ```
451 /// use malachite_base::num::basic::floats::PrimitiveFloat;
452 /// use malachite_base::num::basic::traits::NegativeInfinity;
453 ///
454 /// assert_eq!(f32::NEGATIVE_INFINITY.to_ordered_representation(), 0);
455 /// assert_eq!((-0.0f32).to_ordered_representation(), 2139095040);
456 /// assert_eq!(0.0f32.to_ordered_representation(), 2139095041);
457 /// assert_eq!(1.0f32.to_ordered_representation(), 3204448257);
458 /// assert_eq!(f32::INFINITY.to_ordered_representation(), 4278190081);
459 /// ```
460 fn to_ordered_representation(self) -> u64 {
461 assert!(!self.is_nan());
462 let bits = self.to_bits();
463 if self.sign() == Greater {
464 (u64::low_mask(Self::EXPONENT_WIDTH) << Self::MANTISSA_WIDTH) + bits + 1
465 } else {
466 (u64::low_mask(Self::EXPONENT_WIDTH + 1) << Self::MANTISSA_WIDTH) - bits
467 }
468 }
469
470 /// Maps a non-negative integer, less than or equal to
471 /// [`LARGEST_ORDERED_REPRESENTATION`](PrimitiveFloat::LARGEST_ORDERED_REPRESENTATION), to a
472 /// float. The map preserves ordering, and adjacent integers are mapped to adjacent floats.
473 ///
474 /// Zero is mapped to negative infinity, and
475 /// [`LARGEST_ORDERED_REPRESENTATION`](PrimitiveFloat::LARGEST_ORDERED_REPRESENTATION) is mapped
476 /// to positive infinity. Negative and positive zero are produced by two distinct adjacent
477 /// integers. `NaN` is never produced.
478 ///
479 /// The inverse operation is
480 /// [`to_ordered_representation`](PrimitiveFloat::to_ordered_representation).
481 ///
482 /// # Worst-case complexity
483 /// Constant time and additional memory.
484 ///
485 /// # Panics
486 /// Panics if `self` is greater than
487 /// [`LARGEST_ORDERED_REPRESENTATION`](PrimitiveFloat::LARGEST_ORDERED_REPRESENTATION).
488 ///
489 /// # Examples
490 /// ```
491 /// use malachite_base::num::basic::floats::PrimitiveFloat;
492 /// use malachite_base::num::basic::traits::NegativeInfinity;
493 ///
494 /// assert_eq!(f32::from_ordered_representation(0), f32::NEGATIVE_INFINITY);
495 /// assert_eq!(f32::from_ordered_representation(2139095040), -0.0f32);
496 /// assert_eq!(f32::from_ordered_representation(2139095041), 0.0f32);
497 /// assert_eq!(f32::from_ordered_representation(3204448257), 1.0f32);
498 /// assert_eq!(f32::from_ordered_representation(4278190081), f32::INFINITY);
499 /// ```
500 fn from_ordered_representation(n: u64) -> Self {
501 let zero_exp = u64::low_mask(Self::EXPONENT_WIDTH) << Self::MANTISSA_WIDTH;
502 let f = if n <= zero_exp {
503 Self::from_bits((u64::low_mask(Self::EXPONENT_WIDTH + 1) << Self::MANTISSA_WIDTH) - n)
504 } else {
505 let f = Self::from_bits(n - zero_exp - 1);
506 assert_eq!(f.sign(), Greater);
507 f
508 };
509 assert!(!f.is_nan());
510 f
511 }
512
513 /// Returns the precision of a nonzero finite floating-point number.
514 ///
515 /// The precision is the number of significant bits of the integer mantissa. For example, the
516 /// floats with precision 1 are the powers of 2, those with precision 2 are 3 times a power of
517 /// 2, those with precision 3 are 5 or 7 times a power of 2, and so on.
518 ///
519 /// # Worst-case complexity
520 /// Constant time and additional memory.
521 ///
522 /// # Panics
523 /// Panics if `self` is zero, infinite, or `NaN`.
524 ///
525 /// # Examples
526 /// ```
527 /// use malachite_base::num::basic::floats::PrimitiveFloat;
528 ///
529 /// assert_eq!(1.0.precision(), 1);
530 /// assert_eq!(2.0.precision(), 1);
531 /// assert_eq!(3.0.precision(), 2);
532 /// assert_eq!(1.5.precision(), 2);
533 /// assert_eq!(1.234f32.precision(), 23);
534 /// ```
535 fn precision(self) -> u64 {
536 assert!(self.is_finite());
537 assert!(self != Self::ZERO);
538 let (mut mantissa, exponent) = self.raw_mantissa_and_exponent();
539 if exponent == 0 {
540 mantissa.significant_bits() - TrailingZeros::trailing_zeros(mantissa)
541 } else {
542 mantissa.set_bit(Self::MANTISSA_WIDTH);
543 Self::MANTISSA_WIDTH + 1 - TrailingZeros::trailing_zeros(mantissa)
544 }
545 }
546
547 /// Given a scientific exponent, returns the largest possible precision for a float with that
548 /// exponent.
549 ///
550 /// See the documentation of the [`precision`](PrimitiveFloat::precision) function for a
551 /// definition of precision.
552 ///
553 /// For exponents greater than or equal to
554 /// [`MIN_NORMAL_EXPONENT`](PrimitiveFloat::MIN_NORMAL_EXPONENT), the maximum precision is one
555 /// more than the mantissa width. For smaller exponents (corresponding to the subnormal range),
556 /// the precision is lower.
557 ///
558 /// # Worst-case complexity
559 /// Constant time and additional memory.
560 ///
561 /// # Panics
562 /// Panics if `exponent` is less than [`MIN_EXPONENT`](PrimitiveFloat::MIN_EXPONENT) or greater
563 /// than [`MAX_EXPONENT`](PrimitiveFloat::MAX_EXPONENT).
564 ///
565 /// # Examples
566 /// ```
567 /// use malachite_base::num::basic::floats::PrimitiveFloat;
568 ///
569 /// assert_eq!(f32::max_precision_for_sci_exponent(0), 24);
570 /// assert_eq!(f32::max_precision_for_sci_exponent(127), 24);
571 /// assert_eq!(f32::max_precision_for_sci_exponent(-149), 1);
572 /// assert_eq!(f32::max_precision_for_sci_exponent(-148), 2);
573 /// assert_eq!(f32::max_precision_for_sci_exponent(-147), 3);
574 /// ```
575 fn max_precision_for_sci_exponent(exponent: i64) -> u64 {
576 assert!(exponent >= Self::MIN_EXPONENT);
577 assert!(exponent <= Self::MAX_EXPONENT);
578 if exponent >= Self::MIN_NORMAL_EXPONENT {
579 Self::MANTISSA_WIDTH + 1
580 } else {
581 u64::wrapping_from(exponent - Self::MIN_EXPONENT) + 1
582 }
583 }
584}
585
586/// Defines basic trait implementations for floating-point types.
587macro_rules! impl_basic_traits_primitive_float {
588 (
589 $t: ident,
590 $width: expr,
591 $min_positive_subnormal: expr,
592 $max_subnormal: expr,
593 $min_positive_normal: expr,
594 $thue_morse_constant: expr,
595 $prime_constant: expr
596 ) => {
597 impl PrimitiveFloat for $t {
598 const WIDTH: u64 = $width;
599 const MANTISSA_WIDTH: u64 = ($t::MANTISSA_DIGITS as u64) - 1;
600
601 const MAX_FINITE: Self = $t::MAX;
602 const MIN_POSITIVE_SUBNORMAL: Self = $min_positive_subnormal;
603 const MAX_SUBNORMAL: Self = $max_subnormal;
604 const MIN_POSITIVE_NORMAL: Self = $min_positive_normal;
605 const SMALLEST_UNREPRESENTABLE_UINT: u64 = (1 << (Self::MANTISSA_WIDTH + 1)) + 1;
606 // We can't shift by $width when $width is 64, so we shift by $width - 1 and then by 1
607 const LARGEST_ORDERED_REPRESENTATION: u64 = (1u64 << ($width - 1) << 1)
608 .wrapping_sub(((1 << Self::MANTISSA_WIDTH) - 1) << 1)
609 - 1;
610
611 #[inline]
612 fn is_nan(self) -> bool {
613 $t::is_nan(self)
614 }
615
616 #[inline]
617 fn is_infinite(self) -> bool {
618 $t::is_infinite(self)
619 }
620
621 #[inline]
622 fn is_finite(self) -> bool {
623 $t::is_finite(self)
624 }
625
626 #[inline]
627 fn is_normal(self) -> bool {
628 $t::is_normal(self)
629 }
630
631 #[inline]
632 fn is_sign_positive(self) -> bool {
633 $t::is_sign_positive(self)
634 }
635
636 #[inline]
637 fn is_sign_negative(self) -> bool {
638 $t::is_sign_negative(self)
639 }
640
641 #[inline]
642 fn classify(self) -> FpCategory {
643 $t::classify(self)
644 }
645
646 #[inline]
647 fn to_bits(self) -> u64 {
648 u64::wrapping_from($t::to_bits(self))
649 }
650
651 #[inline]
652 fn from_bits(v: u64) -> $t {
653 $t::from_bits(v.exact_into())
654 }
655 }
656
657 impl_named!($t);
658
659 /// The constant 0.
660 impl Zero for $t {
661 const ZERO: $t = 0.0;
662 }
663
664 /// The constant 1.
665 impl One for $t {
666 const ONE: $t = 1.0;
667 }
668
669 /// The constant 2.
670 impl Two for $t {
671 const TWO: $t = 2.0;
672 }
673
674 /// The constant 1/2.
675 impl OneHalf for $t {
676 const ONE_HALF: $t = 0.5;
677 }
678
679 /// The constant -1.0 for primitive floating-point types.
680 impl NegativeOne for $t {
681 const NEGATIVE_ONE: $t = -1.0;
682 }
683
684 /// The constant -0.0 for primitive floating-point types.
685 impl NegativeZero for $t {
686 const NEGATIVE_ZERO: $t = -0.0;
687 }
688
689 /// The constant Infinity for primitive floating-point types.
690 impl Infinity for $t {
691 const INFINITY: $t = $t::INFINITY;
692 }
693
694 /// The constant -Infinity for primitive floating-point types.
695 impl NegativeInfinity for $t {
696 const NEGATIVE_INFINITY: $t = $t::NEG_INFINITY;
697 }
698
699 /// The constant NaN for primitive floating-point types.
700 impl NaN for $t {
701 const NAN: $t = $t::NAN;
702 }
703
704 /// The lowest value representable by this type, negative infinity.
705 impl Min for $t {
706 const MIN: $t = $t::NEGATIVE_INFINITY;
707 }
708
709 /// The highest value representable by this type, positive infinity.
710 impl Max for $t {
711 const MAX: $t = $t::INFINITY;
712 }
713
714 /// The Thue-Morse constant.
715 impl ThueMorseConstant for $t {
716 const THUE_MORSE_CONSTANT: $t = $thue_morse_constant;
717 }
718
719 /// The prime constant.
720 impl PrimeConstant for $t {
721 const PRIME_CONSTANT: $t = $prime_constant;
722 }
723 };
724}
725impl_basic_traits_primitive_float!(
726 f32,
727 32,
728 1.0e-45,
729 1.1754942e-38,
730 1.1754944e-38,
731 0.41245404,
732 0.4146825
733);
734impl_basic_traits_primitive_float!(
735 f64,
736 64,
737 5.0e-324,
738 2.225073858507201e-308,
739 2.2250738585072014e-308,
740 0.4124540336401076,
741 0.41468250985111166
742);