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