smallint/src/lib.rs

#![deny(missing_docs)]
#![warn(clippy::all)]

//! A crate for small integer optimization. Provides the [`SmallInt`] type. When possible this will
//! inline an integer and store it on the stack if that integer is small. However, for larger values, 
//! this will be instead stored on the heap as a pointer to a `u32` slice, a length, and a sign.

#[cfg(feature="num-bigint")]
use num_bigint::BigInt;

#[cfg(feature="num-bigint")]
use num_bigint::Sign;

use core::mem::ManuallyDrop;

/// An error that occurred when processing a SmallInt.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SmallIntError {
    /// Conversion error when converting from SmallInt to other integer types.
    ConversionError,
}

impl std::error::Error for SmallIntError {}

impl core::fmt::Display for SmallIntError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        let Self::ConversionError = self;
        write!(f, "Error converting integer to SmallInt.")
    }
}


/// An integer-like type that will store small integers up to `i64` inline. Larger integers are
/// represented as `BigInt` types, which are stored on the heap.
#[derive(Clone, PartialEq, Eq)]
pub enum SmallInt {
    /// An integer stored inline.
    Inline(i128),
    /// A larger integer stored on the heap. This value is represented in base 2<sup>32</sup> and
    /// ordered least significant digit first. Also stored with the size and sign of the integer.
    ///
    /// It is assumed that values stored on the heap are larger than the maximum value of inline
    /// integers.
    Heap((*mut u32, isize))
}

impl Drop for SmallInt {
    fn drop(&mut self) {
        if let Self::Heap((r, s)) = self {
            let size = usize::try_from(s.abs()).unwrap();
            let slice = unsafe { core::slice::from_raw_parts_mut(*r, size) };
            unsafe { std::mem::drop(Box::from_raw(slice)) }
        }
    }

}

macro_rules! int_impl {
    ($itype:ty) => {
        impl From<$itype> for SmallInt {
            fn from(a: $itype) -> Self {
                SmallInt::Inline(i128::from(a))
            }
        }

        impl TryFrom<SmallInt> for $itype {

            type Error = SmallIntError;

            fn try_from(s: SmallInt) -> Result<Self, Self::Error> {
                match s {
                    SmallInt::Inline(i) => <$itype>::try_from(i).map_err(|_| SmallIntError::ConversionError),
                    SmallInt::Heap((_, _)) => Err(SmallIntError::ConversionError),
                }
            }
        }
    }
}

int_impl!(u8);
int_impl!(u16);
int_impl!(u32);
int_impl!(u64);
int_impl!(i8);
int_impl!(i16);
int_impl!(i32);
int_impl!(i64);
int_impl!(i128);


impl From<u128> for SmallInt {
    fn from(a: u128) -> Self {
        match i128::try_from(a) {
            Ok(i) => Self::Inline(i),
            Err(_) => {
                let mut v = a;
                let mut vec = Vec::with_capacity(4);
                while v != 0 {
                    vec.push(v as u32);

                    v >>= 32;
                }
                let mut slice = ManuallyDrop::new(vec.into_boxed_slice());
                SmallInt::Heap((slice.as_mut_ptr(), isize::try_from(slice.len()).unwrap()))
            }
        }
    }
}

impl TryFrom<SmallInt> for u128 {

    type Error = SmallIntError;

    fn try_from(s: SmallInt) -> Result<Self, Self::Error> {
        match s {
            SmallInt::Inline(i) => u128::try_from(i).map_err(|_| SmallIntError::ConversionError),
            SmallInt::Heap((r, s)) => {
                let mut ret: u128 = 0;
                let mut bits = 0;
                let size = usize::try_from(s.abs()).unwrap();
                let slice = unsafe { core::slice::from_raw_parts(r, size) };
                for i in slice {
                    if bits >= 128 {
                        return Err(SmallIntError::ConversionError);
                    }
                    ret |= u128::from(*i) << bits;
                    bits += 32;
                }

                Ok(ret)
            }
        }
    }
}


#[cfg(feature="num-bigint")]
impl From<BigInt> for SmallInt {
    fn from(b: BigInt) -> Self {
        match (&b).try_into() {
            Ok(i) => SmallInt::Inline(i),
            Err(_) => {
                let (sign, vec) = b.to_u32_digits();
                let mut slice = ManuallyDrop::new(vec.into_boxed_slice());
                let size = match sign {
                    Sign::Minus => -isize::try_from(slice.len()).unwrap(),
                    Sign::NoSign => panic!("Shouldn't happen; BigInts which store zero should convert to inline."),
                    Sign::Plus => isize::try_from(slice.len()).unwrap()
                };
                SmallInt::Heap((slice.as_mut_ptr(), size)) }
        }
    }
}

#[cfg(feature="num-bigint")]
impl From<SmallInt> for BigInt {
    fn from(s: SmallInt) -> Self {
        match s {
            SmallInt::Inline(i) => Self::from(i),
            SmallInt::Heap((r, s)) => {
                let size = usize::try_from(s.abs()).unwrap();
                let sign = s.signum();
                let slice = unsafe { core::slice::from_raw_parts(r, size) };
                let bs = match sign {
                    0 => Sign::NoSign,
                    -1 => Sign::Minus,
                    1 => Sign::Plus,
                    _ => panic!("This shouldn't happen; There are only 3 signums."),
                };

                BigInt::new(bs, slice.to_vec())
            }
        }
    }
}

#[cfg(test)]
mod conversion_tests {

    use crate::SmallInt;

    #[cfg(feature="num-bigint")]
    use num_bigint::{BigInt, Sign};

    macro_rules! conversion_tests {
        ($t:ty, $i:ident) => {
            #[test]
            fn $i() {
                let i = <$t>::MAX;
                let s = SmallInt::from(i);
                assert_eq!(<$t>::try_from(s).unwrap(), i);

                let i = <$t>::MIN;
                let s = SmallInt::from(i);
                assert_eq!(<$t>::try_from(s).unwrap(), i);
            }

        }
    }

    conversion_tests!(u8, test_u8);
    conversion_tests!(i8, test_i8);
    conversion_tests!(u16, test_u16);
    conversion_tests!(i16, test_i16);
    conversion_tests!(u32, test_u32);
    conversion_tests!(i32, test_i32);
    conversion_tests!(u64, test_u64);
    conversion_tests!(i64, test_i64);
    conversion_tests!(u128, test_u128);
    conversion_tests!(i128, test_i128);

    #[test]
    #[cfg(feature="num-bigint")]
    fn test_bigint() {
        let i = BigInt::new(Sign::Plus, vec![5, 4, 8, 3, 2, 9, 3]);
        let s = SmallInt::from(i);
        assert_eq!(BigInt::from(s).to_u32_digits(), (Sign::Plus, vec![5, 4, 8, 3, 2, 9, 3]));
    }

}