]>
Commit | Line | Data |
---|---|---|
f2b60f7d | 1 | //! Constants for the `f64` double-precision floating point type. |
ff7c6d11 | 2 | //! |
6a06907d | 3 | //! *[See also the `f64` primitive type][f64].* |
94b46f34 XL |
4 | //! |
5 | //! Mathematically significant numbers are provided in the `consts` sub-module. | |
74b04a01 | 6 | //! |
5869c6ff XL |
7 | //! For the constants defined directly in this module |
8 | //! (as distinct from those defined in the `consts` sub-module), | |
9 | //! new code should instead use the associated constants | |
10 | //! defined directly on the `f64` type. | |
1a4d82fc | 11 | |
85aaf69f | 12 | #![stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 13 | |
60c5eb7d | 14 | use crate::convert::FloatToInt; |
dc9dc135 XL |
15 | #[cfg(not(test))] |
16 | use crate::intrinsics; | |
48663c56 XL |
17 | use crate::mem; |
18 | use crate::num::FpCategory; | |
1a4d82fc | 19 | |
5bcae85e | 20 | /// The radix or base of the internal representation of `f64`. |
6a06907d | 21 | /// Use [`f64::RADIX`] instead. |
f9f354fc XL |
22 | /// |
23 | /// # Examples | |
24 | /// | |
25 | /// ```rust | |
26 | /// // deprecated way | |
5869c6ff | 27 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
28 | /// let r = std::f64::RADIX; |
29 | /// | |
30 | /// // intended way | |
31 | /// let r = f64::RADIX; | |
32 | /// ``` | |
c34b1796 | 33 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 34 | #[deprecated(since = "TBD", note = "replaced by the `RADIX` associated constant on `f64`")] |
74b04a01 | 35 | pub const RADIX: u32 = f64::RADIX; |
1a4d82fc | 36 | |
5bcae85e | 37 | /// Number of significant digits in base 2. |
6a06907d | 38 | /// Use [`f64::MANTISSA_DIGITS`] instead. |
f9f354fc XL |
39 | /// |
40 | /// # Examples | |
41 | /// | |
42 | /// ```rust | |
43 | /// // deprecated way | |
5869c6ff | 44 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
45 | /// let d = std::f64::MANTISSA_DIGITS; |
46 | /// | |
47 | /// // intended way | |
48 | /// let d = f64::MANTISSA_DIGITS; | |
49 | /// ``` | |
c34b1796 | 50 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 51 | #[deprecated( |
5869c6ff | 52 | since = "TBD", |
04454e1e | 53 | note = "replaced by the `MANTISSA_DIGITS` associated constant on `f64`" |
5869c6ff | 54 | )] |
74b04a01 | 55 | pub const MANTISSA_DIGITS: u32 = f64::MANTISSA_DIGITS; |
f9f354fc | 56 | |
5bcae85e | 57 | /// Approximate number of significant digits in base 10. |
6a06907d | 58 | /// Use [`f64::DIGITS`] instead. |
f9f354fc XL |
59 | /// |
60 | /// # Examples | |
61 | /// | |
62 | /// ```rust | |
63 | /// // deprecated way | |
5869c6ff | 64 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
65 | /// let d = std::f64::DIGITS; |
66 | /// | |
67 | /// // intended way | |
68 | /// let d = f64::DIGITS; | |
69 | /// ``` | |
c34b1796 | 70 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 71 | #[deprecated(since = "TBD", note = "replaced by the `DIGITS` associated constant on `f64`")] |
74b04a01 | 72 | pub const DIGITS: u32 = f64::DIGITS; |
1a4d82fc | 73 | |
94b46f34 | 74 | /// [Machine epsilon] value for `f64`. |
6a06907d | 75 | /// Use [`f64::EPSILON`] instead. |
94b46f34 | 76 | /// |
60c5eb7d | 77 | /// This is the difference between `1.0` and the next larger representable number. |
94b46f34 XL |
78 | /// |
79 | /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon | |
f9f354fc XL |
80 | /// |
81 | /// # Examples | |
82 | /// | |
83 | /// ```rust | |
84 | /// // deprecated way | |
5869c6ff | 85 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
86 | /// let e = std::f64::EPSILON; |
87 | /// | |
88 | /// // intended way | |
89 | /// let e = f64::EPSILON; | |
90 | /// ``` | |
85aaf69f | 91 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 92 | #[deprecated(since = "TBD", note = "replaced by the `EPSILON` associated constant on `f64`")] |
74b04a01 | 93 | pub const EPSILON: f64 = f64::EPSILON; |
1a4d82fc | 94 | |
5bcae85e | 95 | /// Smallest finite `f64` value. |
6a06907d | 96 | /// Use [`f64::MIN`] instead. |
f9f354fc XL |
97 | /// |
98 | /// # Examples | |
99 | /// | |
100 | /// ```rust | |
101 | /// // deprecated way | |
5869c6ff | 102 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
103 | /// let min = std::f64::MIN; |
104 | /// | |
105 | /// // intended way | |
106 | /// let min = f64::MIN; | |
107 | /// ``` | |
85aaf69f | 108 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 109 | #[deprecated(since = "TBD", note = "replaced by the `MIN` associated constant on `f64`")] |
74b04a01 | 110 | pub const MIN: f64 = f64::MIN; |
f9f354fc | 111 | |
5bcae85e | 112 | /// Smallest positive normal `f64` value. |
6a06907d | 113 | /// Use [`f64::MIN_POSITIVE`] instead. |
f9f354fc XL |
114 | /// |
115 | /// # Examples | |
116 | /// | |
117 | /// ```rust | |
118 | /// // deprecated way | |
5869c6ff | 119 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
120 | /// let min = std::f64::MIN_POSITIVE; |
121 | /// | |
122 | /// // intended way | |
123 | /// let min = f64::MIN_POSITIVE; | |
124 | /// ``` | |
85aaf69f | 125 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 126 | #[deprecated(since = "TBD", note = "replaced by the `MIN_POSITIVE` associated constant on `f64`")] |
74b04a01 | 127 | pub const MIN_POSITIVE: f64 = f64::MIN_POSITIVE; |
f9f354fc | 128 | |
5bcae85e | 129 | /// Largest finite `f64` value. |
6a06907d | 130 | /// Use [`f64::MAX`] instead. |
f9f354fc XL |
131 | /// |
132 | /// # Examples | |
133 | /// | |
134 | /// ```rust | |
135 | /// // deprecated way | |
5869c6ff | 136 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
137 | /// let max = std::f64::MAX; |
138 | /// | |
139 | /// // intended way | |
140 | /// let max = f64::MAX; | |
141 | /// ``` | |
85aaf69f | 142 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 143 | #[deprecated(since = "TBD", note = "replaced by the `MAX` associated constant on `f64`")] |
74b04a01 | 144 | pub const MAX: f64 = f64::MAX; |
85aaf69f | 145 | |
5bcae85e | 146 | /// One greater than the minimum possible normal power of 2 exponent. |
6a06907d | 147 | /// Use [`f64::MIN_EXP`] instead. |
f9f354fc XL |
148 | /// |
149 | /// # Examples | |
150 | /// | |
151 | /// ```rust | |
152 | /// // deprecated way | |
5869c6ff | 153 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
154 | /// let min = std::f64::MIN_EXP; |
155 | /// | |
156 | /// // intended way | |
157 | /// let min = f64::MIN_EXP; | |
158 | /// ``` | |
c34b1796 | 159 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 160 | #[deprecated(since = "TBD", note = "replaced by the `MIN_EXP` associated constant on `f64`")] |
74b04a01 | 161 | pub const MIN_EXP: i32 = f64::MIN_EXP; |
f9f354fc | 162 | |
5bcae85e | 163 | /// Maximum possible power of 2 exponent. |
6a06907d | 164 | /// Use [`f64::MAX_EXP`] instead. |
f9f354fc XL |
165 | /// |
166 | /// # Examples | |
167 | /// | |
168 | /// ```rust | |
169 | /// // deprecated way | |
5869c6ff | 170 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
171 | /// let max = std::f64::MAX_EXP; |
172 | /// | |
173 | /// // intended way | |
174 | /// let max = f64::MAX_EXP; | |
175 | /// ``` | |
c34b1796 | 176 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 177 | #[deprecated(since = "TBD", note = "replaced by the `MAX_EXP` associated constant on `f64`")] |
74b04a01 | 178 | pub const MAX_EXP: i32 = f64::MAX_EXP; |
1a4d82fc | 179 | |
5bcae85e | 180 | /// Minimum possible normal power of 10 exponent. |
6a06907d | 181 | /// Use [`f64::MIN_10_EXP`] instead. |
f9f354fc XL |
182 | /// |
183 | /// # Examples | |
184 | /// | |
185 | /// ```rust | |
186 | /// // deprecated way | |
5869c6ff | 187 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
188 | /// let min = std::f64::MIN_10_EXP; |
189 | /// | |
190 | /// // intended way | |
191 | /// let min = f64::MIN_10_EXP; | |
192 | /// ``` | |
c34b1796 | 193 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 194 | #[deprecated(since = "TBD", note = "replaced by the `MIN_10_EXP` associated constant on `f64`")] |
74b04a01 | 195 | pub const MIN_10_EXP: i32 = f64::MIN_10_EXP; |
f9f354fc | 196 | |
5bcae85e | 197 | /// Maximum possible power of 10 exponent. |
6a06907d | 198 | /// Use [`f64::MAX_10_EXP`] instead. |
f9f354fc XL |
199 | /// |
200 | /// # Examples | |
201 | /// | |
202 | /// ```rust | |
203 | /// // deprecated way | |
5869c6ff | 204 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
205 | /// let max = std::f64::MAX_10_EXP; |
206 | /// | |
207 | /// // intended way | |
208 | /// let max = f64::MAX_10_EXP; | |
209 | /// ``` | |
c34b1796 | 210 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 211 | #[deprecated(since = "TBD", note = "replaced by the `MAX_10_EXP` associated constant on `f64`")] |
74b04a01 | 212 | pub const MAX_10_EXP: i32 = f64::MAX_10_EXP; |
1a4d82fc | 213 | |
5bcae85e | 214 | /// Not a Number (NaN). |
6a06907d | 215 | /// Use [`f64::NAN`] instead. |
f9f354fc XL |
216 | /// |
217 | /// # Examples | |
218 | /// | |
219 | /// ```rust | |
220 | /// // deprecated way | |
5869c6ff | 221 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
222 | /// let nan = std::f64::NAN; |
223 | /// | |
224 | /// // intended way | |
225 | /// let nan = f64::NAN; | |
226 | /// ``` | |
85aaf69f | 227 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 228 | #[deprecated(since = "TBD", note = "replaced by the `NAN` associated constant on `f64`")] |
74b04a01 | 229 | pub const NAN: f64 = f64::NAN; |
f9f354fc | 230 | |
5bcae85e | 231 | /// Infinity (∞). |
6a06907d | 232 | /// Use [`f64::INFINITY`] instead. |
f9f354fc XL |
233 | /// |
234 | /// # Examples | |
235 | /// | |
236 | /// ```rust | |
237 | /// // deprecated way | |
5869c6ff | 238 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
239 | /// let inf = std::f64::INFINITY; |
240 | /// | |
241 | /// // intended way | |
242 | /// let inf = f64::INFINITY; | |
243 | /// ``` | |
85aaf69f | 244 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 245 | #[deprecated(since = "TBD", note = "replaced by the `INFINITY` associated constant on `f64`")] |
74b04a01 | 246 | pub const INFINITY: f64 = f64::INFINITY; |
f9f354fc | 247 | |
dfeec247 | 248 | /// Negative infinity (−∞). |
6a06907d | 249 | /// Use [`f64::NEG_INFINITY`] instead. |
f9f354fc XL |
250 | /// |
251 | /// # Examples | |
252 | /// | |
253 | /// ```rust | |
254 | /// // deprecated way | |
5869c6ff | 255 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
256 | /// let ninf = std::f64::NEG_INFINITY; |
257 | /// | |
258 | /// // intended way | |
259 | /// let ninf = f64::NEG_INFINITY; | |
260 | /// ``` | |
85aaf69f | 261 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 262 | #[deprecated(since = "TBD", note = "replaced by the `NEG_INFINITY` associated constant on `f64`")] |
74b04a01 | 263 | pub const NEG_INFINITY: f64 = f64::NEG_INFINITY; |
1a4d82fc | 264 | |
b039eaaf | 265 | /// Basic mathematical constants. |
c34b1796 | 266 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
267 | pub mod consts { |
268 | // FIXME: replace with mathematical constants from cmath. | |
269 | ||
5bcae85e | 270 | /// Archimedes' constant (π) |
c34b1796 | 271 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
272 | pub const PI: f64 = 3.14159265358979323846264338327950288_f64; |
273 | ||
60c5eb7d XL |
274 | /// The full circle constant (τ) |
275 | /// | |
276 | /// Equal to 2π. | |
3dfed10e | 277 | #[stable(feature = "tau_constant", since = "1.47.0")] |
60c5eb7d XL |
278 | pub const TAU: f64 = 6.28318530717958647692528676655900577_f64; |
279 | ||
5bcae85e | 280 | /// π/2 |
c34b1796 | 281 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
282 | pub const FRAC_PI_2: f64 = 1.57079632679489661923132169163975144_f64; |
283 | ||
5bcae85e | 284 | /// π/3 |
c34b1796 | 285 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
286 | pub const FRAC_PI_3: f64 = 1.04719755119659774615421446109316763_f64; |
287 | ||
5bcae85e | 288 | /// π/4 |
c34b1796 | 289 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
290 | pub const FRAC_PI_4: f64 = 0.785398163397448309615660845819875721_f64; |
291 | ||
5bcae85e | 292 | /// π/6 |
c34b1796 | 293 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
294 | pub const FRAC_PI_6: f64 = 0.52359877559829887307710723054658381_f64; |
295 | ||
5bcae85e | 296 | /// π/8 |
c34b1796 | 297 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
298 | pub const FRAC_PI_8: f64 = 0.39269908169872415480783042290993786_f64; |
299 | ||
5bcae85e | 300 | /// 1/π |
c34b1796 | 301 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
302 | pub const FRAC_1_PI: f64 = 0.318309886183790671537767526745028724_f64; |
303 | ||
5bcae85e | 304 | /// 2/π |
c34b1796 | 305 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
306 | pub const FRAC_2_PI: f64 = 0.636619772367581343075535053490057448_f64; |
307 | ||
5bcae85e | 308 | /// 2/sqrt(π) |
c34b1796 AL |
309 | #[stable(feature = "rust1", since = "1.0.0")] |
310 | pub const FRAC_2_SQRT_PI: f64 = 1.12837916709551257389615890312154517_f64; | |
311 | ||
5bcae85e | 312 | /// sqrt(2) |
c34b1796 AL |
313 | #[stable(feature = "rust1", since = "1.0.0")] |
314 | pub const SQRT_2: f64 = 1.41421356237309504880168872420969808_f64; | |
315 | ||
5bcae85e | 316 | /// 1/sqrt(2) |
c34b1796 AL |
317 | #[stable(feature = "rust1", since = "1.0.0")] |
318 | pub const FRAC_1_SQRT_2: f64 = 0.707106781186547524400844362104849039_f64; | |
319 | ||
5bcae85e | 320 | /// Euler's number (e) |
c34b1796 | 321 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
322 | pub const E: f64 = 2.71828182845904523536028747135266250_f64; |
323 | ||
94b46f34 | 324 | /// log<sub>2</sub>(10) |
74b04a01 | 325 | #[stable(feature = "extra_log_consts", since = "1.43.0")] |
94b46f34 XL |
326 | pub const LOG2_10: f64 = 3.32192809488736234787031942948939018_f64; |
327 | ||
5bcae85e | 328 | /// log<sub>2</sub>(e) |
c34b1796 | 329 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
330 | pub const LOG2_E: f64 = 1.44269504088896340735992468100189214_f64; |
331 | ||
94b46f34 | 332 | /// log<sub>10</sub>(2) |
74b04a01 | 333 | #[stable(feature = "extra_log_consts", since = "1.43.0")] |
94b46f34 XL |
334 | pub const LOG10_2: f64 = 0.301029995663981195213738894724493027_f64; |
335 | ||
5bcae85e | 336 | /// log<sub>10</sub>(e) |
c34b1796 | 337 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
338 | pub const LOG10_E: f64 = 0.434294481903251827651128918916605082_f64; |
339 | ||
5bcae85e | 340 | /// ln(2) |
c34b1796 | 341 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
342 | pub const LN_2: f64 = 0.693147180559945309417232121458176568_f64; |
343 | ||
5bcae85e | 344 | /// ln(10) |
c34b1796 | 345 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
346 | pub const LN_10: f64 = 2.30258509299404568401799145468436421_f64; |
347 | } | |
348 | ||
94b46f34 XL |
349 | #[cfg(not(test))] |
350 | impl f64 { | |
74b04a01 XL |
351 | /// The radix or base of the internal representation of `f64`. |
352 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
353 | pub const RADIX: u32 = 2; | |
354 | ||
355 | /// Number of significant digits in base 2. | |
356 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
357 | pub const MANTISSA_DIGITS: u32 = 53; | |
358 | /// Approximate number of significant digits in base 10. | |
359 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
360 | pub const DIGITS: u32 = 15; | |
361 | ||
362 | /// [Machine epsilon] value for `f64`. | |
363 | /// | |
364 | /// This is the difference between `1.0` and the next larger representable number. | |
365 | /// | |
366 | /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon | |
367 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
368 | pub const EPSILON: f64 = 2.2204460492503131e-16_f64; | |
369 | ||
370 | /// Smallest finite `f64` value. | |
371 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
372 | pub const MIN: f64 = -1.7976931348623157e+308_f64; | |
373 | /// Smallest positive normal `f64` value. | |
374 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
375 | pub const MIN_POSITIVE: f64 = 2.2250738585072014e-308_f64; | |
376 | /// Largest finite `f64` value. | |
377 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
378 | pub const MAX: f64 = 1.7976931348623157e+308_f64; | |
379 | ||
380 | /// One greater than the minimum possible normal power of 2 exponent. | |
381 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
382 | pub const MIN_EXP: i32 = -1021; | |
383 | /// Maximum possible power of 2 exponent. | |
384 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
385 | pub const MAX_EXP: i32 = 1024; | |
386 | ||
387 | /// Minimum possible normal power of 10 exponent. | |
388 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
389 | pub const MIN_10_EXP: i32 = -307; | |
390 | /// Maximum possible power of 10 exponent. | |
391 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
392 | pub const MAX_10_EXP: i32 = 308; | |
393 | ||
394 | /// Not a Number (NaN). | |
04454e1e | 395 | /// |
f2b60f7d | 396 | /// Note that IEEE 754 doesn't define just a single NaN value; |
04454e1e FG |
397 | /// a plethora of bit patterns are considered to be NaN. |
398 | /// Furthermore, the standard makes a difference | |
399 | /// between a "signaling" and a "quiet" NaN, | |
400 | /// and allows inspecting its "payload" (the unspecified bits in the bit pattern). | |
401 | /// This constant isn't guaranteed to equal to any specific NaN bitpattern, | |
402 | /// and the stability of its representation over Rust versions | |
403 | /// and target platforms isn't guaranteed. | |
74b04a01 XL |
404 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] |
405 | pub const NAN: f64 = 0.0_f64 / 0.0_f64; | |
406 | /// Infinity (∞). | |
407 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
408 | pub const INFINITY: f64 = 1.0_f64 / 0.0_f64; | |
f9f354fc | 409 | /// Negative infinity (−∞). |
74b04a01 XL |
410 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] |
411 | pub const NEG_INFINITY: f64 = -1.0_f64 / 0.0_f64; | |
412 | ||
04454e1e | 413 | /// Returns `true` if this value is NaN. |
83c7162d XL |
414 | /// |
415 | /// ``` | |
83c7162d XL |
416 | /// let nan = f64::NAN; |
417 | /// let f = 7.0_f64; | |
418 | /// | |
419 | /// assert!(nan.is_nan()); | |
420 | /// assert!(!f.is_nan()); | |
421 | /// ``` | |
c295e0f8 | 422 | #[must_use] |
83c7162d | 423 | #[stable(feature = "rust1", since = "1.0.0")] |
3dfed10e | 424 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
83c7162d | 425 | #[inline] |
3dfed10e | 426 | pub const fn is_nan(self) -> bool { |
94b46f34 XL |
427 | self != self |
428 | } | |
83c7162d | 429 | |
9c376795 | 430 | // FIXME(#50145): `abs` is publicly unavailable in core due to |
0731742a XL |
431 | // concerns about portability, so this implementation is for |
432 | // private use internally. | |
433 | #[inline] | |
3dfed10e | 434 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
3c0e092e | 435 | pub(crate) const fn abs_private(self) -> f64 { |
04454e1e FG |
436 | // SAFETY: This transmutation is fine. Probably. For the reasons std is using it. |
437 | unsafe { | |
438 | mem::transmute::<u64, f64>(mem::transmute::<f64, u64>(self) & 0x7fff_ffff_ffff_ffff) | |
439 | } | |
0731742a XL |
440 | } |
441 | ||
9fa01778 XL |
442 | /// Returns `true` if this value is positive infinity or negative infinity, and |
443 | /// `false` otherwise. | |
83c7162d XL |
444 | /// |
445 | /// ``` | |
83c7162d XL |
446 | /// let f = 7.0f64; |
447 | /// let inf = f64::INFINITY; | |
448 | /// let neg_inf = f64::NEG_INFINITY; | |
449 | /// let nan = f64::NAN; | |
450 | /// | |
451 | /// assert!(!f.is_infinite()); | |
452 | /// assert!(!nan.is_infinite()); | |
453 | /// | |
454 | /// assert!(inf.is_infinite()); | |
455 | /// assert!(neg_inf.is_infinite()); | |
456 | /// ``` | |
c295e0f8 | 457 | #[must_use] |
83c7162d | 458 | #[stable(feature = "rust1", since = "1.0.0")] |
3dfed10e | 459 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
83c7162d | 460 | #[inline] |
3dfed10e | 461 | pub const fn is_infinite(self) -> bool { |
04454e1e FG |
462 | // Getting clever with transmutation can result in incorrect answers on some FPUs |
463 | // FIXME: alter the Rust <-> Rust calling convention to prevent this problem. | |
464 | // See https://github.com/rust-lang/rust/issues/72327 | |
465 | (self == f64::INFINITY) | (self == f64::NEG_INFINITY) | |
94b46f34 | 466 | } |
83c7162d | 467 | |
04454e1e | 468 | /// Returns `true` if this number is neither infinite nor NaN. |
83c7162d XL |
469 | /// |
470 | /// ``` | |
83c7162d XL |
471 | /// let f = 7.0f64; |
472 | /// let inf: f64 = f64::INFINITY; | |
473 | /// let neg_inf: f64 = f64::NEG_INFINITY; | |
474 | /// let nan: f64 = f64::NAN; | |
475 | /// | |
476 | /// assert!(f.is_finite()); | |
477 | /// | |
478 | /// assert!(!nan.is_finite()); | |
479 | /// assert!(!inf.is_finite()); | |
480 | /// assert!(!neg_inf.is_finite()); | |
481 | /// ``` | |
c295e0f8 | 482 | #[must_use] |
83c7162d | 483 | #[stable(feature = "rust1", since = "1.0.0")] |
3dfed10e | 484 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
83c7162d | 485 | #[inline] |
3dfed10e | 486 | pub const fn is_finite(self) -> bool { |
0731742a XL |
487 | // There's no need to handle NaN separately: if self is NaN, |
488 | // the comparison is not true, exactly as desired. | |
f9f354fc | 489 | self.abs_private() < Self::INFINITY |
94b46f34 | 490 | } |
83c7162d | 491 | |
fc512014 XL |
492 | /// Returns `true` if the number is [subnormal]. |
493 | /// | |
494 | /// ``` | |
fc512014 XL |
495 | /// let min = f64::MIN_POSITIVE; // 2.2250738585072014e-308_f64 |
496 | /// let max = f64::MAX; | |
497 | /// let lower_than_min = 1.0e-308_f64; | |
498 | /// let zero = 0.0_f64; | |
499 | /// | |
500 | /// assert!(!min.is_subnormal()); | |
501 | /// assert!(!max.is_subnormal()); | |
502 | /// | |
503 | /// assert!(!zero.is_subnormal()); | |
504 | /// assert!(!f64::NAN.is_subnormal()); | |
505 | /// assert!(!f64::INFINITY.is_subnormal()); | |
506 | /// // Values between `0` and `min` are Subnormal. | |
507 | /// assert!(lower_than_min.is_subnormal()); | |
508 | /// ``` | |
509 | /// [subnormal]: https://en.wikipedia.org/wiki/Denormal_number | |
c295e0f8 | 510 | #[must_use] |
cdc7bbd5 | 511 | #[stable(feature = "is_subnormal", since = "1.53.0")] |
fc512014 XL |
512 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
513 | #[inline] | |
514 | pub const fn is_subnormal(self) -> bool { | |
515 | matches!(self.classify(), FpCategory::Subnormal) | |
516 | } | |
517 | ||
83c7162d | 518 | /// Returns `true` if the number is neither zero, infinite, |
04454e1e | 519 | /// [subnormal], or NaN. |
83c7162d XL |
520 | /// |
521 | /// ``` | |
83c7162d XL |
522 | /// let min = f64::MIN_POSITIVE; // 2.2250738585072014e-308f64 |
523 | /// let max = f64::MAX; | |
524 | /// let lower_than_min = 1.0e-308_f64; | |
525 | /// let zero = 0.0f64; | |
526 | /// | |
527 | /// assert!(min.is_normal()); | |
528 | /// assert!(max.is_normal()); | |
529 | /// | |
530 | /// assert!(!zero.is_normal()); | |
531 | /// assert!(!f64::NAN.is_normal()); | |
532 | /// assert!(!f64::INFINITY.is_normal()); | |
533 | /// // Values between `0` and `min` are Subnormal. | |
534 | /// assert!(!lower_than_min.is_normal()); | |
535 | /// ``` | |
536 | /// [subnormal]: https://en.wikipedia.org/wiki/Denormal_number | |
c295e0f8 | 537 | #[must_use] |
83c7162d | 538 | #[stable(feature = "rust1", since = "1.0.0")] |
3dfed10e | 539 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
83c7162d | 540 | #[inline] |
3dfed10e XL |
541 | pub const fn is_normal(self) -> bool { |
542 | matches!(self.classify(), FpCategory::Normal) | |
94b46f34 | 543 | } |
83c7162d XL |
544 | |
545 | /// Returns the floating point category of the number. If only one property | |
546 | /// is going to be tested, it is generally faster to use the specific | |
547 | /// predicate instead. | |
548 | /// | |
549 | /// ``` | |
550 | /// use std::num::FpCategory; | |
83c7162d XL |
551 | /// |
552 | /// let num = 12.4_f64; | |
553 | /// let inf = f64::INFINITY; | |
554 | /// | |
555 | /// assert_eq!(num.classify(), FpCategory::Normal); | |
556 | /// assert_eq!(inf.classify(), FpCategory::Infinite); | |
557 | /// ``` | |
558 | #[stable(feature = "rust1", since = "1.0.0")] | |
3dfed10e XL |
559 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
560 | pub const fn classify(self) -> FpCategory { | |
04454e1e FG |
561 | // A previous implementation tried to only use bitmask-based checks, |
562 | // using f64::to_bits to transmute the float to its bit repr and match on that. | |
563 | // Unfortunately, floating point numbers can be much worse than that. | |
564 | // This also needs to not result in recursive evaluations of f64::to_bits. | |
565 | // | |
566 | // On some processors, in some cases, LLVM will "helpfully" lower floating point ops, | |
567 | // in spite of a request for them using f32 and f64, to things like x87 operations. | |
568 | // These have an f64's mantissa, but can have a larger than normal exponent. | |
569 | // FIXME(jubilee): Using x87 operations is never necessary in order to function | |
570 | // on x86 processors for Rust-to-Rust calls, so this issue should not happen. | |
571 | // Code generation should be adjusted to use non-C calling conventions, avoiding this. | |
572 | // | |
573 | // Thus, a value may compare unequal to infinity, despite having a "full" exponent mask. | |
574 | // And it may not be NaN, as it can simply be an "overextended" finite value. | |
575 | if self.is_nan() { | |
576 | FpCategory::Nan | |
577 | } else { | |
578 | // However, std can't simply compare to zero to check for zero, either, | |
579 | // as correctness requires avoiding equality tests that may be Subnormal == -0.0 | |
580 | // because it may be wrong under "denormals are zero" and "flush to zero" modes. | |
581 | // Most of std's targets don't use those, but they are used for thumbv7neon. | |
582 | // So, this does use bitpattern matching for the rest. | |
583 | ||
584 | // SAFETY: f64 to u64 is fine. Usually. | |
585 | // If control flow has gotten this far, the value is definitely in one of the categories | |
586 | // that f64::partial_classify can correctly analyze. | |
587 | unsafe { f64::partial_classify(self) } | |
588 | } | |
589 | } | |
590 | ||
591 | // This doesn't actually return a right answer for NaN on purpose, | |
592 | // seeing as how it cannot correctly discern between a floating point NaN, | |
593 | // and some normal floating point numbers truncated from an x87 FPU. | |
594 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] | |
595 | const unsafe fn partial_classify(self) -> FpCategory { | |
94b46f34 XL |
596 | const EXP_MASK: u64 = 0x7ff0000000000000; |
597 | const MAN_MASK: u64 = 0x000fffffffffffff; | |
598 | ||
04454e1e FG |
599 | // SAFETY: The caller is not asking questions for which this will tell lies. |
600 | let b = unsafe { mem::transmute::<f64, u64>(self) }; | |
601 | match (b & MAN_MASK, b & EXP_MASK) { | |
602 | (0, EXP_MASK) => FpCategory::Infinite, | |
94b46f34 XL |
603 | (0, 0) => FpCategory::Zero, |
604 | (_, 0) => FpCategory::Subnormal, | |
04454e1e FG |
605 | _ => FpCategory::Normal, |
606 | } | |
607 | } | |
608 | ||
609 | // This operates on bits, and only bits, so it can ignore concerns about weird FPUs. | |
610 | // FIXME(jubilee): In a just world, this would be the entire impl for classify, | |
611 | // plus a transmute. We do not live in a just world, but we can make it more so. | |
612 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] | |
613 | const fn classify_bits(b: u64) -> FpCategory { | |
614 | const EXP_MASK: u64 = 0x7ff0000000000000; | |
615 | const MAN_MASK: u64 = 0x000fffffffffffff; | |
616 | ||
617 | match (b & MAN_MASK, b & EXP_MASK) { | |
94b46f34 XL |
618 | (0, EXP_MASK) => FpCategory::Infinite, |
619 | (_, EXP_MASK) => FpCategory::Nan, | |
04454e1e FG |
620 | (0, 0) => FpCategory::Zero, |
621 | (_, 0) => FpCategory::Subnormal, | |
94b46f34 XL |
622 | _ => FpCategory::Normal, |
623 | } | |
624 | } | |
83c7162d | 625 | |
04454e1e | 626 | /// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with |
f2b60f7d | 627 | /// positive sign bit and positive infinity. Note that IEEE 754 doesn't assign any |
04454e1e FG |
628 | /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that |
629 | /// the bit pattern of NaNs are conserved over arithmetic operations, the result of | |
630 | /// `is_sign_positive` on a NaN might produce an unexpected result in some cases. | |
631 | /// See [explanation of NaN as a special value](f32) for more info. | |
83c7162d XL |
632 | /// |
633 | /// ``` | |
634 | /// let f = 7.0_f64; | |
635 | /// let g = -7.0_f64; | |
636 | /// | |
637 | /// assert!(f.is_sign_positive()); | |
638 | /// assert!(!g.is_sign_positive()); | |
639 | /// ``` | |
c295e0f8 | 640 | #[must_use] |
83c7162d | 641 | #[stable(feature = "rust1", since = "1.0.0")] |
3dfed10e | 642 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
83c7162d | 643 | #[inline] |
3dfed10e | 644 | pub const fn is_sign_positive(self) -> bool { |
94b46f34 XL |
645 | !self.is_sign_negative() |
646 | } | |
83c7162d | 647 | |
c295e0f8 | 648 | #[must_use] |
83c7162d | 649 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 650 | #[deprecated(since = "1.0.0", note = "renamed to is_sign_positive")] |
83c7162d XL |
651 | #[inline] |
652 | #[doc(hidden)] | |
94b46f34 XL |
653 | pub fn is_positive(self) -> bool { |
654 | self.is_sign_positive() | |
655 | } | |
83c7162d | 656 | |
04454e1e | 657 | /// Returns `true` if `self` has a negative sign, including `-0.0`, NaNs with |
f2b60f7d | 658 | /// negative sign bit and negative infinity. Note that IEEE 754 doesn't assign any |
04454e1e FG |
659 | /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that |
660 | /// the bit pattern of NaNs are conserved over arithmetic operations, the result of | |
661 | /// `is_sign_negative` on a NaN might produce an unexpected result in some cases. | |
662 | /// See [explanation of NaN as a special value](f32) for more info. | |
83c7162d XL |
663 | /// |
664 | /// ``` | |
665 | /// let f = 7.0_f64; | |
666 | /// let g = -7.0_f64; | |
667 | /// | |
668 | /// assert!(!f.is_sign_negative()); | |
669 | /// assert!(g.is_sign_negative()); | |
670 | /// ``` | |
c295e0f8 | 671 | #[must_use] |
83c7162d | 672 | #[stable(feature = "rust1", since = "1.0.0")] |
3dfed10e | 673 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
83c7162d | 674 | #[inline] |
3dfed10e | 675 | pub const fn is_sign_negative(self) -> bool { |
04454e1e FG |
676 | // IEEE754 says: isSignMinus(x) is true if and only if x has negative sign. isSignMinus |
677 | // applies to zeros and NaNs as well. | |
678 | // SAFETY: This is just transmuting to get the sign bit, it's fine. | |
679 | unsafe { mem::transmute::<f64, u64>(self) & 0x8000_0000_0000_0000 != 0 } | |
94b46f34 | 680 | } |
83c7162d | 681 | |
c295e0f8 | 682 | #[must_use] |
83c7162d | 683 | #[stable(feature = "rust1", since = "1.0.0")] |
04454e1e | 684 | #[deprecated(since = "1.0.0", note = "renamed to is_sign_negative")] |
83c7162d XL |
685 | #[inline] |
686 | #[doc(hidden)] | |
94b46f34 XL |
687 | pub fn is_negative(self) -> bool { |
688 | self.is_sign_negative() | |
689 | } | |
83c7162d | 690 | |
f2b60f7d FG |
691 | /// Returns the least number greater than `self`. |
692 | /// | |
693 | /// Let `TINY` be the smallest representable positive `f64`. Then, | |
694 | /// - if `self.is_nan()`, this returns `self`; | |
695 | /// - if `self` is [`NEG_INFINITY`], this returns [`MIN`]; | |
696 | /// - if `self` is `-TINY`, this returns -0.0; | |
697 | /// - if `self` is -0.0 or +0.0, this returns `TINY`; | |
698 | /// - if `self` is [`MAX`] or [`INFINITY`], this returns [`INFINITY`]; | |
699 | /// - otherwise the unique least value greater than `self` is returned. | |
700 | /// | |
701 | /// The identity `x.next_up() == -(-x).next_down()` holds for all non-NaN `x`. When `x` | |
702 | /// is finite `x == x.next_up().next_down()` also holds. | |
703 | /// | |
704 | /// ```rust | |
705 | /// #![feature(float_next_up_down)] | |
706 | /// // f64::EPSILON is the difference between 1.0 and the next number up. | |
707 | /// assert_eq!(1.0f64.next_up(), 1.0 + f64::EPSILON); | |
708 | /// // But not for most numbers. | |
709 | /// assert!(0.1f64.next_up() < 0.1 + f64::EPSILON); | |
710 | /// assert_eq!(9007199254740992f64.next_up(), 9007199254740994.0); | |
711 | /// ``` | |
712 | /// | |
713 | /// [`NEG_INFINITY`]: Self::NEG_INFINITY | |
714 | /// [`INFINITY`]: Self::INFINITY | |
715 | /// [`MIN`]: Self::MIN | |
716 | /// [`MAX`]: Self::MAX | |
717 | #[unstable(feature = "float_next_up_down", issue = "91399")] | |
718 | #[rustc_const_unstable(feature = "float_next_up_down", issue = "91399")] | |
719 | pub const fn next_up(self) -> Self { | |
720 | // We must use strictly integer arithmetic to prevent denormals from | |
721 | // flushing to zero after an arithmetic operation on some platforms. | |
722 | const TINY_BITS: u64 = 0x1; // Smallest positive f64. | |
723 | const CLEAR_SIGN_MASK: u64 = 0x7fff_ffff_ffff_ffff; | |
724 | ||
725 | let bits = self.to_bits(); | |
726 | if self.is_nan() || bits == Self::INFINITY.to_bits() { | |
727 | return self; | |
728 | } | |
729 | ||
730 | let abs = bits & CLEAR_SIGN_MASK; | |
731 | let next_bits = if abs == 0 { | |
732 | TINY_BITS | |
733 | } else if bits == abs { | |
734 | bits + 1 | |
735 | } else { | |
736 | bits - 1 | |
737 | }; | |
738 | Self::from_bits(next_bits) | |
739 | } | |
740 | ||
741 | /// Returns the greatest number less than `self`. | |
742 | /// | |
743 | /// Let `TINY` be the smallest representable positive `f64`. Then, | |
744 | /// - if `self.is_nan()`, this returns `self`; | |
745 | /// - if `self` is [`INFINITY`], this returns [`MAX`]; | |
746 | /// - if `self` is `TINY`, this returns 0.0; | |
747 | /// - if `self` is -0.0 or +0.0, this returns `-TINY`; | |
748 | /// - if `self` is [`MIN`] or [`NEG_INFINITY`], this returns [`NEG_INFINITY`]; | |
749 | /// - otherwise the unique greatest value less than `self` is returned. | |
750 | /// | |
751 | /// The identity `x.next_down() == -(-x).next_up()` holds for all non-NaN `x`. When `x` | |
752 | /// is finite `x == x.next_down().next_up()` also holds. | |
753 | /// | |
754 | /// ```rust | |
755 | /// #![feature(float_next_up_down)] | |
756 | /// let x = 1.0f64; | |
757 | /// // Clamp value into range [0, 1). | |
758 | /// let clamped = x.clamp(0.0, 1.0f64.next_down()); | |
759 | /// assert!(clamped < 1.0); | |
760 | /// assert_eq!(clamped.next_up(), 1.0); | |
761 | /// ``` | |
762 | /// | |
763 | /// [`NEG_INFINITY`]: Self::NEG_INFINITY | |
764 | /// [`INFINITY`]: Self::INFINITY | |
765 | /// [`MIN`]: Self::MIN | |
766 | /// [`MAX`]: Self::MAX | |
767 | #[unstable(feature = "float_next_up_down", issue = "91399")] | |
768 | #[rustc_const_unstable(feature = "float_next_up_down", issue = "91399")] | |
769 | pub const fn next_down(self) -> Self { | |
770 | // We must use strictly integer arithmetic to prevent denormals from | |
771 | // flushing to zero after an arithmetic operation on some platforms. | |
772 | const NEG_TINY_BITS: u64 = 0x8000_0000_0000_0001; // Smallest (in magnitude) negative f64. | |
773 | const CLEAR_SIGN_MASK: u64 = 0x7fff_ffff_ffff_ffff; | |
774 | ||
775 | let bits = self.to_bits(); | |
776 | if self.is_nan() || bits == Self::NEG_INFINITY.to_bits() { | |
777 | return self; | |
778 | } | |
779 | ||
780 | let abs = bits & CLEAR_SIGN_MASK; | |
781 | let next_bits = if abs == 0 { | |
782 | NEG_TINY_BITS | |
783 | } else if bits == abs { | |
784 | bits - 1 | |
785 | } else { | |
786 | bits + 1 | |
787 | }; | |
788 | Self::from_bits(next_bits) | |
789 | } | |
790 | ||
83c7162d XL |
791 | /// Takes the reciprocal (inverse) of a number, `1/x`. |
792 | /// | |
793 | /// ``` | |
794 | /// let x = 2.0_f64; | |
e1599b0c | 795 | /// let abs_difference = (x.recip() - (1.0 / x)).abs(); |
83c7162d XL |
796 | /// |
797 | /// assert!(abs_difference < 1e-10); | |
798 | /// ``` | |
a2a8927a | 799 | #[must_use = "this returns the result of the operation, without modifying the original"] |
83c7162d XL |
800 | #[stable(feature = "rust1", since = "1.0.0")] |
801 | #[inline] | |
94b46f34 XL |
802 | pub fn recip(self) -> f64 { |
803 | 1.0 / self | |
804 | } | |
83c7162d XL |
805 | |
806 | /// Converts radians to degrees. | |
807 | /// | |
808 | /// ``` | |
ba9703b0 | 809 | /// let angle = std::f64::consts::PI; |
83c7162d XL |
810 | /// |
811 | /// let abs_difference = (angle.to_degrees() - 180.0).abs(); | |
812 | /// | |
813 | /// assert!(abs_difference < 1e-10); | |
814 | /// ``` | |
c295e0f8 XL |
815 | #[must_use = "this returns the result of the operation, \ |
816 | without modifying the original"] | |
83c7162d XL |
817 | #[stable(feature = "rust1", since = "1.0.0")] |
818 | #[inline] | |
94b46f34 XL |
819 | pub fn to_degrees(self) -> f64 { |
820 | // The division here is correctly rounded with respect to the true | |
821 | // value of 180/π. (This differs from f32, where a constant must be | |
822 | // used to ensure a correctly rounded result.) | |
823 | self * (180.0f64 / consts::PI) | |
824 | } | |
83c7162d XL |
825 | |
826 | /// Converts degrees to radians. | |
827 | /// | |
828 | /// ``` | |
83c7162d XL |
829 | /// let angle = 180.0_f64; |
830 | /// | |
ba9703b0 | 831 | /// let abs_difference = (angle.to_radians() - std::f64::consts::PI).abs(); |
83c7162d XL |
832 | /// |
833 | /// assert!(abs_difference < 1e-10); | |
834 | /// ``` | |
c295e0f8 XL |
835 | #[must_use = "this returns the result of the operation, \ |
836 | without modifying the original"] | |
83c7162d XL |
837 | #[stable(feature = "rust1", since = "1.0.0")] |
838 | #[inline] | |
94b46f34 XL |
839 | pub fn to_radians(self) -> f64 { |
840 | let value: f64 = consts::PI; | |
841 | self * (value / 180.0) | |
842 | } | |
83c7162d | 843 | |
04454e1e | 844 | /// Returns the maximum of the two numbers, ignoring NaN. |
83c7162d | 845 | /// |
04454e1e | 846 | /// If one of the arguments is NaN, then the other argument is returned. |
f2b60f7d | 847 | /// This follows the IEEE 754-2008 semantics for maxNum, except for handling of signaling NaNs; |
04454e1e FG |
848 | /// this function handles all NaNs the same way and avoids maxNum's problems with associativity. |
849 | /// This also matches the behavior of libm’s fmax. | |
3c0e092e | 850 | /// |
83c7162d XL |
851 | /// ``` |
852 | /// let x = 1.0_f64; | |
853 | /// let y = 2.0_f64; | |
854 | /// | |
855 | /// assert_eq!(x.max(y), y); | |
856 | /// ``` | |
a2a8927a | 857 | #[must_use = "this returns the result of the comparison, without modifying either input"] |
83c7162d XL |
858 | #[stable(feature = "rust1", since = "1.0.0")] |
859 | #[inline] | |
860 | pub fn max(self, other: f64) -> f64 { | |
dc9dc135 | 861 | intrinsics::maxnumf64(self, other) |
83c7162d XL |
862 | } |
863 | ||
04454e1e | 864 | /// Returns the minimum of the two numbers, ignoring NaN. |
83c7162d | 865 | /// |
04454e1e | 866 | /// If one of the arguments is NaN, then the other argument is returned. |
f2b60f7d | 867 | /// This follows the IEEE 754-2008 semantics for minNum, except for handling of signaling NaNs; |
04454e1e FG |
868 | /// this function handles all NaNs the same way and avoids minNum's problems with associativity. |
869 | /// This also matches the behavior of libm’s fmin. | |
3c0e092e | 870 | /// |
83c7162d XL |
871 | /// ``` |
872 | /// let x = 1.0_f64; | |
873 | /// let y = 2.0_f64; | |
874 | /// | |
875 | /// assert_eq!(x.min(y), x); | |
876 | /// ``` | |
a2a8927a | 877 | #[must_use = "this returns the result of the comparison, without modifying either input"] |
83c7162d XL |
878 | #[stable(feature = "rust1", since = "1.0.0")] |
879 | #[inline] | |
880 | pub fn min(self, other: f64) -> f64 { | |
dc9dc135 | 881 | intrinsics::minnumf64(self, other) |
83c7162d XL |
882 | } |
883 | ||
04454e1e | 884 | /// Returns the maximum of the two numbers, propagating NaN. |
3c0e092e XL |
885 | /// |
886 | /// This returns NaN when *either* argument is NaN, as opposed to | |
887 | /// [`f64::max`] which only returns NaN when *both* arguments are NaN. | |
888 | /// | |
889 | /// ``` | |
890 | /// #![feature(float_minimum_maximum)] | |
891 | /// let x = 1.0_f64; | |
892 | /// let y = 2.0_f64; | |
893 | /// | |
894 | /// assert_eq!(x.maximum(y), y); | |
895 | /// assert!(x.maximum(f64::NAN).is_nan()); | |
896 | /// ``` | |
897 | /// | |
898 | /// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the greater | |
899 | /// of the two numbers. For this operation, -0.0 is considered to be less than +0.0. | |
900 | /// Note that this follows the semantics specified in IEEE 754-2019. | |
04454e1e FG |
901 | /// |
902 | /// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN | |
903 | /// operand is conserved; see [explanation of NaN as a special value](f32) for more info. | |
a2a8927a | 904 | #[must_use = "this returns the result of the comparison, without modifying either input"] |
3c0e092e XL |
905 | #[unstable(feature = "float_minimum_maximum", issue = "91079")] |
906 | #[inline] | |
907 | pub fn maximum(self, other: f64) -> f64 { | |
908 | if self > other { | |
909 | self | |
910 | } else if other > self { | |
911 | other | |
912 | } else if self == other { | |
913 | if self.is_sign_positive() && other.is_sign_negative() { self } else { other } | |
914 | } else { | |
915 | self + other | |
916 | } | |
917 | } | |
918 | ||
04454e1e | 919 | /// Returns the minimum of the two numbers, propagating NaN. |
3c0e092e XL |
920 | /// |
921 | /// This returns NaN when *either* argument is NaN, as opposed to | |
922 | /// [`f64::min`] which only returns NaN when *both* arguments are NaN. | |
923 | /// | |
924 | /// ``` | |
925 | /// #![feature(float_minimum_maximum)] | |
926 | /// let x = 1.0_f64; | |
927 | /// let y = 2.0_f64; | |
928 | /// | |
929 | /// assert_eq!(x.minimum(y), x); | |
930 | /// assert!(x.minimum(f64::NAN).is_nan()); | |
931 | /// ``` | |
932 | /// | |
933 | /// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the lesser | |
934 | /// of the two numbers. For this operation, -0.0 is considered to be less than +0.0. | |
935 | /// Note that this follows the semantics specified in IEEE 754-2019. | |
04454e1e FG |
936 | /// |
937 | /// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN | |
938 | /// operand is conserved; see [explanation of NaN as a special value](f32) for more info. | |
a2a8927a | 939 | #[must_use = "this returns the result of the comparison, without modifying either input"] |
3c0e092e XL |
940 | #[unstable(feature = "float_minimum_maximum", issue = "91079")] |
941 | #[inline] | |
942 | pub fn minimum(self, other: f64) -> f64 { | |
943 | if self < other { | |
944 | self | |
945 | } else if other < self { | |
946 | other | |
947 | } else if self == other { | |
948 | if self.is_sign_negative() && other.is_sign_positive() { self } else { other } | |
949 | } else { | |
950 | self + other | |
951 | } | |
952 | } | |
953 | ||
49aad941 FG |
954 | /// Calculates the middle point of `self` and `rhs`. |
955 | /// | |
956 | /// This returns NaN when *either* argument is NaN or if a combination of | |
957 | /// +inf and -inf is provided as arguments. | |
958 | /// | |
959 | /// # Examples | |
960 | /// | |
961 | /// ``` | |
962 | /// #![feature(num_midpoint)] | |
963 | /// assert_eq!(1f64.midpoint(4.0), 2.5); | |
964 | /// assert_eq!((-5.5f64).midpoint(8.0), 1.25); | |
965 | /// ``` | |
966 | #[unstable(feature = "num_midpoint", issue = "110840")] | |
967 | pub fn midpoint(self, other: f64) -> f64 { | |
968 | const LO: f64 = f64::MIN_POSITIVE * 2.; | |
969 | const HI: f64 = f64::MAX / 2.; | |
970 | ||
971 | let (a, b) = (self, other); | |
972 | let abs_a = a.abs_private(); | |
973 | let abs_b = b.abs_private(); | |
974 | ||
975 | if abs_a <= HI && abs_b <= HI { | |
976 | // Overflow is impossible | |
977 | (a + b) / 2. | |
978 | } else if abs_a < LO { | |
979 | // Not safe to halve a | |
980 | a + (b / 2.) | |
981 | } else if abs_b < LO { | |
982 | // Not safe to halve b | |
983 | (a / 2.) + b | |
984 | } else { | |
985 | // Not safe to halve a and b | |
986 | (a / 2.) + (b / 2.) | |
987 | } | |
988 | } | |
989 | ||
60c5eb7d XL |
990 | /// Rounds toward zero and converts to any primitive integer type, |
991 | /// assuming that the value is finite and fits in that type. | |
992 | /// | |
993 | /// ``` | |
f9f354fc | 994 | /// let value = 4.6_f64; |
ba9703b0 | 995 | /// let rounded = unsafe { value.to_int_unchecked::<u16>() }; |
60c5eb7d XL |
996 | /// assert_eq!(rounded, 4); |
997 | /// | |
f9f354fc | 998 | /// let value = -128.9_f64; |
ba9703b0 XL |
999 | /// let rounded = unsafe { value.to_int_unchecked::<i8>() }; |
1000 | /// assert_eq!(rounded, i8::MIN); | |
60c5eb7d XL |
1001 | /// ``` |
1002 | /// | |
1003 | /// # Safety | |
1004 | /// | |
1005 | /// The value must: | |
1006 | /// | |
1007 | /// * Not be `NaN` | |
1008 | /// * Not be infinite | |
1009 | /// * Be representable in the return type `Int`, after truncating off its fractional part | |
c295e0f8 XL |
1010 | #[must_use = "this returns the result of the operation, \ |
1011 | without modifying the original"] | |
ba9703b0 | 1012 | #[stable(feature = "float_approx_unchecked_to", since = "1.44.0")] |
60c5eb7d | 1013 | #[inline] |
ba9703b0 | 1014 | pub unsafe fn to_int_unchecked<Int>(self) -> Int |
60c5eb7d XL |
1015 | where |
1016 | Self: FloatToInt<Int>, | |
1017 | { | |
f035d41b XL |
1018 | // SAFETY: the caller must uphold the safety contract for |
1019 | // `FloatToInt::to_int_unchecked`. | |
1020 | unsafe { FloatToInt::<Int>::to_int_unchecked(self) } | |
60c5eb7d XL |
1021 | } |
1022 | ||
83c7162d XL |
1023 | /// Raw transmutation to `u64`. |
1024 | /// | |
1025 | /// This is currently identical to `transmute::<f64, u64>(self)` on all platforms. | |
1026 | /// | |
17df50a5 XL |
1027 | /// See [`from_bits`](Self::from_bits) for some discussion of the |
1028 | /// portability of this operation (there are almost no issues). | |
83c7162d XL |
1029 | /// |
1030 | /// Note that this function is distinct from `as` casting, which attempts to | |
1031 | /// preserve the *numeric* value, and not the bitwise value. | |
1032 | /// | |
1033 | /// # Examples | |
1034 | /// | |
1035 | /// ``` | |
1036 | /// assert!((1f64).to_bits() != 1f64 as u64); // to_bits() is not casting! | |
1037 | /// assert_eq!((12.5f64).to_bits(), 0x4029000000000000); | |
1038 | /// | |
1039 | /// ``` | |
c295e0f8 XL |
1040 | #[must_use = "this returns the result of the operation, \ |
1041 | without modifying the original"] | |
83c7162d | 1042 | #[stable(feature = "float_bits_conv", since = "1.20.0")] |
3dfed10e | 1043 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
83c7162d | 1044 | #[inline] |
3dfed10e | 1045 | pub const fn to_bits(self) -> u64 { |
04454e1e FG |
1046 | // SAFETY: `u64` is a plain old datatype so we can always transmute to it. |
1047 | // ...sorta. | |
1048 | // | |
1049 | // See the SAFETY comment in f64::from_bits for more. | |
1050 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] | |
1051 | const fn ct_f64_to_u64(ct: f64) -> u64 { | |
1052 | match ct.classify() { | |
1053 | FpCategory::Nan => { | |
1054 | panic!("const-eval error: cannot use f64::to_bits on a NaN") | |
1055 | } | |
1056 | FpCategory::Subnormal => { | |
1057 | panic!("const-eval error: cannot use f64::to_bits on a subnormal number") | |
1058 | } | |
1059 | FpCategory::Infinite | FpCategory::Normal | FpCategory::Zero => { | |
1060 | // SAFETY: We have a normal floating point number. Now we transmute, i.e. do a bitcopy. | |
1061 | unsafe { mem::transmute::<f64, u64>(ct) } | |
1062 | } | |
1063 | } | |
1064 | } | |
f2b60f7d FG |
1065 | |
1066 | #[inline(always)] // See https://github.com/rust-lang/compiler-builtins/issues/491 | |
1067 | fn rt_f64_to_u64(rt: f64) -> u64 { | |
1068 | // SAFETY: `u64` is a plain old datatype so we can always... uh... | |
1069 | // ...look, just pretend you forgot what you just read. | |
1070 | // Stability concerns. | |
1071 | unsafe { mem::transmute::<f64, u64>(rt) } | |
1072 | } | |
04454e1e FG |
1073 | // SAFETY: We use internal implementations that either always work or fail at compile time. |
1074 | unsafe { intrinsics::const_eval_select((self,), ct_f64_to_u64, rt_f64_to_u64) } | |
83c7162d XL |
1075 | } |
1076 | ||
1077 | /// Raw transmutation from `u64`. | |
1078 | /// | |
1079 | /// This is currently identical to `transmute::<u64, f64>(v)` on all platforms. | |
1080 | /// It turns out this is incredibly portable, for two reasons: | |
1081 | /// | |
1082 | /// * Floats and Ints have the same endianness on all supported platforms. | |
f2b60f7d | 1083 | /// * IEEE 754 very precisely specifies the bit layout of floats. |
83c7162d | 1084 | /// |
f2b60f7d | 1085 | /// However there is one caveat: prior to the 2008 version of IEEE 754, how |
83c7162d XL |
1086 | /// to interpret the NaN signaling bit wasn't actually specified. Most platforms |
1087 | /// (notably x86 and ARM) picked the interpretation that was ultimately | |
1088 | /// standardized in 2008, but some didn't (notably MIPS). As a result, all | |
1089 | /// signaling NaNs on MIPS are quiet NaNs on x86, and vice-versa. | |
1090 | /// | |
1091 | /// Rather than trying to preserve signaling-ness cross-platform, this | |
3dfed10e | 1092 | /// implementation favors preserving the exact bits. This means that |
83c7162d XL |
1093 | /// any payloads encoded in NaNs will be preserved even if the result of |
1094 | /// this method is sent over the network from an x86 machine to a MIPS one. | |
1095 | /// | |
1096 | /// If the results of this method are only manipulated by the same | |
1097 | /// architecture that produced them, then there is no portability concern. | |
1098 | /// | |
1099 | /// If the input isn't NaN, then there is no portability concern. | |
1100 | /// | |
3dfed10e | 1101 | /// If you don't care about signaling-ness (very likely), then there is no |
83c7162d XL |
1102 | /// portability concern. |
1103 | /// | |
1104 | /// Note that this function is distinct from `as` casting, which attempts to | |
1105 | /// preserve the *numeric* value, and not the bitwise value. | |
1106 | /// | |
1107 | /// # Examples | |
1108 | /// | |
1109 | /// ``` | |
83c7162d | 1110 | /// let v = f64::from_bits(0x4029000000000000); |
416331ca | 1111 | /// assert_eq!(v, 12.5); |
83c7162d XL |
1112 | /// ``` |
1113 | #[stable(feature = "float_bits_conv", since = "1.20.0")] | |
3dfed10e | 1114 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
c295e0f8 | 1115 | #[must_use] |
83c7162d | 1116 | #[inline] |
3dfed10e | 1117 | pub const fn from_bits(v: u64) -> Self { |
94b46f34 | 1118 | // It turns out the safety issues with sNaN were overblown! Hooray! |
04454e1e FG |
1119 | // SAFETY: `u64` is a plain old datatype so we can always transmute from it |
1120 | // ...sorta. | |
1121 | // | |
1122 | // It turns out that at runtime, it is possible for a floating point number | |
1123 | // to be subject to floating point modes that alter nonzero subnormal numbers | |
1124 | // to zero on reads and writes, aka "denormals are zero" and "flush to zero". | |
1125 | // This is not a problem usually, but at least one tier2 platform for Rust | |
1126 | // actually exhibits an FTZ behavior by default: thumbv7neon | |
1127 | // aka "the Neon FPU in AArch32 state" | |
1128 | // | |
1129 | // Even with this, not all instructions exhibit the FTZ behaviors on thumbv7neon, | |
1130 | // so this should load the same bits if LLVM emits the "correct" instructions, | |
1131 | // but LLVM sometimes makes interesting choices about float optimization, | |
1132 | // and other FPUs may do similar. Thus, it is wise to indulge luxuriously in caution. | |
1133 | // | |
1134 | // In addition, on x86 targets with SSE or SSE2 disabled and the x87 FPU enabled, | |
1135 | // i.e. not soft-float, the way Rust does parameter passing can actually alter | |
1136 | // a number that is "not infinity" to have the same exponent as infinity, | |
1137 | // in a slightly unpredictable manner. | |
1138 | // | |
1139 | // And, of course evaluating to a NaN value is fairly nondeterministic. | |
1140 | // More precisely: when NaN should be returned is knowable, but which NaN? | |
1141 | // So far that's defined by a combination of LLVM and the CPU, not Rust. | |
1142 | // This function, however, allows observing the bitstring of a NaN, | |
1143 | // thus introspection on CTFE. | |
1144 | // | |
1145 | // In order to preserve, at least for the moment, const-to-runtime equivalence, | |
1146 | // reject any of these possible situations from happening. | |
1147 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] | |
1148 | const fn ct_u64_to_f64(ct: u64) -> f64 { | |
1149 | match f64::classify_bits(ct) { | |
1150 | FpCategory::Subnormal => { | |
1151 | panic!("const-eval error: cannot use f64::from_bits on a subnormal number") | |
1152 | } | |
1153 | FpCategory::Nan => { | |
1154 | panic!("const-eval error: cannot use f64::from_bits on NaN") | |
1155 | } | |
1156 | FpCategory::Infinite | FpCategory::Normal | FpCategory::Zero => { | |
1157 | // SAFETY: It's not a frumious number | |
1158 | unsafe { mem::transmute::<u64, f64>(ct) } | |
1159 | } | |
1160 | } | |
1161 | } | |
f2b60f7d FG |
1162 | |
1163 | #[inline(always)] // See https://github.com/rust-lang/compiler-builtins/issues/491 | |
1164 | fn rt_u64_to_f64(rt: u64) -> f64 { | |
1165 | // SAFETY: `u64` is a plain old datatype so we can always... uh... | |
1166 | // ...look, just pretend you forgot what you just read. | |
1167 | // Stability concerns. | |
1168 | unsafe { mem::transmute::<u64, f64>(rt) } | |
1169 | } | |
04454e1e FG |
1170 | // SAFETY: We use internal implementations that either always work or fail at compile time. |
1171 | unsafe { intrinsics::const_eval_select((v,), ct_u64_to_f64, rt_u64_to_f64) } | |
83c7162d | 1172 | } |
416331ca XL |
1173 | |
1174 | /// Return the memory representation of this floating point number as a byte array in | |
1175 | /// big-endian (network) byte order. | |
1176 | /// | |
04454e1e FG |
1177 | /// See [`from_bits`](Self::from_bits) for some discussion of the |
1178 | /// portability of this operation (there are almost no issues). | |
1179 | /// | |
416331ca XL |
1180 | /// # Examples |
1181 | /// | |
1182 | /// ``` | |
416331ca XL |
1183 | /// let bytes = 12.5f64.to_be_bytes(); |
1184 | /// assert_eq!(bytes, [0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]); | |
1185 | /// ``` | |
c295e0f8 XL |
1186 | #[must_use = "this returns the result of the operation, \ |
1187 | without modifying the original"] | |
e74abb32 | 1188 | #[stable(feature = "float_to_from_bytes", since = "1.40.0")] |
3dfed10e | 1189 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
416331ca | 1190 | #[inline] |
3dfed10e | 1191 | pub const fn to_be_bytes(self) -> [u8; 8] { |
416331ca XL |
1192 | self.to_bits().to_be_bytes() |
1193 | } | |
1194 | ||
1195 | /// Return the memory representation of this floating point number as a byte array in | |
1196 | /// little-endian byte order. | |
1197 | /// | |
04454e1e FG |
1198 | /// See [`from_bits`](Self::from_bits) for some discussion of the |
1199 | /// portability of this operation (there are almost no issues). | |
1200 | /// | |
416331ca XL |
1201 | /// # Examples |
1202 | /// | |
1203 | /// ``` | |
416331ca XL |
1204 | /// let bytes = 12.5f64.to_le_bytes(); |
1205 | /// assert_eq!(bytes, [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40]); | |
1206 | /// ``` | |
c295e0f8 XL |
1207 | #[must_use = "this returns the result of the operation, \ |
1208 | without modifying the original"] | |
e74abb32 | 1209 | #[stable(feature = "float_to_from_bytes", since = "1.40.0")] |
3dfed10e | 1210 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
416331ca | 1211 | #[inline] |
3dfed10e | 1212 | pub const fn to_le_bytes(self) -> [u8; 8] { |
416331ca XL |
1213 | self.to_bits().to_le_bytes() |
1214 | } | |
1215 | ||
1216 | /// Return the memory representation of this floating point number as a byte array in | |
1217 | /// native byte order. | |
1218 | /// | |
1219 | /// As the target platform's native endianness is used, portable code | |
1220 | /// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate, instead. | |
1221 | /// | |
6a06907d XL |
1222 | /// [`to_be_bytes`]: f64::to_be_bytes |
1223 | /// [`to_le_bytes`]: f64::to_le_bytes | |
416331ca | 1224 | /// |
04454e1e FG |
1225 | /// See [`from_bits`](Self::from_bits) for some discussion of the |
1226 | /// portability of this operation (there are almost no issues). | |
1227 | /// | |
416331ca XL |
1228 | /// # Examples |
1229 | /// | |
1230 | /// ``` | |
416331ca XL |
1231 | /// let bytes = 12.5f64.to_ne_bytes(); |
1232 | /// assert_eq!( | |
1233 | /// bytes, | |
1234 | /// if cfg!(target_endian = "big") { | |
1235 | /// [0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00] | |
1236 | /// } else { | |
1237 | /// [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40] | |
1238 | /// } | |
1239 | /// ); | |
1240 | /// ``` | |
c295e0f8 XL |
1241 | #[must_use = "this returns the result of the operation, \ |
1242 | without modifying the original"] | |
e74abb32 | 1243 | #[stable(feature = "float_to_from_bytes", since = "1.40.0")] |
3dfed10e | 1244 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
416331ca | 1245 | #[inline] |
3dfed10e | 1246 | pub const fn to_ne_bytes(self) -> [u8; 8] { |
416331ca XL |
1247 | self.to_bits().to_ne_bytes() |
1248 | } | |
1249 | ||
1250 | /// Create a floating point value from its representation as a byte array in big endian. | |
1251 | /// | |
04454e1e FG |
1252 | /// See [`from_bits`](Self::from_bits) for some discussion of the |
1253 | /// portability of this operation (there are almost no issues). | |
1254 | /// | |
416331ca XL |
1255 | /// # Examples |
1256 | /// | |
1257 | /// ``` | |
416331ca XL |
1258 | /// let value = f64::from_be_bytes([0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]); |
1259 | /// assert_eq!(value, 12.5); | |
1260 | /// ``` | |
e74abb32 | 1261 | #[stable(feature = "float_to_from_bytes", since = "1.40.0")] |
3dfed10e | 1262 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
c295e0f8 | 1263 | #[must_use] |
416331ca | 1264 | #[inline] |
3dfed10e | 1265 | pub const fn from_be_bytes(bytes: [u8; 8]) -> Self { |
416331ca XL |
1266 | Self::from_bits(u64::from_be_bytes(bytes)) |
1267 | } | |
1268 | ||
1269 | /// Create a floating point value from its representation as a byte array in little endian. | |
1270 | /// | |
04454e1e FG |
1271 | /// See [`from_bits`](Self::from_bits) for some discussion of the |
1272 | /// portability of this operation (there are almost no issues). | |
1273 | /// | |
416331ca XL |
1274 | /// # Examples |
1275 | /// | |
1276 | /// ``` | |
416331ca XL |
1277 | /// let value = f64::from_le_bytes([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40]); |
1278 | /// assert_eq!(value, 12.5); | |
1279 | /// ``` | |
e74abb32 | 1280 | #[stable(feature = "float_to_from_bytes", since = "1.40.0")] |
3dfed10e | 1281 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
c295e0f8 | 1282 | #[must_use] |
416331ca | 1283 | #[inline] |
3dfed10e | 1284 | pub const fn from_le_bytes(bytes: [u8; 8]) -> Self { |
416331ca XL |
1285 | Self::from_bits(u64::from_le_bytes(bytes)) |
1286 | } | |
1287 | ||
1288 | /// Create a floating point value from its representation as a byte array in native endian. | |
1289 | /// | |
1290 | /// As the target platform's native endianness is used, portable code | |
1291 | /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as | |
1292 | /// appropriate instead. | |
1293 | /// | |
6a06907d XL |
1294 | /// [`from_be_bytes`]: f64::from_be_bytes |
1295 | /// [`from_le_bytes`]: f64::from_le_bytes | |
416331ca | 1296 | /// |
04454e1e FG |
1297 | /// See [`from_bits`](Self::from_bits) for some discussion of the |
1298 | /// portability of this operation (there are almost no issues). | |
1299 | /// | |
416331ca XL |
1300 | /// # Examples |
1301 | /// | |
1302 | /// ``` | |
416331ca XL |
1303 | /// let value = f64::from_ne_bytes(if cfg!(target_endian = "big") { |
1304 | /// [0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00] | |
1305 | /// } else { | |
1306 | /// [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40] | |
1307 | /// }); | |
1308 | /// assert_eq!(value, 12.5); | |
1309 | /// ``` | |
e74abb32 | 1310 | #[stable(feature = "float_to_from_bytes", since = "1.40.0")] |
3dfed10e | 1311 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
c295e0f8 | 1312 | #[must_use] |
416331ca | 1313 | #[inline] |
3dfed10e | 1314 | pub const fn from_ne_bytes(bytes: [u8; 8]) -> Self { |
416331ca XL |
1315 | Self::from_bits(u64::from_ne_bytes(bytes)) |
1316 | } | |
f9f354fc | 1317 | |
5099ac24 FG |
1318 | /// Return the ordering between `self` and `other`. |
1319 | /// | |
f9f354fc XL |
1320 | /// Unlike the standard partial comparison between floating point numbers, |
1321 | /// this comparison always produces an ordering in accordance to | |
5099ac24 FG |
1322 | /// the `totalOrder` predicate as defined in the IEEE 754 (2008 revision) |
1323 | /// floating point standard. The values are ordered in the following sequence: | |
1324 | /// | |
1325 | /// - negative quiet NaN | |
1326 | /// - negative signaling NaN | |
1327 | /// - negative infinity | |
1328 | /// - negative numbers | |
1329 | /// - negative subnormal numbers | |
1330 | /// - negative zero | |
1331 | /// - positive zero | |
1332 | /// - positive subnormal numbers | |
1333 | /// - positive numbers | |
1334 | /// - positive infinity | |
1335 | /// - positive signaling NaN | |
1336 | /// - positive quiet NaN. | |
1337 | /// | |
1338 | /// The ordering established by this function does not always agree with the | |
1339 | /// [`PartialOrd`] and [`PartialEq`] implementations of `f64`. For example, | |
1340 | /// they consider negative and positive zero equal, while `total_cmp` | |
1341 | /// doesn't. | |
1342 | /// | |
1343 | /// The interpretation of the signaling NaN bit follows the definition in | |
1344 | /// the IEEE 754 standard, which may not match the interpretation by some of | |
1345 | /// the older, non-conformant (e.g. MIPS) hardware implementations. | |
29967ef6 | 1346 | /// |
f9f354fc | 1347 | /// # Example |
5099ac24 | 1348 | /// |
f9f354fc | 1349 | /// ``` |
f9f354fc XL |
1350 | /// struct GoodBoy { |
1351 | /// name: String, | |
1352 | /// weight: f64, | |
1353 | /// } | |
1354 | /// | |
1355 | /// let mut bois = vec![ | |
1356 | /// GoodBoy { name: "Pucci".to_owned(), weight: 0.1 }, | |
1357 | /// GoodBoy { name: "Woofer".to_owned(), weight: 99.0 }, | |
1358 | /// GoodBoy { name: "Yapper".to_owned(), weight: 10.0 }, | |
1359 | /// GoodBoy { name: "Chonk".to_owned(), weight: f64::INFINITY }, | |
1360 | /// GoodBoy { name: "Abs. Unit".to_owned(), weight: f64::NAN }, | |
1361 | /// GoodBoy { name: "Floaty".to_owned(), weight: -5.0 }, | |
1362 | /// ]; | |
1363 | /// | |
1364 | /// bois.sort_by(|a, b| a.weight.total_cmp(&b.weight)); | |
1365 | /// # assert!(bois.into_iter().map(|b| b.weight) | |
1366 | /// # .zip([-5.0, 0.1, 10.0, 99.0, f64::INFINITY, f64::NAN].iter()) | |
1367 | /// # .all(|(a, b)| a.to_bits() == b.to_bits())) | |
1368 | /// ``` | |
04454e1e | 1369 | #[stable(feature = "total_cmp", since = "1.62.0")] |
3c0e092e | 1370 | #[must_use] |
f9f354fc XL |
1371 | #[inline] |
1372 | pub fn total_cmp(&self, other: &Self) -> crate::cmp::Ordering { | |
1373 | let mut left = self.to_bits() as i64; | |
1374 | let mut right = other.to_bits() as i64; | |
1375 | ||
1376 | // In case of negatives, flip all the bits except the sign | |
1377 | // to achieve a similar layout as two's complement integers | |
1378 | // | |
1379 | // Why does this work? IEEE 754 floats consist of three fields: | |
1380 | // Sign bit, exponent and mantissa. The set of exponent and mantissa | |
1381 | // fields as a whole have the property that their bitwise order is | |
1382 | // equal to the numeric magnitude where the magnitude is defined. | |
1383 | // The magnitude is not normally defined on NaN values, but | |
1384 | // IEEE 754 totalOrder defines the NaN values also to follow the | |
1385 | // bitwise order. This leads to order explained in the doc comment. | |
1386 | // However, the representation of magnitude is the same for negative | |
1387 | // and positive numbers – only the sign bit is different. | |
1388 | // To easily compare the floats as signed integers, we need to | |
1389 | // flip the exponent and mantissa bits in case of negative numbers. | |
1390 | // We effectively convert the numbers to "two's complement" form. | |
1391 | // | |
1392 | // To do the flipping, we construct a mask and XOR against it. | |
1393 | // We branchlessly calculate an "all-ones except for the sign bit" | |
1394 | // mask from negative-signed values: right shifting sign-extends | |
1395 | // the integer, so we "fill" the mask with sign bits, and then | |
1396 | // convert to unsigned to push one more zero bit. | |
1397 | // On positive values, the mask is all zeros, so it's a no-op. | |
1398 | left ^= (((left >> 63) as u64) >> 1) as i64; | |
1399 | right ^= (((right >> 63) as u64) >> 1) as i64; | |
1400 | ||
1401 | left.cmp(&right) | |
1402 | } | |
fc512014 XL |
1403 | |
1404 | /// Restrict a value to a certain interval unless it is NaN. | |
1405 | /// | |
1406 | /// Returns `max` if `self` is greater than `max`, and `min` if `self` is | |
1407 | /// less than `min`. Otherwise this returns `self`. | |
1408 | /// | |
1409 | /// Note that this function returns NaN if the initial value was NaN as | |
1410 | /// well. | |
1411 | /// | |
1412 | /// # Panics | |
1413 | /// | |
1414 | /// Panics if `min > max`, `min` is NaN, or `max` is NaN. | |
1415 | /// | |
1416 | /// # Examples | |
1417 | /// | |
1418 | /// ``` | |
1419 | /// assert!((-3.0f64).clamp(-2.0, 1.0) == -2.0); | |
1420 | /// assert!((0.0f64).clamp(-2.0, 1.0) == 0.0); | |
1421 | /// assert!((2.0f64).clamp(-2.0, 1.0) == 1.0); | |
1422 | /// assert!((f64::NAN).clamp(-2.0, 1.0).is_nan()); | |
1423 | /// ``` | |
1424 | #[must_use = "method returns a new number and does not mutate the original value"] | |
1425 | #[stable(feature = "clamp", since = "1.50.0")] | |
1426 | #[inline] | |
f2b60f7d | 1427 | pub fn clamp(mut self, min: f64, max: f64) -> f64 { |
353b0b11 | 1428 | assert!(min <= max, "min > max, or either was NaN. min = {min:?}, max = {max:?}"); |
f2b60f7d FG |
1429 | if self < min { |
1430 | self = min; | |
fc512014 | 1431 | } |
f2b60f7d FG |
1432 | if self > max { |
1433 | self = max; | |
fc512014 | 1434 | } |
f2b60f7d | 1435 | self |
fc512014 | 1436 | } |
83c7162d | 1437 | } |