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