core/num/float_macros.rs
1#[rustc_macro_transparency = "semiopaque"]
2pub(crate) macro float_impl(
3 Self = $SelfT:ty,
4 Bits = $BitsT:ty,
5 SignedBits = $SignedBitsT:ty,
6 // Constants
7 BITS = $BITS:literal,
8 MANTISSA_DIGITS = $MANTISSA_DIGITS:literal,
9 DIGITS = $DIGITS:literal,
10 EPSILON = $EPSILON:literal,
11 MIN = $MIN:literal,
12 MIN_POSITIVE = $MIN_POSITIVE:literal,
13 MAX = $MAX:literal,
14 MIN_EXP = $MIN_EXP:literal,
15 MAX_EXP = $MAX_EXP:literal,
16 MIN_10_EXP = $MIN_10_EXP:literal,
17 MAX_10_EXP = $MAX_10_EXP:literal,
18 SIGN_MASK = $SIGN_MASK:literal,
19 EXPONENT_MASK = $EXPONENT_MASK:literal,
20 MANTISSA_MASK = $MANTISSA_MASK:literal,
21 // Values for docs
22 exponent_bias = $exponent_bias:literal,
23 // Feature gates
24 assoc_int_consts = #[$assoc_int_consts:meta],
25 // Things needed for `f16`/`f128` doctests
26 $(feature = $feature:ident,)?
27 $(has_reliable_cfg = $has_reliable_cfg:ident,)?
28 $(has_reliable_math_cfg = $has_reliable_math_cfg:ident,)?
29) {
30
31 /// The radix or base of the internal representation of
32 #[doc = concat!("`", stringify!($SelfT), "`.")]
33 #[$assoc_int_consts]
34 pub const RADIX: u32 = 2;
35
36 /// The size of this float type in bits.
37 #[unstable(feature = "float_bits_const", issue = "151073")]
38 pub const BITS: u32 = $BITS;
39
40 /// Number of significant digits in base 2.
41 ///
42 /// Note that the size of the mantissa in the bitwise representation is one
43 /// smaller than this since the leading 1 is not stored explicitly.
44 #[$assoc_int_consts]
45 pub const MANTISSA_DIGITS: u32 = $MANTISSA_DIGITS;
46
47 /// Approximate number of significant digits in base 10.
48 ///
49 /// This is the maximum <i>x</i> such that any decimal number with <i>x</i>
50 /// significant digits can be converted to
51 #[doc = concat!("`", stringify!($SelfT), "`")]
52 /// and back without loss.
53 ///
54 /// Equal to floor(log<sub>10</sub> 2<sup>[`MANTISSA_DIGITS`] − 1</sup>).
55 ///
56 /// [`MANTISSA_DIGITS`]: Self::MANTISSA_DIGITS
57 #[$assoc_int_consts]
58 pub const DIGITS: u32 = $DIGITS;
59
60 /// [Machine epsilon] value for
61 #[doc = concat!("`", stringify!($SelfT), "`.")]
62 ///
63 /// This is the difference between `1.0` and the next larger representable number.
64 ///
65 /// Equal to 2<sup>1 − [`MANTISSA_DIGITS`]</sup>.
66 ///
67 /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon
68 /// [`MANTISSA_DIGITS`]: Self::MANTISSA_DIGITS
69 #[$assoc_int_consts]
70 #[rustc_diagnostic_item = concat!(stringify!($SelfT), "_epsilon")]
71 pub const EPSILON: Self = $EPSILON;
72
73 /// Smallest finite
74 #[doc = concat!("`", stringify!($SelfT), "`")]
75 /// value.
76 ///
77 /// Equal to −[`MAX`].
78 ///
79 /// [`MAX`]: Self::MAX
80 #[$assoc_int_consts]
81 pub const MIN: Self = $MIN;
82 /// Smallest positive normal
83 #[doc = concat!("`", stringify!($SelfT), "`")]
84 /// value.
85 ///
86 /// Equal to 2<sup>[`MIN_EXP`] − 1</sup>.
87 ///
88 /// [`MIN_EXP`]: Self::MIN_EXP
89 #[$assoc_int_consts]
90 pub const MIN_POSITIVE: Self = $MIN_POSITIVE;
91 /// Largest finite
92 #[doc = concat!("`", stringify!($SelfT), "`")]
93 /// value.
94 ///
95 /// Equal to
96 /// (1 − 2<sup>−[`MANTISSA_DIGITS`]</sup>) 2<sup>[`MAX_EXP`]</sup>.
97 ///
98 /// [`MANTISSA_DIGITS`]: Self::MANTISSA_DIGITS
99 /// [`MAX_EXP`]: Self::MAX_EXP
100 #[$assoc_int_consts]
101 pub const MAX: Self = $MAX;
102
103 /// One greater than the minimum possible *normal* power of 2 exponent
104 /// for a significand bounded by 1 ≤ x < 2 (i.e. the IEEE definition).
105 ///
106 /// This corresponds to the exact minimum possible *normal* power of 2 exponent
107 /// for a significand bounded by 0.5 ≤ x < 1 (i.e. the C definition).
108 /// In other words, all normal numbers representable by this type are
109 /// greater than or equal to 0.5 × 2<sup><i>MIN_EXP</i></sup>.
110 #[$assoc_int_consts]
111 pub const MIN_EXP: i32 = $MIN_EXP;
112 /// One greater than the maximum possible power of 2 exponent
113 /// for a significand bounded by 1 ≤ x < 2 (i.e. the IEEE definition).
114 ///
115 /// This corresponds to the exact maximum possible power of 2 exponent
116 /// for a significand bounded by 0.5 ≤ x < 1 (i.e. the C definition).
117 /// In other words, all numbers representable by this type are
118 /// strictly less than 2<sup><i>MAX_EXP</i></sup>.
119 #[$assoc_int_consts]
120 pub const MAX_EXP: i32 = $MAX_EXP;
121
122 /// Minimum <i>x</i> for which 10<sup><i>x</i></sup> is normal.
123 ///
124 /// Equal to ceil(log<sub>10</sub> [`MIN_POSITIVE`]).
125 ///
126 /// [`MIN_POSITIVE`]: Self::MIN_POSITIVE
127 #[$assoc_int_consts]
128 pub const MIN_10_EXP: i32 = $MIN_10_EXP;
129 /// Maximum <i>x</i> for which 10<sup><i>x</i></sup> is normal.
130 ///
131 /// Equal to floor(log<sub>10</sub> [`MAX`]).
132 ///
133 /// [`MAX`]: Self::MAX
134 #[$assoc_int_consts]
135 pub const MAX_10_EXP: i32 = $MAX_10_EXP;
136
137 /// Not a Number (NaN).
138 ///
139 /// Note that IEEE 754 doesn't define just a single NaN value; a plethora of bit patterns are
140 /// considered to be NaN. Furthermore, the standard makes a difference between a "signaling" and
141 /// a "quiet" NaN, and allows inspecting its "payload" (the unspecified bits in the bit pattern)
142 /// and its sign. See the [specification of NaN bit patterns](f32#nan-bit-patterns) for more
143 /// info.
144 ///
145 /// This constant is guaranteed to be a quiet NaN (on targets that follow the Rust assumptions
146 /// that the quiet/signaling bit being set to 1 indicates a quiet NaN). Beyond that, nothing is
147 /// guaranteed about the specific bit pattern chosen here: both payload and sign are arbitrary.
148 /// The concrete bit pattern may change across Rust versions and target platforms.
149 #[$assoc_int_consts]
150 #[rustc_diagnostic_item = concat!(stringify!($SelfT), "_nan")]
151 #[allow(clippy::eq_op, clippy::zero_divided_by_zero)]
152 pub const NAN: Self = 0.0 / 0.0;
153 /// Infinity (∞).
154 #[$assoc_int_consts]
155 pub const INFINITY: Self = 1.0 / 0.0;
156 /// Negative infinity (−∞).
157 #[$assoc_int_consts]
158 pub const NEG_INFINITY: Self = -1.0 / 0.0;
159
160 /// Maximum integer that can be represented exactly in an
161 #[doc = concat!("[`", stringify!($SelfT), "`]")]
162 /// value, with no other integer converting to the same floating point value.
163 ///
164 /// For an integer `x` which satisfies `MIN_EXACT_INTEGER <= x <= MAX_EXACT_INTEGER`,
165 /// there is a "one-to-one" mapping between
166 #[doc = concat!(" [`", stringify!($SignedBitsT), "`]")]
167 /// and
168 #[doc = concat!("[`", stringify!($SelfT), "`]")]
169 /// values. `MAX_EXACT_INTEGER + 1` also converts losslessly to
170 #[doc = concat!("[`", stringify!($SelfT), "`]")]
171 /// and back to
172 #[doc = concat!("[`", stringify!($SignedBitsT), "`],")]
173 /// but `MAX_EXACT_INTEGER + 2` converts to the same
174 #[doc = concat!("[`", stringify!($SelfT), "`]")]
175 /// value (and back to `MAX_EXACT_INTEGER + 1` as an integer) so there is not a
176 /// "one-to-one" mapping.
177 ///
178 /// [`MAX_EXACT_INTEGER`]: Self::MAX_EXACT_INTEGER
179 /// [`MIN_EXACT_INTEGER`]: Self::MIN_EXACT_INTEGER
180 /// ```
181 $(#[doc = concat!("#![feature(", stringify!($feature), ")]")])?
182 /// #![feature(float_exact_integer_constants)]
183 /// # // FIXME(#152635): Float rounding on `i586` does not adhere to IEEE 754
184 /// # #[cfg(not(all(target_arch = "x86", not(target_feature = "sse"))))] {
185 $(#[doc = concat!("# #[cfg(", stringify!($has_reliable_cfg), ")] {")])?
186 #[doc = concat!("let max_exact_int = ", stringify!($SelfT), "::MAX_EXACT_INTEGER;")]
187 #[doc = concat!("assert_eq!(max_exact_int, max_exact_int as ", stringify!($SelfT), " as ", stringify!($SignedBitsT), ");")]
188 #[doc = concat!("assert_eq!(max_exact_int + 1, (max_exact_int + 1) as ", stringify!($SelfT), " as ", stringify!($SignedBitsT), ");")]
189 #[doc = concat!("assert_ne!(max_exact_int + 2, (max_exact_int + 2) as ", stringify!($SelfT), " as ", stringify!($SignedBitsT), ");")]
190 ///
191 #[doc = concat!("// Beyond `", stringify!($SelfT), "::MAX_EXACT_INTEGER`, multiple integers can map to one float value")]
192 #[doc = concat!("assert_eq!((max_exact_int + 1) as ", stringify!($SelfT), ", (max_exact_int + 2) as ", stringify!($SelfT), ");")]
193 #[doc = concat!("# }" $(${ignore($has_reliable_cfg)}, "}")?)]
194 /// ```
195 #[unstable(feature = "float_exact_integer_constants", issue = "152466")]
196 pub const MAX_EXACT_INTEGER: $SignedBitsT = (1 << Self::MANTISSA_DIGITS) - 1;
197
198 /// Minimum integer that can be represented exactly in an
199 #[doc = concat!("[`", stringify!($SelfT), "`]")]
200 /// value, with no other integer converting to the same floating point value.
201 ///
202 /// For an integer `x` which satisfies `MIN_EXACT_INTEGER <= x <= MAX_EXACT_INTEGER`,
203 /// there is a "one-to-one" mapping between
204 #[doc = concat!(" [`", stringify!($SignedBitsT), "`]")]
205 /// and
206 #[doc = concat!("[`", stringify!($SelfT), "`]")]
207 /// values. `MAX_EXACT_INTEGER + 1` also converts losslessly to
208 #[doc = concat!("[`", stringify!($SelfT), "`]")]
209 /// and back to
210 #[doc = concat!(" [`", stringify!($SignedBitsT), "`],")]
211 /// but `MAX_EXACT_INTEGER + 2` converts to the same
212 #[doc = concat!("[`", stringify!($SelfT), "`]")]
213 /// value (and back to `MAX_EXACT_INTEGER + 1` as an integer) so there is not a
214 /// "one-to-one" mapping.
215 ///
216 /// This constant is equivalent to `-MAX_EXACT_INTEGER`.
217 ///
218 /// [`MAX_EXACT_INTEGER`]: Self::MAX_EXACT_INTEGER
219 /// [`MIN_EXACT_INTEGER`]: Self::MIN_EXACT_INTEGER
220 /// ```
221 $(#[doc = concat!("#![feature(", stringify!($feature), ")]")])?
222 /// #![feature(float_exact_integer_constants)]
223 /// # // FIXME(#152635): Float rounding on `i586` does not adhere to IEEE 754
224 /// # #[cfg(not(all(target_arch = "x86", not(target_feature = "sse"))))] {
225 $(#[doc = concat!("# #[cfg(", stringify!($has_reliable_cfg), ")] {")])?
226 #[doc = concat!("let min_exact_int = ", stringify!($SelfT), "::MIN_EXACT_INTEGER;")]
227 #[doc = concat!("assert_eq!(min_exact_int, min_exact_int as ", stringify!($SelfT), " as ", stringify!($SignedBitsT), ");")]
228 #[doc = concat!("assert_eq!(min_exact_int - 1, (min_exact_int - 1) as ", stringify!($SelfT), " as ", stringify!($SignedBitsT), ");")]
229 #[doc = concat!("assert_ne!(min_exact_int - 2, (min_exact_int - 2) as ", stringify!($SelfT), " as ", stringify!($SignedBitsT), ");")]
230 ///
231 #[doc = concat!("// Below `", stringify!($SelfT), "::MIN_EXACT_INTEGER`, multiple integers can map to one float value")]
232 #[doc = concat!("assert_eq!((min_exact_int - 1) as ", stringify!($SelfT), ", (min_exact_int - 2) as ", stringify!($SelfT), ");")]
233 #[doc = concat!("# }" $(${ignore($has_reliable_cfg)}, "}")?)]
234 /// ```
235 #[unstable(feature = "float_exact_integer_constants", issue = "152466")]
236 pub const MIN_EXACT_INTEGER: $SignedBitsT = -Self::MAX_EXACT_INTEGER;
237
238 /// The mask of the bit used to encode the sign of an
239 #[doc = concat!("[`", stringify!($SelfT), "`].")]
240 ///
241 /// This bit is set when the sign is negative and unset when the sign is
242 /// positive.
243 /// If you only need to check whether a value is positive or negative,
244 /// [`is_sign_positive`] or [`is_sign_negative`] can be used.
245 ///
246 /// [`is_sign_positive`]: Self::is_sign_positive
247 /// [`is_sign_negative`]: Self::is_sign_negative
248 /// ```
249 /// #![feature(float_masks)]
250 $(#[doc = concat!("#![feature(", stringify!($feature), ")]")])?
251 $(#[doc = concat!("# #[cfg(", stringify!($has_reliable_cfg), ")] {")])?
252 #[doc = concat!("let sign_mask = ", stringify!($SelfT), "::SIGN_MASK;")]
253 #[doc = concat!("let a = 1.6552", stringify!($SelfT), ";")]
254 /// let a_bits = a.to_bits();
255 ///
256 /// assert_eq!(a_bits & sign_mask, 0x0);
257 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::from_bits(a_bits ^ sign_mask), -a);")]
258 #[doc = concat!("assert_eq!(sign_mask, (-0.0", stringify!($SelfT), ").to_bits());")]
259 $(${ignore($has_reliable_cfg)}
260 /// # }
261 )?
262 /// ```
263 #[unstable(feature = "float_masks", issue = "154064")]
264 pub const SIGN_MASK: $BitsT = $SIGN_MASK;
265
266 /// The mask of the bits used to encode the exponent of an
267 #[doc = concat!("[`", stringify!($SelfT), "`].")]
268 ///
269 /// Note that the exponent is stored as a biased value, with a bias of
270 #[doc = stringify!($exponent_bias)]
271 /// for
272 #[doc = concat!("`", stringify!($SelfT), "`.")]
273 ///
274 /// ```
275 /// #![feature(float_masks)]
276 $(#[doc = concat!("#![feature(", stringify!($feature), ")]")])?
277 $(#[doc = concat!("# #[cfg(", stringify!($has_reliable_cfg), ")] {")])?
278 #[doc = concat!("fn get_exp(a: ", stringify!($SelfT), ") -> ", stringify!($SignedBitsT), " {")]
279 #[doc = concat!(" let bias = ", $exponent_bias, ";")]
280 #[doc = concat!(" let biased = a.to_bits() & ", stringify!($SelfT), "::EXPONENT_MASK;")]
281 #[doc = concat!(" (biased >> (", stringify!($SelfT), "::MANTISSA_DIGITS - 1)).cast_signed() - bias")]
282 /// }
283 ///
284 /// assert_eq!(get_exp(0.5), -1);
285 /// assert_eq!(get_exp(1.0), 0);
286 /// assert_eq!(get_exp(2.0), 1);
287 /// assert_eq!(get_exp(4.0), 2);
288 $(${ignore($has_reliable_cfg)}
289 /// # }
290 )?
291 /// ```
292 #[unstable(feature = "float_masks", issue = "154064")]
293 pub const EXPONENT_MASK: $BitsT = $EXPONENT_MASK;
294
295 /// The mask of the bits used to encode the mantissa of an
296 #[doc = concat!("[`", stringify!($SelfT), "`].")]
297 ///
298 /// ```rust
299 /// #![feature(float_masks)]
300 $(#[doc = concat!("#![feature(", stringify!($feature), ")]")])?
301 $(#[doc = concat!("# #[cfg(", stringify!($has_reliable_cfg), ")] {")])?
302 #[doc = concat!("let mantissa_mask = ", stringify!($SelfT), "::MANTISSA_MASK;")]
303 ///
304 #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".to_bits() & mantissa_mask, 0x0);")]
305 #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".to_bits() & mantissa_mask, 0x0);")]
306 ///
307 /// // multiplying a finite value by a power of 2 doesn't change its mantissa
308 /// // unless the result or initial value is not normal.
309 #[doc = concat!("let a = 1.6552", stringify!($SelfT), ";")]
310 /// let b = 4.0 * a;
311 /// assert_eq!(a.to_bits() & mantissa_mask, b.to_bits() & mantissa_mask);
312 ///
313 /// // The maximum and minimum values have a saturated significand
314 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.to_bits() & ", stringify!($SelfT), "::MANTISSA_MASK, ", stringify!($SelfT), "::MANTISSA_MASK);")]
315 #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.to_bits() & ", stringify!($SelfT), "::MANTISSA_MASK, ", stringify!($SelfT), "::MANTISSA_MASK);")]
316 $(${ignore($has_reliable_cfg)}
317 /// # }
318 )?
319 /// ```
320 #[unstable(feature = "float_masks", issue = "154064")]
321 pub const MANTISSA_MASK: $BitsT = $MANTISSA_MASK;
322
323 /// Minimum representable positive value (min subnormal)
324 const TINY_BITS: $BitsT = 0x1;
325
326 /// Minimum representable negative value (min negative subnormal)
327 const NEG_TINY_BITS: $BitsT = Self::TINY_BITS | Self::SIGN_MASK;
328}