]>
Commit | Line | Data |
---|---|---|
5869c6ff | 1 | //! Constants specific to 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")] |
5869c6ff | 34 | #[rustc_deprecated(since = "TBD", reason = "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")] |
5869c6ff XL |
51 | #[rustc_deprecated( |
52 | since = "TBD", | |
53 | reason = "replaced by the `MANTISSA_DIGITS` associated constant on `f64`" | |
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")] |
5869c6ff | 71 | #[rustc_deprecated(since = "TBD", reason = "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")] |
5869c6ff XL |
92 | #[rustc_deprecated( |
93 | since = "TBD", | |
94 | reason = "replaced by the `EPSILON` associated constant on `f64`" | |
95 | )] | |
74b04a01 | 96 | pub const EPSILON: f64 = f64::EPSILON; |
1a4d82fc | 97 | |
5bcae85e | 98 | /// Smallest finite `f64` value. |
6a06907d | 99 | /// Use [`f64::MIN`] instead. |
f9f354fc XL |
100 | /// |
101 | /// # Examples | |
102 | /// | |
103 | /// ```rust | |
104 | /// // deprecated way | |
5869c6ff | 105 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
106 | /// let min = std::f64::MIN; |
107 | /// | |
108 | /// // intended way | |
109 | /// let min = f64::MIN; | |
110 | /// ``` | |
85aaf69f | 111 | #[stable(feature = "rust1", since = "1.0.0")] |
5869c6ff | 112 | #[rustc_deprecated(since = "TBD", reason = "replaced by the `MIN` associated constant on `f64`")] |
74b04a01 | 113 | pub const MIN: f64 = f64::MIN; |
f9f354fc | 114 | |
5bcae85e | 115 | /// Smallest positive normal `f64` value. |
6a06907d | 116 | /// Use [`f64::MIN_POSITIVE`] instead. |
f9f354fc XL |
117 | /// |
118 | /// # Examples | |
119 | /// | |
120 | /// ```rust | |
121 | /// // deprecated way | |
5869c6ff | 122 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
123 | /// let min = std::f64::MIN_POSITIVE; |
124 | /// | |
125 | /// // intended way | |
126 | /// let min = f64::MIN_POSITIVE; | |
127 | /// ``` | |
85aaf69f | 128 | #[stable(feature = "rust1", since = "1.0.0")] |
5869c6ff XL |
129 | #[rustc_deprecated( |
130 | since = "TBD", | |
131 | reason = "replaced by the `MIN_POSITIVE` associated constant on `f64`" | |
132 | )] | |
74b04a01 | 133 | pub const MIN_POSITIVE: f64 = f64::MIN_POSITIVE; |
f9f354fc | 134 | |
5bcae85e | 135 | /// Largest finite `f64` value. |
6a06907d | 136 | /// Use [`f64::MAX`] instead. |
f9f354fc XL |
137 | /// |
138 | /// # Examples | |
139 | /// | |
140 | /// ```rust | |
141 | /// // deprecated way | |
5869c6ff | 142 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
143 | /// let max = std::f64::MAX; |
144 | /// | |
145 | /// // intended way | |
146 | /// let max = f64::MAX; | |
147 | /// ``` | |
85aaf69f | 148 | #[stable(feature = "rust1", since = "1.0.0")] |
5869c6ff | 149 | #[rustc_deprecated(since = "TBD", reason = "replaced by the `MAX` associated constant on `f64`")] |
74b04a01 | 150 | pub const MAX: f64 = f64::MAX; |
85aaf69f | 151 | |
5bcae85e | 152 | /// One greater than the minimum possible normal power of 2 exponent. |
6a06907d | 153 | /// Use [`f64::MIN_EXP`] instead. |
f9f354fc XL |
154 | /// |
155 | /// # Examples | |
156 | /// | |
157 | /// ```rust | |
158 | /// // deprecated way | |
5869c6ff | 159 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
160 | /// let min = std::f64::MIN_EXP; |
161 | /// | |
162 | /// // intended way | |
163 | /// let min = f64::MIN_EXP; | |
164 | /// ``` | |
c34b1796 | 165 | #[stable(feature = "rust1", since = "1.0.0")] |
5869c6ff XL |
166 | #[rustc_deprecated( |
167 | since = "TBD", | |
168 | reason = "replaced by the `MIN_EXP` associated constant on `f64`" | |
169 | )] | |
74b04a01 | 170 | pub const MIN_EXP: i32 = f64::MIN_EXP; |
f9f354fc | 171 | |
5bcae85e | 172 | /// Maximum possible power of 2 exponent. |
6a06907d | 173 | /// Use [`f64::MAX_EXP`] instead. |
f9f354fc XL |
174 | /// |
175 | /// # Examples | |
176 | /// | |
177 | /// ```rust | |
178 | /// // deprecated way | |
5869c6ff | 179 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
180 | /// let max = std::f64::MAX_EXP; |
181 | /// | |
182 | /// // intended way | |
183 | /// let max = f64::MAX_EXP; | |
184 | /// ``` | |
c34b1796 | 185 | #[stable(feature = "rust1", since = "1.0.0")] |
5869c6ff XL |
186 | #[rustc_deprecated( |
187 | since = "TBD", | |
188 | reason = "replaced by the `MAX_EXP` associated constant on `f64`" | |
189 | )] | |
74b04a01 | 190 | pub const MAX_EXP: i32 = f64::MAX_EXP; |
1a4d82fc | 191 | |
5bcae85e | 192 | /// Minimum possible normal power of 10 exponent. |
6a06907d | 193 | /// Use [`f64::MIN_10_EXP`] instead. |
f9f354fc XL |
194 | /// |
195 | /// # Examples | |
196 | /// | |
197 | /// ```rust | |
198 | /// // deprecated way | |
5869c6ff | 199 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
200 | /// let min = std::f64::MIN_10_EXP; |
201 | /// | |
202 | /// // intended way | |
203 | /// let min = f64::MIN_10_EXP; | |
204 | /// ``` | |
c34b1796 | 205 | #[stable(feature = "rust1", since = "1.0.0")] |
5869c6ff XL |
206 | #[rustc_deprecated( |
207 | since = "TBD", | |
208 | reason = "replaced by the `MIN_10_EXP` associated constant on `f64`" | |
209 | )] | |
74b04a01 | 210 | pub const MIN_10_EXP: i32 = f64::MIN_10_EXP; |
f9f354fc | 211 | |
5bcae85e | 212 | /// Maximum possible power of 10 exponent. |
6a06907d | 213 | /// Use [`f64::MAX_10_EXP`] instead. |
f9f354fc XL |
214 | /// |
215 | /// # Examples | |
216 | /// | |
217 | /// ```rust | |
218 | /// // deprecated way | |
5869c6ff | 219 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
220 | /// let max = std::f64::MAX_10_EXP; |
221 | /// | |
222 | /// // intended way | |
223 | /// let max = f64::MAX_10_EXP; | |
224 | /// ``` | |
c34b1796 | 225 | #[stable(feature = "rust1", since = "1.0.0")] |
5869c6ff XL |
226 | #[rustc_deprecated( |
227 | since = "TBD", | |
228 | reason = "replaced by the `MAX_10_EXP` associated constant on `f64`" | |
229 | )] | |
74b04a01 | 230 | pub const MAX_10_EXP: i32 = f64::MAX_10_EXP; |
1a4d82fc | 231 | |
5bcae85e | 232 | /// Not a Number (NaN). |
6a06907d | 233 | /// Use [`f64::NAN`] instead. |
f9f354fc XL |
234 | /// |
235 | /// # Examples | |
236 | /// | |
237 | /// ```rust | |
238 | /// // deprecated way | |
5869c6ff | 239 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
240 | /// let nan = std::f64::NAN; |
241 | /// | |
242 | /// // intended way | |
243 | /// let nan = f64::NAN; | |
244 | /// ``` | |
85aaf69f | 245 | #[stable(feature = "rust1", since = "1.0.0")] |
5869c6ff | 246 | #[rustc_deprecated(since = "TBD", reason = "replaced by the `NAN` associated constant on `f64`")] |
74b04a01 | 247 | pub const NAN: f64 = f64::NAN; |
f9f354fc | 248 | |
5bcae85e | 249 | /// Infinity (∞). |
6a06907d | 250 | /// Use [`f64::INFINITY`] instead. |
f9f354fc XL |
251 | /// |
252 | /// # Examples | |
253 | /// | |
254 | /// ```rust | |
255 | /// // deprecated way | |
5869c6ff | 256 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
257 | /// let inf = std::f64::INFINITY; |
258 | /// | |
259 | /// // intended way | |
260 | /// let inf = f64::INFINITY; | |
261 | /// ``` | |
85aaf69f | 262 | #[stable(feature = "rust1", since = "1.0.0")] |
5869c6ff XL |
263 | #[rustc_deprecated( |
264 | since = "TBD", | |
265 | reason = "replaced by the `INFINITY` associated constant on `f64`" | |
266 | )] | |
74b04a01 | 267 | pub const INFINITY: f64 = f64::INFINITY; |
f9f354fc | 268 | |
dfeec247 | 269 | /// Negative infinity (−∞). |
6a06907d | 270 | /// Use [`f64::NEG_INFINITY`] instead. |
f9f354fc XL |
271 | /// |
272 | /// # Examples | |
273 | /// | |
274 | /// ```rust | |
275 | /// // deprecated way | |
5869c6ff | 276 | /// # #[allow(deprecated, deprecated_in_future)] |
f9f354fc XL |
277 | /// let ninf = std::f64::NEG_INFINITY; |
278 | /// | |
279 | /// // intended way | |
280 | /// let ninf = f64::NEG_INFINITY; | |
281 | /// ``` | |
85aaf69f | 282 | #[stable(feature = "rust1", since = "1.0.0")] |
5869c6ff XL |
283 | #[rustc_deprecated( |
284 | since = "TBD", | |
285 | reason = "replaced by the `NEG_INFINITY` associated constant on `f64`" | |
286 | )] | |
74b04a01 | 287 | pub const NEG_INFINITY: f64 = f64::NEG_INFINITY; |
1a4d82fc | 288 | |
b039eaaf | 289 | /// Basic mathematical constants. |
c34b1796 | 290 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
291 | pub mod consts { |
292 | // FIXME: replace with mathematical constants from cmath. | |
293 | ||
5bcae85e | 294 | /// Archimedes' constant (π) |
c34b1796 | 295 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
296 | pub const PI: f64 = 3.14159265358979323846264338327950288_f64; |
297 | ||
60c5eb7d XL |
298 | /// The full circle constant (τ) |
299 | /// | |
300 | /// Equal to 2π. | |
3dfed10e | 301 | #[stable(feature = "tau_constant", since = "1.47.0")] |
60c5eb7d XL |
302 | pub const TAU: f64 = 6.28318530717958647692528676655900577_f64; |
303 | ||
5bcae85e | 304 | /// π/2 |
c34b1796 | 305 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
306 | pub const FRAC_PI_2: f64 = 1.57079632679489661923132169163975144_f64; |
307 | ||
5bcae85e | 308 | /// π/3 |
c34b1796 | 309 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
310 | pub const FRAC_PI_3: f64 = 1.04719755119659774615421446109316763_f64; |
311 | ||
5bcae85e | 312 | /// π/4 |
c34b1796 | 313 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
314 | pub const FRAC_PI_4: f64 = 0.785398163397448309615660845819875721_f64; |
315 | ||
5bcae85e | 316 | /// π/6 |
c34b1796 | 317 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
318 | pub const FRAC_PI_6: f64 = 0.52359877559829887307710723054658381_f64; |
319 | ||
5bcae85e | 320 | /// π/8 |
c34b1796 | 321 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
322 | pub const FRAC_PI_8: f64 = 0.39269908169872415480783042290993786_f64; |
323 | ||
5bcae85e | 324 | /// 1/π |
c34b1796 | 325 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
326 | pub const FRAC_1_PI: f64 = 0.318309886183790671537767526745028724_f64; |
327 | ||
5bcae85e | 328 | /// 2/π |
c34b1796 | 329 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
330 | pub const FRAC_2_PI: f64 = 0.636619772367581343075535053490057448_f64; |
331 | ||
5bcae85e | 332 | /// 2/sqrt(π) |
c34b1796 AL |
333 | #[stable(feature = "rust1", since = "1.0.0")] |
334 | pub const FRAC_2_SQRT_PI: f64 = 1.12837916709551257389615890312154517_f64; | |
335 | ||
5bcae85e | 336 | /// sqrt(2) |
c34b1796 AL |
337 | #[stable(feature = "rust1", since = "1.0.0")] |
338 | pub const SQRT_2: f64 = 1.41421356237309504880168872420969808_f64; | |
339 | ||
5bcae85e | 340 | /// 1/sqrt(2) |
c34b1796 AL |
341 | #[stable(feature = "rust1", since = "1.0.0")] |
342 | pub const FRAC_1_SQRT_2: f64 = 0.707106781186547524400844362104849039_f64; | |
343 | ||
5bcae85e | 344 | /// Euler's number (e) |
c34b1796 | 345 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
346 | pub const E: f64 = 2.71828182845904523536028747135266250_f64; |
347 | ||
94b46f34 | 348 | /// log<sub>2</sub>(10) |
74b04a01 | 349 | #[stable(feature = "extra_log_consts", since = "1.43.0")] |
94b46f34 XL |
350 | pub const LOG2_10: f64 = 3.32192809488736234787031942948939018_f64; |
351 | ||
5bcae85e | 352 | /// log<sub>2</sub>(e) |
c34b1796 | 353 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
354 | pub const LOG2_E: f64 = 1.44269504088896340735992468100189214_f64; |
355 | ||
94b46f34 | 356 | /// log<sub>10</sub>(2) |
74b04a01 | 357 | #[stable(feature = "extra_log_consts", since = "1.43.0")] |
94b46f34 XL |
358 | pub const LOG10_2: f64 = 0.301029995663981195213738894724493027_f64; |
359 | ||
5bcae85e | 360 | /// log<sub>10</sub>(e) |
c34b1796 | 361 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
362 | pub const LOG10_E: f64 = 0.434294481903251827651128918916605082_f64; |
363 | ||
5bcae85e | 364 | /// ln(2) |
c34b1796 | 365 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
366 | pub const LN_2: f64 = 0.693147180559945309417232121458176568_f64; |
367 | ||
5bcae85e | 368 | /// ln(10) |
c34b1796 | 369 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
370 | pub const LN_10: f64 = 2.30258509299404568401799145468436421_f64; |
371 | } | |
372 | ||
94b46f34 XL |
373 | #[lang = "f64"] |
374 | #[cfg(not(test))] | |
375 | impl f64 { | |
74b04a01 XL |
376 | /// The radix or base of the internal representation of `f64`. |
377 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
378 | pub const RADIX: u32 = 2; | |
379 | ||
380 | /// Number of significant digits in base 2. | |
381 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
382 | pub const MANTISSA_DIGITS: u32 = 53; | |
383 | /// Approximate number of significant digits in base 10. | |
384 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
385 | pub const DIGITS: u32 = 15; | |
386 | ||
387 | /// [Machine epsilon] value for `f64`. | |
388 | /// | |
389 | /// This is the difference between `1.0` and the next larger representable number. | |
390 | /// | |
391 | /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon | |
392 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
393 | pub const EPSILON: f64 = 2.2204460492503131e-16_f64; | |
394 | ||
395 | /// Smallest finite `f64` value. | |
396 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
397 | pub const MIN: f64 = -1.7976931348623157e+308_f64; | |
398 | /// Smallest positive normal `f64` value. | |
399 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
400 | pub const MIN_POSITIVE: f64 = 2.2250738585072014e-308_f64; | |
401 | /// Largest finite `f64` value. | |
402 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
403 | pub const MAX: f64 = 1.7976931348623157e+308_f64; | |
404 | ||
405 | /// One greater than the minimum possible normal power of 2 exponent. | |
406 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
407 | pub const MIN_EXP: i32 = -1021; | |
408 | /// Maximum possible power of 2 exponent. | |
409 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
410 | pub const MAX_EXP: i32 = 1024; | |
411 | ||
412 | /// Minimum possible normal power of 10 exponent. | |
413 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
414 | pub const MIN_10_EXP: i32 = -307; | |
415 | /// Maximum possible power of 10 exponent. | |
416 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
417 | pub const MAX_10_EXP: i32 = 308; | |
418 | ||
419 | /// Not a Number (NaN). | |
420 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
421 | pub const NAN: f64 = 0.0_f64 / 0.0_f64; | |
422 | /// Infinity (∞). | |
423 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
424 | pub const INFINITY: f64 = 1.0_f64 / 0.0_f64; | |
f9f354fc | 425 | /// Negative infinity (−∞). |
74b04a01 XL |
426 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] |
427 | pub const NEG_INFINITY: f64 = -1.0_f64 / 0.0_f64; | |
428 | ||
9fa01778 | 429 | /// Returns `true` if this value is `NaN`. |
83c7162d XL |
430 | /// |
431 | /// ``` | |
83c7162d XL |
432 | /// let nan = f64::NAN; |
433 | /// let f = 7.0_f64; | |
434 | /// | |
435 | /// assert!(nan.is_nan()); | |
436 | /// assert!(!f.is_nan()); | |
437 | /// ``` | |
438 | #[stable(feature = "rust1", since = "1.0.0")] | |
3dfed10e | 439 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
83c7162d | 440 | #[inline] |
3dfed10e | 441 | pub const fn is_nan(self) -> bool { |
94b46f34 XL |
442 | self != self |
443 | } | |
83c7162d | 444 | |
0731742a XL |
445 | // FIXME(#50145): `abs` is publicly unavailable in libcore due to |
446 | // concerns about portability, so this implementation is for | |
447 | // private use internally. | |
448 | #[inline] | |
3dfed10e XL |
449 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
450 | const fn abs_private(self) -> f64 { | |
0731742a XL |
451 | f64::from_bits(self.to_bits() & 0x7fff_ffff_ffff_ffff) |
452 | } | |
453 | ||
9fa01778 XL |
454 | /// Returns `true` if this value is positive infinity or negative infinity, and |
455 | /// `false` otherwise. | |
83c7162d XL |
456 | /// |
457 | /// ``` | |
83c7162d XL |
458 | /// let f = 7.0f64; |
459 | /// let inf = f64::INFINITY; | |
460 | /// let neg_inf = f64::NEG_INFINITY; | |
461 | /// let nan = f64::NAN; | |
462 | /// | |
463 | /// assert!(!f.is_infinite()); | |
464 | /// assert!(!nan.is_infinite()); | |
465 | /// | |
466 | /// assert!(inf.is_infinite()); | |
467 | /// assert!(neg_inf.is_infinite()); | |
468 | /// ``` | |
469 | #[stable(feature = "rust1", since = "1.0.0")] | |
3dfed10e | 470 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
83c7162d | 471 | #[inline] |
3dfed10e | 472 | pub const fn is_infinite(self) -> bool { |
f9f354fc | 473 | self.abs_private() == Self::INFINITY |
94b46f34 | 474 | } |
83c7162d XL |
475 | |
476 | /// Returns `true` if this number is neither infinite nor `NaN`. | |
477 | /// | |
478 | /// ``` | |
83c7162d XL |
479 | /// let f = 7.0f64; |
480 | /// let inf: f64 = f64::INFINITY; | |
481 | /// let neg_inf: f64 = f64::NEG_INFINITY; | |
482 | /// let nan: f64 = f64::NAN; | |
483 | /// | |
484 | /// assert!(f.is_finite()); | |
485 | /// | |
486 | /// assert!(!nan.is_finite()); | |
487 | /// assert!(!inf.is_finite()); | |
488 | /// assert!(!neg_inf.is_finite()); | |
489 | /// ``` | |
490 | #[stable(feature = "rust1", since = "1.0.0")] | |
3dfed10e | 491 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
83c7162d | 492 | #[inline] |
3dfed10e | 493 | pub const fn is_finite(self) -> bool { |
0731742a XL |
494 | // There's no need to handle NaN separately: if self is NaN, |
495 | // the comparison is not true, exactly as desired. | |
f9f354fc | 496 | self.abs_private() < Self::INFINITY |
94b46f34 | 497 | } |
83c7162d | 498 | |
fc512014 XL |
499 | /// Returns `true` if the number is [subnormal]. |
500 | /// | |
501 | /// ``` | |
502 | /// #![feature(is_subnormal)] | |
503 | /// let min = f64::MIN_POSITIVE; // 2.2250738585072014e-308_f64 | |
504 | /// let max = f64::MAX; | |
505 | /// let lower_than_min = 1.0e-308_f64; | |
506 | /// let zero = 0.0_f64; | |
507 | /// | |
508 | /// assert!(!min.is_subnormal()); | |
509 | /// assert!(!max.is_subnormal()); | |
510 | /// | |
511 | /// assert!(!zero.is_subnormal()); | |
512 | /// assert!(!f64::NAN.is_subnormal()); | |
513 | /// assert!(!f64::INFINITY.is_subnormal()); | |
514 | /// // Values between `0` and `min` are Subnormal. | |
515 | /// assert!(lower_than_min.is_subnormal()); | |
516 | /// ``` | |
517 | /// [subnormal]: https://en.wikipedia.org/wiki/Denormal_number | |
518 | #[unstable(feature = "is_subnormal", issue = "79288")] | |
519 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] | |
520 | #[inline] | |
521 | pub const fn is_subnormal(self) -> bool { | |
522 | matches!(self.classify(), FpCategory::Subnormal) | |
523 | } | |
524 | ||
83c7162d | 525 | /// Returns `true` if the number is neither zero, infinite, |
dfeec247 | 526 | /// [subnormal], or `NaN`. |
83c7162d XL |
527 | /// |
528 | /// ``` | |
83c7162d XL |
529 | /// let min = f64::MIN_POSITIVE; // 2.2250738585072014e-308f64 |
530 | /// let max = f64::MAX; | |
531 | /// let lower_than_min = 1.0e-308_f64; | |
532 | /// let zero = 0.0f64; | |
533 | /// | |
534 | /// assert!(min.is_normal()); | |
535 | /// assert!(max.is_normal()); | |
536 | /// | |
537 | /// assert!(!zero.is_normal()); | |
538 | /// assert!(!f64::NAN.is_normal()); | |
539 | /// assert!(!f64::INFINITY.is_normal()); | |
540 | /// // Values between `0` and `min` are Subnormal. | |
541 | /// assert!(!lower_than_min.is_normal()); | |
542 | /// ``` | |
543 | /// [subnormal]: https://en.wikipedia.org/wiki/Denormal_number | |
544 | #[stable(feature = "rust1", since = "1.0.0")] | |
3dfed10e | 545 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
83c7162d | 546 | #[inline] |
3dfed10e XL |
547 | pub const fn is_normal(self) -> bool { |
548 | matches!(self.classify(), FpCategory::Normal) | |
94b46f34 | 549 | } |
83c7162d XL |
550 | |
551 | /// Returns the floating point category of the number. If only one property | |
552 | /// is going to be tested, it is generally faster to use the specific | |
553 | /// predicate instead. | |
554 | /// | |
555 | /// ``` | |
556 | /// use std::num::FpCategory; | |
83c7162d XL |
557 | /// |
558 | /// let num = 12.4_f64; | |
559 | /// let inf = f64::INFINITY; | |
560 | /// | |
561 | /// assert_eq!(num.classify(), FpCategory::Normal); | |
562 | /// assert_eq!(inf.classify(), FpCategory::Infinite); | |
563 | /// ``` | |
564 | #[stable(feature = "rust1", since = "1.0.0")] | |
3dfed10e XL |
565 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
566 | pub const fn classify(self) -> FpCategory { | |
94b46f34 XL |
567 | const EXP_MASK: u64 = 0x7ff0000000000000; |
568 | const MAN_MASK: u64 = 0x000fffffffffffff; | |
569 | ||
570 | let bits = self.to_bits(); | |
571 | match (bits & MAN_MASK, bits & EXP_MASK) { | |
572 | (0, 0) => FpCategory::Zero, | |
573 | (_, 0) => FpCategory::Subnormal, | |
574 | (0, EXP_MASK) => FpCategory::Infinite, | |
575 | (_, EXP_MASK) => FpCategory::Nan, | |
576 | _ => FpCategory::Normal, | |
577 | } | |
578 | } | |
83c7162d | 579 | |
9fa01778 | 580 | /// Returns `true` if `self` has a positive sign, including `+0.0`, `NaN`s with |
83c7162d XL |
581 | /// positive sign bit and positive infinity. |
582 | /// | |
583 | /// ``` | |
584 | /// let f = 7.0_f64; | |
585 | /// let g = -7.0_f64; | |
586 | /// | |
587 | /// assert!(f.is_sign_positive()); | |
588 | /// assert!(!g.is_sign_positive()); | |
589 | /// ``` | |
590 | #[stable(feature = "rust1", since = "1.0.0")] | |
3dfed10e | 591 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
83c7162d | 592 | #[inline] |
3dfed10e | 593 | pub const fn is_sign_positive(self) -> bool { |
94b46f34 XL |
594 | !self.is_sign_negative() |
595 | } | |
83c7162d XL |
596 | |
597 | #[stable(feature = "rust1", since = "1.0.0")] | |
598 | #[rustc_deprecated(since = "1.0.0", reason = "renamed to is_sign_positive")] | |
599 | #[inline] | |
600 | #[doc(hidden)] | |
94b46f34 XL |
601 | pub fn is_positive(self) -> bool { |
602 | self.is_sign_positive() | |
603 | } | |
83c7162d | 604 | |
9fa01778 | 605 | /// Returns `true` if `self` has a negative sign, including `-0.0`, `NaN`s with |
83c7162d XL |
606 | /// negative sign bit and negative infinity. |
607 | /// | |
608 | /// ``` | |
609 | /// let f = 7.0_f64; | |
610 | /// let g = -7.0_f64; | |
611 | /// | |
612 | /// assert!(!f.is_sign_negative()); | |
613 | /// assert!(g.is_sign_negative()); | |
614 | /// ``` | |
615 | #[stable(feature = "rust1", since = "1.0.0")] | |
3dfed10e | 616 | #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] |
83c7162d | 617 | #[inline] |
3dfed10e | 618 | pub const fn is_sign_negative(self) -> bool { |
94b46f34 XL |
619 | self.to_bits() & 0x8000_0000_0000_0000 != 0 |
620 | } | |
83c7162d XL |
621 | |
622 | #[stable(feature = "rust1", since = "1.0.0")] | |
623 | #[rustc_deprecated(since = "1.0.0", reason = "renamed to is_sign_negative")] | |
624 | #[inline] | |
625 | #[doc(hidden)] | |
94b46f34 XL |
626 | pub fn is_negative(self) -> bool { |
627 | self.is_sign_negative() | |
628 | } | |
83c7162d XL |
629 | |
630 | /// Takes the reciprocal (inverse) of a number, `1/x`. | |
631 | /// | |
632 | /// ``` | |
633 | /// let x = 2.0_f64; | |
e1599b0c | 634 | /// let abs_difference = (x.recip() - (1.0 / x)).abs(); |
83c7162d XL |
635 | /// |
636 | /// assert!(abs_difference < 1e-10); | |
637 | /// ``` | |
638 | #[stable(feature = "rust1", since = "1.0.0")] | |
639 | #[inline] | |
94b46f34 XL |
640 | pub fn recip(self) -> f64 { |
641 | 1.0 / self | |
642 | } | |
83c7162d XL |
643 | |
644 | /// Converts radians to degrees. | |
645 | /// | |
646 | /// ``` | |
ba9703b0 | 647 | /// let angle = std::f64::consts::PI; |
83c7162d XL |
648 | /// |
649 | /// let abs_difference = (angle.to_degrees() - 180.0).abs(); | |
650 | /// | |
651 | /// assert!(abs_difference < 1e-10); | |
652 | /// ``` | |
653 | #[stable(feature = "rust1", since = "1.0.0")] | |
654 | #[inline] | |
94b46f34 XL |
655 | pub fn to_degrees(self) -> f64 { |
656 | // The division here is correctly rounded with respect to the true | |
657 | // value of 180/π. (This differs from f32, where a constant must be | |
658 | // used to ensure a correctly rounded result.) | |
659 | self * (180.0f64 / consts::PI) | |
660 | } | |
83c7162d XL |
661 | |
662 | /// Converts degrees to radians. | |
663 | /// | |
664 | /// ``` | |
83c7162d XL |
665 | /// let angle = 180.0_f64; |
666 | /// | |
ba9703b0 | 667 | /// let abs_difference = (angle.to_radians() - std::f64::consts::PI).abs(); |
83c7162d XL |
668 | /// |
669 | /// assert!(abs_difference < 1e-10); | |
670 | /// ``` | |
671 | #[stable(feature = "rust1", since = "1.0.0")] | |
672 | #[inline] | |
94b46f34 XL |
673 | pub fn to_radians(self) -> f64 { |
674 | let value: f64 = consts::PI; | |
675 | self * (value / 180.0) | |
676 | } | |
83c7162d XL |
677 | |
678 | /// Returns the maximum of the two numbers. | |
679 | /// | |
680 | /// ``` | |
681 | /// let x = 1.0_f64; | |
682 | /// let y = 2.0_f64; | |
683 | /// | |
684 | /// assert_eq!(x.max(y), y); | |
685 | /// ``` | |
686 | /// | |
687 | /// If one of the arguments is NaN, then the other argument is returned. | |
688 | #[stable(feature = "rust1", since = "1.0.0")] | |
689 | #[inline] | |
690 | pub fn max(self, other: f64) -> f64 { | |
dc9dc135 | 691 | intrinsics::maxnumf64(self, other) |
83c7162d XL |
692 | } |
693 | ||
694 | /// Returns the minimum of the two numbers. | |
695 | /// | |
696 | /// ``` | |
697 | /// let x = 1.0_f64; | |
698 | /// let y = 2.0_f64; | |
699 | /// | |
700 | /// assert_eq!(x.min(y), x); | |
701 | /// ``` | |
702 | /// | |
703 | /// If one of the arguments is NaN, then the other argument is returned. | |
704 | #[stable(feature = "rust1", since = "1.0.0")] | |
705 | #[inline] | |
706 | pub fn min(self, other: f64) -> f64 { | |
dc9dc135 | 707 | intrinsics::minnumf64(self, other) |
83c7162d XL |
708 | } |
709 | ||
60c5eb7d XL |
710 | /// Rounds toward zero and converts to any primitive integer type, |
711 | /// assuming that the value is finite and fits in that type. | |
712 | /// | |
713 | /// ``` | |
f9f354fc | 714 | /// let value = 4.6_f64; |
ba9703b0 | 715 | /// let rounded = unsafe { value.to_int_unchecked::<u16>() }; |
60c5eb7d XL |
716 | /// assert_eq!(rounded, 4); |
717 | /// | |
f9f354fc | 718 | /// let value = -128.9_f64; |
ba9703b0 XL |
719 | /// let rounded = unsafe { value.to_int_unchecked::<i8>() }; |
720 | /// assert_eq!(rounded, i8::MIN); | |
60c5eb7d XL |
721 | /// ``` |
722 | /// | |
723 | /// # Safety | |
724 | /// | |
725 | /// The value must: | |
726 | /// | |
727 | /// * Not be `NaN` | |
728 | /// * Not be infinite | |
729 | /// * Be representable in the return type `Int`, after truncating off its fractional part | |
ba9703b0 | 730 | #[stable(feature = "float_approx_unchecked_to", since = "1.44.0")] |
60c5eb7d | 731 | #[inline] |
ba9703b0 | 732 | pub unsafe fn to_int_unchecked<Int>(self) -> Int |
60c5eb7d XL |
733 | where |
734 | Self: FloatToInt<Int>, | |
735 | { | |
f035d41b XL |
736 | // SAFETY: the caller must uphold the safety contract for |
737 | // `FloatToInt::to_int_unchecked`. | |
738 | unsafe { FloatToInt::<Int>::to_int_unchecked(self) } | |
60c5eb7d XL |
739 | } |
740 | ||
83c7162d XL |
741 | /// Raw transmutation to `u64`. |
742 | /// | |
743 | /// This is currently identical to `transmute::<f64, u64>(self)` on all platforms. | |
744 | /// | |
745 | /// See `from_bits` for some discussion of the portability of this operation | |
746 | /// (there are almost no issues). | |
747 | /// | |
748 | /// Note that this function is distinct from `as` casting, which attempts to | |
749 | /// preserve the *numeric* value, and not the bitwise value. | |
750 | /// | |
751 | /// # Examples | |
752 | /// | |
753 | /// ``` | |
754 | /// assert!((1f64).to_bits() != 1f64 as u64); // to_bits() is not casting! | |
755 | /// assert_eq!((12.5f64).to_bits(), 0x4029000000000000); | |
756 | /// | |
757 | /// ``` | |
758 | #[stable(feature = "float_bits_conv", since = "1.20.0")] | |
3dfed10e | 759 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
83c7162d | 760 | #[inline] |
3dfed10e | 761 | pub const fn to_bits(self) -> u64 { |
60c5eb7d | 762 | // SAFETY: `u64` is a plain old datatype so we can always transmute to it |
94b46f34 | 763 | unsafe { mem::transmute(self) } |
83c7162d XL |
764 | } |
765 | ||
766 | /// Raw transmutation from `u64`. | |
767 | /// | |
768 | /// This is currently identical to `transmute::<u64, f64>(v)` on all platforms. | |
769 | /// It turns out this is incredibly portable, for two reasons: | |
770 | /// | |
771 | /// * Floats and Ints have the same endianness on all supported platforms. | |
772 | /// * IEEE-754 very precisely specifies the bit layout of floats. | |
773 | /// | |
774 | /// However there is one caveat: prior to the 2008 version of IEEE-754, how | |
775 | /// to interpret the NaN signaling bit wasn't actually specified. Most platforms | |
776 | /// (notably x86 and ARM) picked the interpretation that was ultimately | |
777 | /// standardized in 2008, but some didn't (notably MIPS). As a result, all | |
778 | /// signaling NaNs on MIPS are quiet NaNs on x86, and vice-versa. | |
779 | /// | |
780 | /// Rather than trying to preserve signaling-ness cross-platform, this | |
3dfed10e | 781 | /// implementation favors preserving the exact bits. This means that |
83c7162d XL |
782 | /// any payloads encoded in NaNs will be preserved even if the result of |
783 | /// this method is sent over the network from an x86 machine to a MIPS one. | |
784 | /// | |
785 | /// If the results of this method are only manipulated by the same | |
786 | /// architecture that produced them, then there is no portability concern. | |
787 | /// | |
788 | /// If the input isn't NaN, then there is no portability concern. | |
789 | /// | |
3dfed10e | 790 | /// If you don't care about signaling-ness (very likely), then there is no |
83c7162d XL |
791 | /// portability concern. |
792 | /// | |
793 | /// Note that this function is distinct from `as` casting, which attempts to | |
794 | /// preserve the *numeric* value, and not the bitwise value. | |
795 | /// | |
796 | /// # Examples | |
797 | /// | |
798 | /// ``` | |
83c7162d | 799 | /// let v = f64::from_bits(0x4029000000000000); |
416331ca | 800 | /// assert_eq!(v, 12.5); |
83c7162d XL |
801 | /// ``` |
802 | #[stable(feature = "float_bits_conv", since = "1.20.0")] | |
3dfed10e | 803 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
83c7162d | 804 | #[inline] |
3dfed10e | 805 | pub const fn from_bits(v: u64) -> Self { |
60c5eb7d | 806 | // SAFETY: `u64` is a plain old datatype so we can always transmute from it |
94b46f34 XL |
807 | // It turns out the safety issues with sNaN were overblown! Hooray! |
808 | unsafe { mem::transmute(v) } | |
83c7162d | 809 | } |
416331ca XL |
810 | |
811 | /// Return the memory representation of this floating point number as a byte array in | |
812 | /// big-endian (network) byte order. | |
813 | /// | |
814 | /// # Examples | |
815 | /// | |
816 | /// ``` | |
416331ca XL |
817 | /// let bytes = 12.5f64.to_be_bytes(); |
818 | /// assert_eq!(bytes, [0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]); | |
819 | /// ``` | |
e74abb32 | 820 | #[stable(feature = "float_to_from_bytes", since = "1.40.0")] |
3dfed10e | 821 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
416331ca | 822 | #[inline] |
3dfed10e | 823 | pub const fn to_be_bytes(self) -> [u8; 8] { |
416331ca XL |
824 | self.to_bits().to_be_bytes() |
825 | } | |
826 | ||
827 | /// Return the memory representation of this floating point number as a byte array in | |
828 | /// little-endian byte order. | |
829 | /// | |
830 | /// # Examples | |
831 | /// | |
832 | /// ``` | |
416331ca XL |
833 | /// let bytes = 12.5f64.to_le_bytes(); |
834 | /// assert_eq!(bytes, [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40]); | |
835 | /// ``` | |
e74abb32 | 836 | #[stable(feature = "float_to_from_bytes", since = "1.40.0")] |
3dfed10e | 837 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
416331ca | 838 | #[inline] |
3dfed10e | 839 | pub const fn to_le_bytes(self) -> [u8; 8] { |
416331ca XL |
840 | self.to_bits().to_le_bytes() |
841 | } | |
842 | ||
843 | /// Return the memory representation of this floating point number as a byte array in | |
844 | /// native byte order. | |
845 | /// | |
846 | /// As the target platform's native endianness is used, portable code | |
847 | /// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate, instead. | |
848 | /// | |
6a06907d XL |
849 | /// [`to_be_bytes`]: f64::to_be_bytes |
850 | /// [`to_le_bytes`]: f64::to_le_bytes | |
416331ca XL |
851 | /// |
852 | /// # Examples | |
853 | /// | |
854 | /// ``` | |
416331ca XL |
855 | /// let bytes = 12.5f64.to_ne_bytes(); |
856 | /// assert_eq!( | |
857 | /// bytes, | |
858 | /// if cfg!(target_endian = "big") { | |
859 | /// [0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00] | |
860 | /// } else { | |
861 | /// [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40] | |
862 | /// } | |
863 | /// ); | |
864 | /// ``` | |
e74abb32 | 865 | #[stable(feature = "float_to_from_bytes", since = "1.40.0")] |
3dfed10e | 866 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
416331ca | 867 | #[inline] |
3dfed10e | 868 | pub const fn to_ne_bytes(self) -> [u8; 8] { |
416331ca XL |
869 | self.to_bits().to_ne_bytes() |
870 | } | |
871 | ||
29967ef6 XL |
872 | /// Return the memory representation of this floating point number as a byte array in |
873 | /// native byte order. | |
874 | /// | |
875 | /// [`to_ne_bytes`] should be preferred over this whenever possible. | |
876 | /// | |
6a06907d | 877 | /// [`to_ne_bytes`]: f64::to_ne_bytes |
29967ef6 XL |
878 | /// |
879 | /// # Examples | |
880 | /// | |
881 | /// ``` | |
882 | /// #![feature(num_as_ne_bytes)] | |
883 | /// let num = 12.5f64; | |
884 | /// let bytes = num.as_ne_bytes(); | |
885 | /// assert_eq!( | |
886 | /// bytes, | |
887 | /// if cfg!(target_endian = "big") { | |
888 | /// &[0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00] | |
889 | /// } else { | |
890 | /// &[0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40] | |
891 | /// } | |
892 | /// ); | |
893 | /// ``` | |
894 | #[unstable(feature = "num_as_ne_bytes", issue = "76976")] | |
895 | #[inline] | |
896 | pub fn as_ne_bytes(&self) -> &[u8; 8] { | |
897 | // SAFETY: `f64` is a plain old datatype so we can always transmute to it | |
898 | unsafe { &*(self as *const Self as *const _) } | |
899 | } | |
900 | ||
416331ca XL |
901 | /// Create a floating point value from its representation as a byte array in big endian. |
902 | /// | |
903 | /// # Examples | |
904 | /// | |
905 | /// ``` | |
416331ca XL |
906 | /// let value = f64::from_be_bytes([0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]); |
907 | /// assert_eq!(value, 12.5); | |
908 | /// ``` | |
e74abb32 | 909 | #[stable(feature = "float_to_from_bytes", since = "1.40.0")] |
3dfed10e | 910 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
416331ca | 911 | #[inline] |
3dfed10e | 912 | pub const fn from_be_bytes(bytes: [u8; 8]) -> Self { |
416331ca XL |
913 | Self::from_bits(u64::from_be_bytes(bytes)) |
914 | } | |
915 | ||
916 | /// Create a floating point value from its representation as a byte array in little endian. | |
917 | /// | |
918 | /// # Examples | |
919 | /// | |
920 | /// ``` | |
416331ca XL |
921 | /// let value = f64::from_le_bytes([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40]); |
922 | /// assert_eq!(value, 12.5); | |
923 | /// ``` | |
e74abb32 | 924 | #[stable(feature = "float_to_from_bytes", since = "1.40.0")] |
3dfed10e | 925 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
416331ca | 926 | #[inline] |
3dfed10e | 927 | pub const fn from_le_bytes(bytes: [u8; 8]) -> Self { |
416331ca XL |
928 | Self::from_bits(u64::from_le_bytes(bytes)) |
929 | } | |
930 | ||
931 | /// Create a floating point value from its representation as a byte array in native endian. | |
932 | /// | |
933 | /// As the target platform's native endianness is used, portable code | |
934 | /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as | |
935 | /// appropriate instead. | |
936 | /// | |
6a06907d XL |
937 | /// [`from_be_bytes`]: f64::from_be_bytes |
938 | /// [`from_le_bytes`]: f64::from_le_bytes | |
416331ca XL |
939 | /// |
940 | /// # Examples | |
941 | /// | |
942 | /// ``` | |
416331ca XL |
943 | /// let value = f64::from_ne_bytes(if cfg!(target_endian = "big") { |
944 | /// [0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00] | |
945 | /// } else { | |
946 | /// [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40] | |
947 | /// }); | |
948 | /// assert_eq!(value, 12.5); | |
949 | /// ``` | |
e74abb32 | 950 | #[stable(feature = "float_to_from_bytes", since = "1.40.0")] |
3dfed10e | 951 | #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] |
416331ca | 952 | #[inline] |
3dfed10e | 953 | pub const fn from_ne_bytes(bytes: [u8; 8]) -> Self { |
416331ca XL |
954 | Self::from_bits(u64::from_ne_bytes(bytes)) |
955 | } | |
f9f354fc XL |
956 | |
957 | /// Returns an ordering between self and other values. | |
958 | /// Unlike the standard partial comparison between floating point numbers, | |
959 | /// this comparison always produces an ordering in accordance to | |
960 | /// the totalOrder predicate as defined in IEEE 754 (2008 revision) | |
961 | /// floating point standard. The values are ordered in following order: | |
962 | /// - Negative quiet NaN | |
963 | /// - Negative signaling NaN | |
964 | /// - Negative infinity | |
965 | /// - Negative numbers | |
966 | /// - Negative subnormal numbers | |
967 | /// - Negative zero | |
968 | /// - Positive zero | |
969 | /// - Positive subnormal numbers | |
970 | /// - Positive numbers | |
971 | /// - Positive infinity | |
972 | /// - Positive signaling NaN | |
973 | /// - Positive quiet NaN | |
974 | /// | |
29967ef6 XL |
975 | /// Note that this function does not always agree with the [`PartialOrd`] |
976 | /// and [`PartialEq`] implementations of `f64`. In particular, they regard | |
977 | /// negative and positive zero as equal, while `total_cmp` doesn't. | |
978 | /// | |
f9f354fc XL |
979 | /// # Example |
980 | /// ``` | |
981 | /// #![feature(total_cmp)] | |
982 | /// struct GoodBoy { | |
983 | /// name: String, | |
984 | /// weight: f64, | |
985 | /// } | |
986 | /// | |
987 | /// let mut bois = vec![ | |
988 | /// GoodBoy { name: "Pucci".to_owned(), weight: 0.1 }, | |
989 | /// GoodBoy { name: "Woofer".to_owned(), weight: 99.0 }, | |
990 | /// GoodBoy { name: "Yapper".to_owned(), weight: 10.0 }, | |
991 | /// GoodBoy { name: "Chonk".to_owned(), weight: f64::INFINITY }, | |
992 | /// GoodBoy { name: "Abs. Unit".to_owned(), weight: f64::NAN }, | |
993 | /// GoodBoy { name: "Floaty".to_owned(), weight: -5.0 }, | |
994 | /// ]; | |
995 | /// | |
996 | /// bois.sort_by(|a, b| a.weight.total_cmp(&b.weight)); | |
997 | /// # assert!(bois.into_iter().map(|b| b.weight) | |
998 | /// # .zip([-5.0, 0.1, 10.0, 99.0, f64::INFINITY, f64::NAN].iter()) | |
999 | /// # .all(|(a, b)| a.to_bits() == b.to_bits())) | |
1000 | /// ``` | |
1001 | #[unstable(feature = "total_cmp", issue = "72599")] | |
1002 | #[inline] | |
1003 | pub fn total_cmp(&self, other: &Self) -> crate::cmp::Ordering { | |
1004 | let mut left = self.to_bits() as i64; | |
1005 | let mut right = other.to_bits() as i64; | |
1006 | ||
1007 | // In case of negatives, flip all the bits except the sign | |
1008 | // to achieve a similar layout as two's complement integers | |
1009 | // | |
1010 | // Why does this work? IEEE 754 floats consist of three fields: | |
1011 | // Sign bit, exponent and mantissa. The set of exponent and mantissa | |
1012 | // fields as a whole have the property that their bitwise order is | |
1013 | // equal to the numeric magnitude where the magnitude is defined. | |
1014 | // The magnitude is not normally defined on NaN values, but | |
1015 | // IEEE 754 totalOrder defines the NaN values also to follow the | |
1016 | // bitwise order. This leads to order explained in the doc comment. | |
1017 | // However, the representation of magnitude is the same for negative | |
1018 | // and positive numbers – only the sign bit is different. | |
1019 | // To easily compare the floats as signed integers, we need to | |
1020 | // flip the exponent and mantissa bits in case of negative numbers. | |
1021 | // We effectively convert the numbers to "two's complement" form. | |
1022 | // | |
1023 | // To do the flipping, we construct a mask and XOR against it. | |
1024 | // We branchlessly calculate an "all-ones except for the sign bit" | |
1025 | // mask from negative-signed values: right shifting sign-extends | |
1026 | // the integer, so we "fill" the mask with sign bits, and then | |
1027 | // convert to unsigned to push one more zero bit. | |
1028 | // On positive values, the mask is all zeros, so it's a no-op. | |
1029 | left ^= (((left >> 63) as u64) >> 1) as i64; | |
1030 | right ^= (((right >> 63) as u64) >> 1) as i64; | |
1031 | ||
1032 | left.cmp(&right) | |
1033 | } | |
fc512014 XL |
1034 | |
1035 | /// Restrict a value to a certain interval unless it is NaN. | |
1036 | /// | |
1037 | /// Returns `max` if `self` is greater than `max`, and `min` if `self` is | |
1038 | /// less than `min`. Otherwise this returns `self`. | |
1039 | /// | |
1040 | /// Note that this function returns NaN if the initial value was NaN as | |
1041 | /// well. | |
1042 | /// | |
1043 | /// # Panics | |
1044 | /// | |
1045 | /// Panics if `min > max`, `min` is NaN, or `max` is NaN. | |
1046 | /// | |
1047 | /// # Examples | |
1048 | /// | |
1049 | /// ``` | |
1050 | /// assert!((-3.0f64).clamp(-2.0, 1.0) == -2.0); | |
1051 | /// assert!((0.0f64).clamp(-2.0, 1.0) == 0.0); | |
1052 | /// assert!((2.0f64).clamp(-2.0, 1.0) == 1.0); | |
1053 | /// assert!((f64::NAN).clamp(-2.0, 1.0).is_nan()); | |
1054 | /// ``` | |
1055 | #[must_use = "method returns a new number and does not mutate the original value"] | |
1056 | #[stable(feature = "clamp", since = "1.50.0")] | |
1057 | #[inline] | |
1058 | pub fn clamp(self, min: f64, max: f64) -> f64 { | |
1059 | assert!(min <= max); | |
1060 | let mut x = self; | |
1061 | if x < min { | |
1062 | x = min; | |
1063 | } | |
1064 | if x > max { | |
1065 | x = max; | |
1066 | } | |
1067 | x | |
1068 | } | |
83c7162d | 1069 | } |