Revision control
Copy as Markdown
Other Tools
//! `num_conv` is a crate to convert between integer types without using `as` casts. This provides
//! better certainty when refactoring, makes the exact behavior of code more explicit, and allows
//! using turbofish syntax.
#![no_std]
/// Anonymously import all extension traits.
///
/// This allows you to use the methods without worrying about polluting the namespace or importing
/// them individually.
///
/// ```rust
/// use num_conv::prelude::*;
/// ```
pub mod prelude {
pub use crate::{CastSigned as _, CastUnsigned as _, Extend as _, Truncate as _};
}
mod sealed {
pub trait Integer {}
macro_rules! impl_integer {
($($t:ty)*) => {$(
impl Integer for $t {}
)*};
}
impl_integer! {
u8 u16 u32 u64 u128 usize
i8 i16 i32 i64 i128 isize
}
pub trait ExtendTargetSealed<T> {
fn extend(self) -> T;
}
pub trait TruncateTargetSealed<T> {
fn truncate(self) -> T;
}
}
/// Cast to a signed integer of the same size.
///
/// This trait is implemented for all integers. Unsigned to signed casts are equivalent to
/// `0.wrapping_add_signed(value)`, while signed to signed casts are an identity conversion.
///
/// ```rust
/// # use num_conv::CastSigned;
/// assert_eq!(u8::MAX.cast_signed(), -1_i8);
/// assert_eq!(u16::MAX.cast_signed(), -1_i16);
/// assert_eq!(u32::MAX.cast_signed(), -1_i32);
/// assert_eq!(u64::MAX.cast_signed(), -1_i64);
/// assert_eq!(u128::MAX.cast_signed(), -1_i128);
/// assert_eq!(usize::MAX.cast_signed(), -1_isize);
/// ```
///
/// ```rust
/// # use num_conv::CastSigned;
/// assert_eq!(0_i8.cast_signed(), 0_i8);
/// assert_eq!(0_i16.cast_signed(), 0_i16);
/// assert_eq!(0_i32.cast_signed(), 0_i32);
/// assert_eq!(0_i64.cast_signed(), 0_i64);
/// assert_eq!(0_i128.cast_signed(), 0_i128);
/// assert_eq!(0_isize.cast_signed(), 0_isize);
/// ```
pub trait CastSigned: sealed::Integer {
/// The signed integer type with the same size as `Self`.
type Signed;
/// Cast an integer to the signed integer of the same size.
fn cast_signed(self) -> Self::Signed;
}
/// Cast to an unsigned integer of the same size.
///
/// This trait is implemented for all integers. Signed to unsigned casts are equivalent to
/// `0.wrapping_add_unsigned(value)`, while unsigned to unsigned casts are an identity conversion.
///
/// ```rust
/// # use num_conv::CastUnsigned;
/// assert_eq!((-1_i8).cast_unsigned(), u8::MAX);
/// assert_eq!((-1_i16).cast_unsigned(), u16::MAX);
/// assert_eq!((-1_i32).cast_unsigned(), u32::MAX);
/// assert_eq!((-1_i64).cast_unsigned(), u64::MAX);
/// assert_eq!((-1_i128).cast_unsigned(), u128::MAX);
/// assert_eq!((-1_isize).cast_unsigned(), usize::MAX);
/// ```
///
/// ```rust
/// # use num_conv::CastUnsigned;
/// assert_eq!(0_u8.cast_unsigned(), 0_u8);
/// assert_eq!(0_u16.cast_unsigned(), 0_u16);
/// assert_eq!(0_u32.cast_unsigned(), 0_u32);
/// assert_eq!(0_u64.cast_unsigned(), 0_u64);
/// assert_eq!(0_u128.cast_unsigned(), 0_u128);
/// assert_eq!(0_usize.cast_unsigned(), 0_usize);
/// ```
pub trait CastUnsigned: sealed::Integer {
/// The unsigned integer type with the same size as `Self`.
type Unsigned;
/// Cast an integer to the unsigned integer of the same size.
fn cast_unsigned(self) -> Self::Unsigned;
}
/// A type that can be used with turbofish syntax in [`Extend::extend`].
///
/// It is unlikely that you will want to use this trait directly. You are probably looking for the
/// [`Extend`] trait.
pub trait ExtendTarget<T>: sealed::ExtendTargetSealed<T> {}
/// A type that can be used with turbofish syntax in [`Truncate::truncate`].
///
/// It is unlikely that you will want to use this trait directly. You are probably looking for the
/// [`Truncate`] trait.
pub trait TruncateTarget<T>: sealed::TruncateTargetSealed<T> {}
/// Extend to an integer of the same size or larger, preserving its value.
///
/// ```rust
/// # use num_conv::Extend;
/// assert_eq!(0_u8.extend::<u16>(), 0_u16);
/// assert_eq!(0_u16.extend::<u32>(), 0_u32);
/// assert_eq!(0_u32.extend::<u64>(), 0_u64);
/// assert_eq!(0_u64.extend::<u128>(), 0_u128);
/// ```
///
/// ```rust
/// # use num_conv::Extend;
/// assert_eq!((-1_i8).extend::<i16>(), -1_i16);
/// assert_eq!((-1_i16).extend::<i32>(), -1_i32);
/// assert_eq!((-1_i32).extend::<i64>(), -1_i64);
/// assert_eq!((-1_i64).extend::<i128>(), -1_i128);
/// ```
pub trait Extend: sealed::Integer {
/// Extend an integer to an integer of the same size or larger, preserving its value.
fn extend<T>(self) -> T
where
Self: ExtendTarget<T>;
}
impl<T: sealed::Integer> Extend for T {
fn extend<U>(self) -> U
where
T: ExtendTarget<U>,
{
sealed::ExtendTargetSealed::extend(self)
}
}
/// Truncate to an integer of the same size or smaller, preserving the least significant bits.
///
/// ```rust
/// # use num_conv::Truncate;
/// assert_eq!(u16::MAX.truncate::<u8>(), u8::MAX);
/// assert_eq!(u32::MAX.truncate::<u16>(), u16::MAX);
/// assert_eq!(u64::MAX.truncate::<u32>(), u32::MAX);
/// assert_eq!(u128::MAX.truncate::<u64>(), u64::MAX);
/// ```
///
/// ```rust
/// # use num_conv::Truncate;
/// assert_eq!((-1_i16).truncate::<i8>(), -1_i8);
/// assert_eq!((-1_i32).truncate::<i16>(), -1_i16);
/// assert_eq!((-1_i64).truncate::<i32>(), -1_i32);
/// assert_eq!((-1_i128).truncate::<i64>(), -1_i64);
/// ```
pub trait Truncate: sealed::Integer {
/// Truncate an integer to an integer of the same size or smaller, preserving the least
/// significant bits.
fn truncate<T>(self) -> T
where
Self: TruncateTarget<T>;
}
impl<T: sealed::Integer> Truncate for T {
fn truncate<U>(self) -> U
where
T: TruncateTarget<U>,
{
sealed::TruncateTargetSealed::truncate(self)
}
}
macro_rules! impl_cast_signed {
($($($from:ty),+ => $to:ty;)*) => {$($(
const _: () = assert!(
core::mem::size_of::<$from>() == core::mem::size_of::<$to>(),
concat!(
"cannot cast ",
stringify!($from),
" to ",
stringify!($to),
" because they are different sizes"
)
);
impl CastSigned for $from {
type Signed = $to;
fn cast_signed(self) -> Self::Signed {
self as _
}
}
)+)*};
}
macro_rules! impl_cast_unsigned {
($($($from:ty),+ => $to:ty;)*) => {$($(
const _: () = assert!(
core::mem::size_of::<$from>() == core::mem::size_of::<$to>(),
concat!(
"cannot cast ",
stringify!($from),
" to ",
stringify!($to),
" because they are different sizes"
)
);
impl CastUnsigned for $from {
type Unsigned = $to;
fn cast_unsigned(self) -> Self::Unsigned {
self as _
}
}
)+)*};
}
macro_rules! impl_extend {
($($from:ty => $($to:ty),+;)*) => {$($(
const _: () = assert!(
core::mem::size_of::<$from>() <= core::mem::size_of::<$to>(),
concat!(
"cannot extend ",
stringify!($from),
" to ",
stringify!($to),
" because ",
stringify!($from),
" is larger than ",
stringify!($to)
)
);
impl sealed::ExtendTargetSealed<$to> for $from {
fn extend(self) -> $to {
self as _
}
}
impl ExtendTarget<$to> for $from {}
)+)*};
}
macro_rules! impl_truncate {
($($($from:ty),+ => $to:ty;)*) => {$($(
const _: () = assert!(
core::mem::size_of::<$from>() >= core::mem::size_of::<$to>(),
concat!(
"cannot truncate ",
stringify!($from),
" to ",
stringify!($to),
" because ",
stringify!($from),
" is smaller than ",
stringify!($to)
)
);
impl sealed::TruncateTargetSealed<$to> for $from {
fn truncate(self) -> $to {
self as _
}
}
impl TruncateTarget<$to> for $from {}
)+)*};
}
impl_cast_signed! {
u8, i8 => i8;
u16, i16 => i16;
u32, i32 => i32;
u64, i64 => i64;
u128, i128 => i128;
usize, isize => isize;
}
impl_cast_unsigned! {
u8, i8 => u8;
u16, i16 => u16;
u32, i32 => u32;
u64, i64 => u64;
u128, i128 => u128;
usize, isize => usize;
}
impl_extend! {
u8 => u8, u16, u32, u64, u128, usize;
u16 => u16, u32, u64, u128, usize;
u32 => u32, u64, u128;
u64 => u64, u128;
u128 => u128;
usize => usize;
i8 => i8, i16, i32, i64, i128, isize;
i16 => i16, i32, i64, i128, isize;
i32 => i32, i64, i128;
i64 => i64, i128;
i128 => i128;
isize => isize;
}
impl_truncate! {
u8, u16, u32, u64, u128, usize => u8;
u16, u32, u64, u128, usize => u16;
u32, u64, u128 => u32;
u64, u128 => u64;
u128 => u128;
usize => usize;
i8, i16, i32, i64, i128, isize => i8;
i16, i32, i64, i128, isize => i16;
i32, i64, i128 => i32;
i64, i128 => i64;
i128 => i128;
isize => isize;
}