1 use core::mem::size_of;
2 use core::num::Wrapping;
3 use core::{f32, f64};
4 use core::{i128, i16, i32, i64, i8, isize};
5 use core::{u128, u16, u32, u64, u8, usize};
6 
7 /// A generic trait for converting a value to a number.
8 ///
9 /// A value can be represented by the target type when it lies within
10 /// the range of scalars supported by the target type.
11 /// For example, a negative integer cannot be represented by an unsigned
12 /// integer type, and an `i64` with a very high magnitude might not be
13 /// convertible to an `i32`.
14 /// On the other hand, conversions with possible precision loss or truncation
15 /// are admitted, like an `f32` with a decimal part to an integer type, or
16 /// even a large `f64` saturating to `f32` infinity.
17 pub trait ToPrimitive {
18     /// Converts the value of `self` to an `isize`. If the value cannot be
19     /// represented by an `isize`, then `None` is returned.
20     #[inline]
to_isize(&self) -> Option<isize>21     fn to_isize(&self) -> Option<isize> {
22         self.to_i64().as_ref().and_then(ToPrimitive::to_isize)
23     }
24 
25     /// Converts the value of `self` to an `i8`. If the value cannot be
26     /// represented by an `i8`, then `None` is returned.
27     #[inline]
to_i8(&self) -> Option<i8>28     fn to_i8(&self) -> Option<i8> {
29         self.to_i64().as_ref().and_then(ToPrimitive::to_i8)
30     }
31 
32     /// Converts the value of `self` to an `i16`. If the value cannot be
33     /// represented by an `i16`, then `None` is returned.
34     #[inline]
to_i16(&self) -> Option<i16>35     fn to_i16(&self) -> Option<i16> {
36         self.to_i64().as_ref().and_then(ToPrimitive::to_i16)
37     }
38 
39     /// Converts the value of `self` to an `i32`. If the value cannot be
40     /// represented by an `i32`, then `None` is returned.
41     #[inline]
to_i32(&self) -> Option<i32>42     fn to_i32(&self) -> Option<i32> {
43         self.to_i64().as_ref().and_then(ToPrimitive::to_i32)
44     }
45 
46     /// Converts the value of `self` to an `i64`. If the value cannot be
47     /// represented by an `i64`, then `None` is returned.
to_i64(&self) -> Option<i64>48     fn to_i64(&self) -> Option<i64>;
49 
50     /// Converts the value of `self` to an `i128`. If the value cannot be
51     /// represented by an `i128` (`i64` under the default implementation), then
52     /// `None` is returned.
53     ///
54     /// The default implementation converts through `to_i64()`. Types implementing
55     /// this trait should override this method if they can represent a greater range.
56     #[inline]
to_i128(&self) -> Option<i128>57     fn to_i128(&self) -> Option<i128> {
58         self.to_i64().map(From::from)
59     }
60 
61     /// Converts the value of `self` to a `usize`. If the value cannot be
62     /// represented by a `usize`, then `None` is returned.
63     #[inline]
to_usize(&self) -> Option<usize>64     fn to_usize(&self) -> Option<usize> {
65         self.to_u64().as_ref().and_then(ToPrimitive::to_usize)
66     }
67 
68     /// Converts the value of `self` to a `u8`. If the value cannot be
69     /// represented by a `u8`, then `None` is returned.
70     #[inline]
to_u8(&self) -> Option<u8>71     fn to_u8(&self) -> Option<u8> {
72         self.to_u64().as_ref().and_then(ToPrimitive::to_u8)
73     }
74 
75     /// Converts the value of `self` to a `u16`. If the value cannot be
76     /// represented by a `u16`, then `None` is returned.
77     #[inline]
to_u16(&self) -> Option<u16>78     fn to_u16(&self) -> Option<u16> {
79         self.to_u64().as_ref().and_then(ToPrimitive::to_u16)
80     }
81 
82     /// Converts the value of `self` to a `u32`. If the value cannot be
83     /// represented by a `u32`, then `None` is returned.
84     #[inline]
to_u32(&self) -> Option<u32>85     fn to_u32(&self) -> Option<u32> {
86         self.to_u64().as_ref().and_then(ToPrimitive::to_u32)
87     }
88 
89     /// Converts the value of `self` to a `u64`. If the value cannot be
90     /// represented by a `u64`, then `None` is returned.
to_u64(&self) -> Option<u64>91     fn to_u64(&self) -> Option<u64>;
92 
93     /// Converts the value of `self` to a `u128`. If the value cannot be
94     /// represented by a `u128` (`u64` under the default implementation), then
95     /// `None` is returned.
96     ///
97     /// The default implementation converts through `to_u64()`. Types implementing
98     /// this trait should override this method if they can represent a greater range.
99     #[inline]
to_u128(&self) -> Option<u128>100     fn to_u128(&self) -> Option<u128> {
101         self.to_u64().map(From::from)
102     }
103 
104     /// Converts the value of `self` to an `f32`. Overflows may map to positive
105     /// or negative inifinity, otherwise `None` is returned if the value cannot
106     /// be represented by an `f32`.
107     #[inline]
to_f32(&self) -> Option<f32>108     fn to_f32(&self) -> Option<f32> {
109         self.to_f64().as_ref().and_then(ToPrimitive::to_f32)
110     }
111 
112     /// Converts the value of `self` to an `f64`. Overflows may map to positive
113     /// or negative inifinity, otherwise `None` is returned if the value cannot
114     /// be represented by an `f64`.
115     ///
116     /// The default implementation tries to convert through `to_i64()`, and
117     /// failing that through `to_u64()`. Types implementing this trait should
118     /// override this method if they can represent a greater range.
119     #[inline]
to_f64(&self) -> Option<f64>120     fn to_f64(&self) -> Option<f64> {
121         match self.to_i64() {
122             Some(i) => i.to_f64(),
123             None => self.to_u64().as_ref().and_then(ToPrimitive::to_f64),
124         }
125     }
126 }
127 
128 macro_rules! impl_to_primitive_int_to_int {
129     ($SrcT:ident : $( $(#[$cfg:meta])* fn $method:ident -> $DstT:ident ; )*) => {$(
130         #[inline]
131         $(#[$cfg])*
132         fn $method(&self) -> Option<$DstT> {
133             let min = $DstT::MIN as $SrcT;
134             let max = $DstT::MAX as $SrcT;
135             if size_of::<$SrcT>() <= size_of::<$DstT>() || (min <= *self && *self <= max) {
136                 Some(*self as $DstT)
137             } else {
138                 None
139             }
140         }
141     )*}
142 }
143 
144 macro_rules! impl_to_primitive_int_to_uint {
145     ($SrcT:ident : $( $(#[$cfg:meta])* fn $method:ident -> $DstT:ident ; )*) => {$(
146         #[inline]
147         $(#[$cfg])*
148         fn $method(&self) -> Option<$DstT> {
149             let max = $DstT::MAX as $SrcT;
150             if 0 <= *self && (size_of::<$SrcT>() <= size_of::<$DstT>() || *self <= max) {
151                 Some(*self as $DstT)
152             } else {
153                 None
154             }
155         }
156     )*}
157 }
158 
159 macro_rules! impl_to_primitive_int {
160     ($T:ident) => {
161         impl ToPrimitive for $T {
162             impl_to_primitive_int_to_int! { $T:
163                 fn to_isize -> isize;
164                 fn to_i8 -> i8;
165                 fn to_i16 -> i16;
166                 fn to_i32 -> i32;
167                 fn to_i64 -> i64;
168                 fn to_i128 -> i128;
169             }
170 
171             impl_to_primitive_int_to_uint! { $T:
172                 fn to_usize -> usize;
173                 fn to_u8 -> u8;
174                 fn to_u16 -> u16;
175                 fn to_u32 -> u32;
176                 fn to_u64 -> u64;
177                 fn to_u128 -> u128;
178             }
179 
180             #[inline]
181             fn to_f32(&self) -> Option<f32> {
182                 Some(*self as f32)
183             }
184             #[inline]
185             fn to_f64(&self) -> Option<f64> {
186                 Some(*self as f64)
187             }
188         }
189     };
190 }
191 
192 impl_to_primitive_int!(isize);
193 impl_to_primitive_int!(i8);
194 impl_to_primitive_int!(i16);
195 impl_to_primitive_int!(i32);
196 impl_to_primitive_int!(i64);
197 impl_to_primitive_int!(i128);
198 
199 macro_rules! impl_to_primitive_uint_to_int {
200     ($SrcT:ident : $( $(#[$cfg:meta])* fn $method:ident -> $DstT:ident ; )*) => {$(
201         #[inline]
202         $(#[$cfg])*
203         fn $method(&self) -> Option<$DstT> {
204             let max = $DstT::MAX as $SrcT;
205             if size_of::<$SrcT>() < size_of::<$DstT>() || *self <= max {
206                 Some(*self as $DstT)
207             } else {
208                 None
209             }
210         }
211     )*}
212 }
213 
214 macro_rules! impl_to_primitive_uint_to_uint {
215     ($SrcT:ident : $( $(#[$cfg:meta])* fn $method:ident -> $DstT:ident ; )*) => {$(
216         #[inline]
217         $(#[$cfg])*
218         fn $method(&self) -> Option<$DstT> {
219             let max = $DstT::MAX as $SrcT;
220             if size_of::<$SrcT>() <= size_of::<$DstT>() || *self <= max {
221                 Some(*self as $DstT)
222             } else {
223                 None
224             }
225         }
226     )*}
227 }
228 
229 macro_rules! impl_to_primitive_uint {
230     ($T:ident) => {
231         impl ToPrimitive for $T {
232             impl_to_primitive_uint_to_int! { $T:
233                 fn to_isize -> isize;
234                 fn to_i8 -> i8;
235                 fn to_i16 -> i16;
236                 fn to_i32 -> i32;
237                 fn to_i64 -> i64;
238                 fn to_i128 -> i128;
239             }
240 
241             impl_to_primitive_uint_to_uint! { $T:
242                 fn to_usize -> usize;
243                 fn to_u8 -> u8;
244                 fn to_u16 -> u16;
245                 fn to_u32 -> u32;
246                 fn to_u64 -> u64;
247                 fn to_u128 -> u128;
248             }
249 
250             #[inline]
251             fn to_f32(&self) -> Option<f32> {
252                 Some(*self as f32)
253             }
254             #[inline]
255             fn to_f64(&self) -> Option<f64> {
256                 Some(*self as f64)
257             }
258         }
259     };
260 }
261 
262 impl_to_primitive_uint!(usize);
263 impl_to_primitive_uint!(u8);
264 impl_to_primitive_uint!(u16);
265 impl_to_primitive_uint!(u32);
266 impl_to_primitive_uint!(u64);
267 impl_to_primitive_uint!(u128);
268 
269 macro_rules! impl_to_primitive_float_to_float {
270     ($SrcT:ident : $( fn $method:ident -> $DstT:ident ; )*) => {$(
271         #[inline]
272         fn $method(&self) -> Option<$DstT> {
273             // We can safely cast all values, whether NaN, +-inf, or finite.
274             // Finite values that are reducing size may saturate to +-inf.
275             Some(*self as $DstT)
276         }
277     )*}
278 }
279 
280 macro_rules! float_to_int_unchecked {
281     // SAFETY: Must not be NaN or infinite; must be representable as the integer after truncating.
282     // We already checked that the float is in the exclusive range `(MIN-1, MAX+1)`.
283     ($float:expr => $int:ty) => {
284         unsafe { $float.to_int_unchecked::<$int>() }
285     };
286 }
287 
288 macro_rules! impl_to_primitive_float_to_signed_int {
289     ($f:ident : $( $(#[$cfg:meta])* fn $method:ident -> $i:ident ; )*) => {$(
290         #[inline]
291         $(#[$cfg])*
292         fn $method(&self) -> Option<$i> {
293             // Float as int truncates toward zero, so we want to allow values
294             // in the exclusive range `(MIN-1, MAX+1)`.
295             if size_of::<$f>() > size_of::<$i>() {
296                 // With a larger size, we can represent the range exactly.
297                 const MIN_M1: $f = $i::MIN as $f - 1.0;
298                 const MAX_P1: $f = $i::MAX as $f + 1.0;
299                 if *self > MIN_M1 && *self < MAX_P1 {
300                     return Some(float_to_int_unchecked!(*self => $i));
301                 }
302             } else {
303                 // We can't represent `MIN-1` exactly, but there's no fractional part
304                 // at this magnitude, so we can just use a `MIN` inclusive boundary.
305                 const MIN: $f = $i::MIN as $f;
306                 // We can't represent `MAX` exactly, but it will round up to exactly
307                 // `MAX+1` (a power of two) when we cast it.
308                 const MAX_P1: $f = $i::MAX as $f;
309                 if *self >= MIN && *self < MAX_P1 {
310                     return Some(float_to_int_unchecked!(*self => $i));
311                 }
312             }
313             None
314         }
315     )*}
316 }
317 
318 macro_rules! impl_to_primitive_float_to_unsigned_int {
319     ($f:ident : $( $(#[$cfg:meta])* fn $method:ident -> $u:ident ; )*) => {$(
320         #[inline]
321         $(#[$cfg])*
322         fn $method(&self) -> Option<$u> {
323             // Float as int truncates toward zero, so we want to allow values
324             // in the exclusive range `(-1, MAX+1)`.
325             if size_of::<$f>() > size_of::<$u>() {
326                 // With a larger size, we can represent the range exactly.
327                 const MAX_P1: $f = $u::MAX as $f + 1.0;
328                 if *self > -1.0 && *self < MAX_P1 {
329                     return Some(float_to_int_unchecked!(*self => $u));
330                 }
331             } else {
332                 // We can't represent `MAX` exactly, but it will round up to exactly
333                 // `MAX+1` (a power of two) when we cast it.
334                 // (`u128::MAX as f32` is infinity, but this is still ok.)
335                 const MAX_P1: $f = $u::MAX as $f;
336                 if *self > -1.0 && *self < MAX_P1 {
337                     return Some(float_to_int_unchecked!(*self => $u));
338                 }
339             }
340             None
341         }
342     )*}
343 }
344 
345 macro_rules! impl_to_primitive_float {
346     ($T:ident) => {
347         impl ToPrimitive for $T {
348             impl_to_primitive_float_to_signed_int! { $T:
349                 fn to_isize -> isize;
350                 fn to_i8 -> i8;
351                 fn to_i16 -> i16;
352                 fn to_i32 -> i32;
353                 fn to_i64 -> i64;
354                 fn to_i128 -> i128;
355             }
356 
357             impl_to_primitive_float_to_unsigned_int! { $T:
358                 fn to_usize -> usize;
359                 fn to_u8 -> u8;
360                 fn to_u16 -> u16;
361                 fn to_u32 -> u32;
362                 fn to_u64 -> u64;
363                 fn to_u128 -> u128;
364             }
365 
366             impl_to_primitive_float_to_float! { $T:
367                 fn to_f32 -> f32;
368                 fn to_f64 -> f64;
369             }
370         }
371     };
372 }
373 
374 impl_to_primitive_float!(f32);
375 impl_to_primitive_float!(f64);
376 
377 /// A generic trait for converting a number to a value.
378 ///
379 /// A value can be represented by the target type when it lies within
380 /// the range of scalars supported by the target type.
381 /// For example, a negative integer cannot be represented by an unsigned
382 /// integer type, and an `i64` with a very high magnitude might not be
383 /// convertible to an `i32`.
384 /// On the other hand, conversions with possible precision loss or truncation
385 /// are admitted, like an `f32` with a decimal part to an integer type, or
386 /// even a large `f64` saturating to `f32` infinity.
387 pub trait FromPrimitive: Sized {
388     /// Converts an `isize` to return an optional value of this type. If the
389     /// value cannot be represented by this type, then `None` is returned.
390     #[inline]
from_isize(n: isize) -> Option<Self>391     fn from_isize(n: isize) -> Option<Self> {
392         n.to_i64().and_then(FromPrimitive::from_i64)
393     }
394 
395     /// Converts an `i8` to return an optional value of this type. If the
396     /// value cannot be represented by this type, then `None` is returned.
397     #[inline]
from_i8(n: i8) -> Option<Self>398     fn from_i8(n: i8) -> Option<Self> {
399         FromPrimitive::from_i64(From::from(n))
400     }
401 
402     /// Converts an `i16` to return an optional value of this type. If the
403     /// value cannot be represented by this type, then `None` is returned.
404     #[inline]
from_i16(n: i16) -> Option<Self>405     fn from_i16(n: i16) -> Option<Self> {
406         FromPrimitive::from_i64(From::from(n))
407     }
408 
409     /// Converts an `i32` to return an optional value of this type. If the
410     /// value cannot be represented by this type, then `None` is returned.
411     #[inline]
from_i32(n: i32) -> Option<Self>412     fn from_i32(n: i32) -> Option<Self> {
413         FromPrimitive::from_i64(From::from(n))
414     }
415 
416     /// Converts an `i64` to return an optional value of this type. If the
417     /// value cannot be represented by this type, then `None` is returned.
from_i64(n: i64) -> Option<Self>418     fn from_i64(n: i64) -> Option<Self>;
419 
420     /// Converts an `i128` to return an optional value of this type. If the
421     /// value cannot be represented by this type, then `None` is returned.
422     ///
423     /// The default implementation converts through `from_i64()`. Types implementing
424     /// this trait should override this method if they can represent a greater range.
425     #[inline]
from_i128(n: i128) -> Option<Self>426     fn from_i128(n: i128) -> Option<Self> {
427         n.to_i64().and_then(FromPrimitive::from_i64)
428     }
429 
430     /// Converts a `usize` to return an optional value of this type. If the
431     /// value cannot be represented by this type, then `None` is returned.
432     #[inline]
from_usize(n: usize) -> Option<Self>433     fn from_usize(n: usize) -> Option<Self> {
434         n.to_u64().and_then(FromPrimitive::from_u64)
435     }
436 
437     /// Converts an `u8` to return an optional value of this type. If the
438     /// value cannot be represented by this type, then `None` is returned.
439     #[inline]
from_u8(n: u8) -> Option<Self>440     fn from_u8(n: u8) -> Option<Self> {
441         FromPrimitive::from_u64(From::from(n))
442     }
443 
444     /// Converts an `u16` to return an optional value of this type. If the
445     /// value cannot be represented by this type, then `None` is returned.
446     #[inline]
from_u16(n: u16) -> Option<Self>447     fn from_u16(n: u16) -> Option<Self> {
448         FromPrimitive::from_u64(From::from(n))
449     }
450 
451     /// Converts an `u32` to return an optional value of this type. If the
452     /// value cannot be represented by this type, then `None` is returned.
453     #[inline]
from_u32(n: u32) -> Option<Self>454     fn from_u32(n: u32) -> Option<Self> {
455         FromPrimitive::from_u64(From::from(n))
456     }
457 
458     /// Converts an `u64` to return an optional value of this type. If the
459     /// value cannot be represented by this type, then `None` is returned.
from_u64(n: u64) -> Option<Self>460     fn from_u64(n: u64) -> Option<Self>;
461 
462     /// Converts an `u128` to return an optional value of this type. If the
463     /// value cannot be represented by this type, then `None` is returned.
464     ///
465     /// The default implementation converts through `from_u64()`. Types implementing
466     /// this trait should override this method if they can represent a greater range.
467     #[inline]
from_u128(n: u128) -> Option<Self>468     fn from_u128(n: u128) -> Option<Self> {
469         n.to_u64().and_then(FromPrimitive::from_u64)
470     }
471 
472     /// Converts a `f32` to return an optional value of this type. If the
473     /// value cannot be represented by this type, then `None` is returned.
474     #[inline]
from_f32(n: f32) -> Option<Self>475     fn from_f32(n: f32) -> Option<Self> {
476         FromPrimitive::from_f64(From::from(n))
477     }
478 
479     /// Converts a `f64` to return an optional value of this type. If the
480     /// value cannot be represented by this type, then `None` is returned.
481     ///
482     /// The default implementation tries to convert through `from_i64()`, and
483     /// failing that through `from_u64()`. Types implementing this trait should
484     /// override this method if they can represent a greater range.
485     #[inline]
from_f64(n: f64) -> Option<Self>486     fn from_f64(n: f64) -> Option<Self> {
487         match n.to_i64() {
488             Some(i) => FromPrimitive::from_i64(i),
489             None => n.to_u64().and_then(FromPrimitive::from_u64),
490         }
491     }
492 }
493 
494 macro_rules! impl_from_primitive {
495     ($T:ty, $to_ty:ident) => {
496         #[allow(deprecated)]
497         impl FromPrimitive for $T {
498             #[inline]
499             fn from_isize(n: isize) -> Option<$T> {
500                 n.$to_ty()
501             }
502             #[inline]
503             fn from_i8(n: i8) -> Option<$T> {
504                 n.$to_ty()
505             }
506             #[inline]
507             fn from_i16(n: i16) -> Option<$T> {
508                 n.$to_ty()
509             }
510             #[inline]
511             fn from_i32(n: i32) -> Option<$T> {
512                 n.$to_ty()
513             }
514             #[inline]
515             fn from_i64(n: i64) -> Option<$T> {
516                 n.$to_ty()
517             }
518             #[inline]
519             fn from_i128(n: i128) -> Option<$T> {
520                 n.$to_ty()
521             }
522 
523             #[inline]
524             fn from_usize(n: usize) -> Option<$T> {
525                 n.$to_ty()
526             }
527             #[inline]
528             fn from_u8(n: u8) -> Option<$T> {
529                 n.$to_ty()
530             }
531             #[inline]
532             fn from_u16(n: u16) -> Option<$T> {
533                 n.$to_ty()
534             }
535             #[inline]
536             fn from_u32(n: u32) -> Option<$T> {
537                 n.$to_ty()
538             }
539             #[inline]
540             fn from_u64(n: u64) -> Option<$T> {
541                 n.$to_ty()
542             }
543             #[inline]
544             fn from_u128(n: u128) -> Option<$T> {
545                 n.$to_ty()
546             }
547 
548             #[inline]
549             fn from_f32(n: f32) -> Option<$T> {
550                 n.$to_ty()
551             }
552             #[inline]
553             fn from_f64(n: f64) -> Option<$T> {
554                 n.$to_ty()
555             }
556         }
557     };
558 }
559 
560 impl_from_primitive!(isize, to_isize);
561 impl_from_primitive!(i8, to_i8);
562 impl_from_primitive!(i16, to_i16);
563 impl_from_primitive!(i32, to_i32);
564 impl_from_primitive!(i64, to_i64);
565 impl_from_primitive!(i128, to_i128);
566 impl_from_primitive!(usize, to_usize);
567 impl_from_primitive!(u8, to_u8);
568 impl_from_primitive!(u16, to_u16);
569 impl_from_primitive!(u32, to_u32);
570 impl_from_primitive!(u64, to_u64);
571 impl_from_primitive!(u128, to_u128);
572 impl_from_primitive!(f32, to_f32);
573 impl_from_primitive!(f64, to_f64);
574 
575 macro_rules! impl_to_primitive_wrapping {
576     ($( $(#[$cfg:meta])* fn $method:ident -> $i:ident ; )*) => {$(
577         #[inline]
578         $(#[$cfg])*
579         fn $method(&self) -> Option<$i> {
580             (self.0).$method()
581         }
582     )*}
583 }
584 
585 impl<T: ToPrimitive> ToPrimitive for Wrapping<T> {
586     impl_to_primitive_wrapping! {
587         fn to_isize -> isize;
588         fn to_i8 -> i8;
589         fn to_i16 -> i16;
590         fn to_i32 -> i32;
591         fn to_i64 -> i64;
592         fn to_i128 -> i128;
593 
594         fn to_usize -> usize;
595         fn to_u8 -> u8;
596         fn to_u16 -> u16;
597         fn to_u32 -> u32;
598         fn to_u64 -> u64;
599         fn to_u128 -> u128;
600 
601         fn to_f32 -> f32;
602         fn to_f64 -> f64;
603     }
604 }
605 
606 macro_rules! impl_from_primitive_wrapping {
607     ($( $(#[$cfg:meta])* fn $method:ident ( $i:ident ); )*) => {$(
608         #[inline]
609         $(#[$cfg])*
610         fn $method(n: $i) -> Option<Self> {
611             T::$method(n).map(Wrapping)
612         }
613     )*}
614 }
615 
616 impl<T: FromPrimitive> FromPrimitive for Wrapping<T> {
617     impl_from_primitive_wrapping! {
618         fn from_isize(isize);
619         fn from_i8(i8);
620         fn from_i16(i16);
621         fn from_i32(i32);
622         fn from_i64(i64);
623         fn from_i128(i128);
624 
625         fn from_usize(usize);
626         fn from_u8(u8);
627         fn from_u16(u16);
628         fn from_u32(u32);
629         fn from_u64(u64);
630         fn from_u128(u128);
631 
632         fn from_f32(f32);
633         fn from_f64(f64);
634     }
635 }
636 
637 /// Cast from one machine scalar to another.
638 ///
639 /// # Examples
640 ///
641 /// ```
642 /// # use num_traits as num;
643 /// let twenty: f32 = num::cast(0x14).unwrap();
644 /// assert_eq!(twenty, 20f32);
645 /// ```
646 ///
647 #[inline]
cast<T: NumCast, U: NumCast>(n: T) -> Option<U>648 pub fn cast<T: NumCast, U: NumCast>(n: T) -> Option<U> {
649     NumCast::from(n)
650 }
651 
652 /// An interface for casting between machine scalars.
653 pub trait NumCast: Sized + ToPrimitive {
654     /// Creates a number from another value that can be converted into
655     /// a primitive via the `ToPrimitive` trait. If the source value cannot be
656     /// represented by the target type, then `None` is returned.
657     ///
658     /// A value can be represented by the target type when it lies within
659     /// the range of scalars supported by the target type.
660     /// For example, a negative integer cannot be represented by an unsigned
661     /// integer type, and an `i64` with a very high magnitude might not be
662     /// convertible to an `i32`.
663     /// On the other hand, conversions with possible precision loss or truncation
664     /// are admitted, like an `f32` with a decimal part to an integer type, or
665     /// even a large `f64` saturating to `f32` infinity.
from<T: ToPrimitive>(n: T) -> Option<Self>666     fn from<T: ToPrimitive>(n: T) -> Option<Self>;
667 }
668 
669 macro_rules! impl_num_cast {
670     ($T:ty, $conv:ident) => {
671         impl NumCast for $T {
672             #[inline]
673             #[allow(deprecated)]
674             fn from<N: ToPrimitive>(n: N) -> Option<$T> {
675                 // `$conv` could be generated using `concat_idents!`, but that
676                 // macro seems to be broken at the moment
677                 n.$conv()
678             }
679         }
680     };
681 }
682 
683 impl_num_cast!(u8, to_u8);
684 impl_num_cast!(u16, to_u16);
685 impl_num_cast!(u32, to_u32);
686 impl_num_cast!(u64, to_u64);
687 impl_num_cast!(u128, to_u128);
688 impl_num_cast!(usize, to_usize);
689 impl_num_cast!(i8, to_i8);
690 impl_num_cast!(i16, to_i16);
691 impl_num_cast!(i32, to_i32);
692 impl_num_cast!(i64, to_i64);
693 impl_num_cast!(i128, to_i128);
694 impl_num_cast!(isize, to_isize);
695 impl_num_cast!(f32, to_f32);
696 impl_num_cast!(f64, to_f64);
697 
698 impl<T: NumCast> NumCast for Wrapping<T> {
from<U: ToPrimitive>(n: U) -> Option<Self>699     fn from<U: ToPrimitive>(n: U) -> Option<Self> {
700         T::from(n).map(Wrapping)
701     }
702 }
703 
704 /// A generic interface for casting between machine scalars with the
705 /// `as` operator, which admits narrowing and precision loss.
706 /// Implementers of this trait `AsPrimitive` should behave like a primitive
707 /// numeric type (e.g. a newtype around another primitive), and the
708 /// intended conversion must never fail.
709 ///
710 /// # Examples
711 ///
712 /// ```
713 /// # use num_traits::AsPrimitive;
714 /// let three: i32 = (3.14159265f32).as_();
715 /// assert_eq!(three, 3);
716 /// ```
717 ///
718 /// # Safety
719 ///
720 /// **In Rust versions before 1.45.0**, some uses of the `as` operator were not entirely safe.
721 /// In particular, it was undefined behavior if
722 /// a truncated floating point value could not fit in the target integer
723 /// type ([#10184](https://github.com/rust-lang/rust/issues/10184)).
724 ///
725 /// ```ignore
726 /// # use num_traits::AsPrimitive;
727 /// let x: u8 = (1.04E+17).as_(); // UB
728 /// ```
729 ///
730 pub trait AsPrimitive<T>: 'static + Copy
731 where
732     T: 'static + Copy,
733 {
734     /// Convert a value to another, using the `as` operator.
as_(self) -> T735     fn as_(self) -> T;
736 }
737 
738 macro_rules! impl_as_primitive {
739     (@ $T: ty => $(#[$cfg:meta])* impl $U: ty ) => {
740         $(#[$cfg])*
741         impl AsPrimitive<$U> for $T {
742             #[inline] fn as_(self) -> $U { self as $U }
743         }
744     };
745     (@ $T: ty => { $( $U: ty ),* } ) => {$(
746         impl_as_primitive!(@ $T => impl $U);
747     )*};
748     ($T: ty => { $( $U: ty ),* } ) => {
749         impl_as_primitive!(@ $T => { $( $U ),* });
750         impl_as_primitive!(@ $T => { u8, u16, u32, u64, u128, usize });
751         impl_as_primitive!(@ $T => { i8, i16, i32, i64, i128, isize });
752     };
753 }
754 
755 impl_as_primitive!(u8 => { char, f32, f64 });
756 impl_as_primitive!(i8 => { f32, f64 });
757 impl_as_primitive!(u16 => { f32, f64 });
758 impl_as_primitive!(i16 => { f32, f64 });
759 impl_as_primitive!(u32 => { f32, f64 });
760 impl_as_primitive!(i32 => { f32, f64 });
761 impl_as_primitive!(u64 => { f32, f64 });
762 impl_as_primitive!(i64 => { f32, f64 });
763 impl_as_primitive!(u128 => { f32, f64 });
764 impl_as_primitive!(i128 => { f32, f64 });
765 impl_as_primitive!(usize => { f32, f64 });
766 impl_as_primitive!(isize => { f32, f64 });
767 impl_as_primitive!(f32 => { f32, f64 });
768 impl_as_primitive!(f64 => { f32, f64 });
769 impl_as_primitive!(char => { char });
770 impl_as_primitive!(bool => {});
771