small_num/

lib.rs

//! Small numbers can be used to describe some constrained data.
//! For example, a number of alignment bytes:
//! 
//! ```rust
//! use small_num::small_num;
//! 
//! small_num! {
//!     #[derive(Clone, Debug, PartialEq, Copy, Eq, PartialOrd, Ord, Hash)]
//!     pub enum AlignBytes: [1, 2, 4];
//! }
//! 
//! let bytes = AlignBytes::new(2);
//! assert_eq!(bytes, Some(AlignBytes::_2));
//! assert_eq!(AlignBytes::new(3), None);
//! assert_eq!(std::mem::size_of::<Option<AlignBytes>>(), 1);
//! ```
//! 
//! Or an integer valid for a spicific range:
//! 
//! ```rust
//! use small_num::small_num;
//! 
//! small_num! {
//!     #[derive(Clone, Debug, PartialEq, Copy, Eq, PartialOrd, Ord, Hash)]
//!     pub enum U7: ..128;
//! }
//! 
//! assert_eq!(U7::new(0), Some(U7::_0));
//! assert_eq!(U7::new(50), Some(U7::_50));
//! assert_eq!(U7::new(127), Some(U7::_127));
//! assert_eq!(U7::new(128), None);
//! assert_eq!(std::mem::size_of::<Option<U7>>(), 1);
//! ```
//! 
//! It can be casted to an integer with `as` operator:
//! 
//! ```rust
//! use small_num::small_num;
//! 
//! small_num! {
//!     #[derive(Clone, Debug, PartialEq, Copy, Eq, PartialOrd, Ord, Hash)]
//!     pub enum Num50to100: 50..=100;
//! }
//! 
//! assert_eq!(Num50to100::new(69).unwrap() as u32, 69);
//! ```
//! 
//! Where clause can be used to derive supported traits:
//! 
//! ```rust
//! use small_num::small_num;
//! 
//! small_num! {
//!     #[derive(Clone)]
//!     pub enum MySmallNumber: [0, 42, 121]
//!     where
//!         Self: Debug + Serialize;
//! }
//! ```
//! 
//! Supported traits in the where clause:
//! 
//! - `Debug` - prints your small number as a regular number
//! - `Serialize` (with `serde` feature)
//! - `Deserialize` (with `serde` feature)
//! 
//! ## Crate features
//! 
//! - `serde` enables `Serialize` and `Deserialize` derivation.



pub mod util {
    pub use seq_macro::seq;
    pub use paste::paste;

    #[cfg(feature = "serde")]
    pub use serde;
}



/// Macro used to create small numbers. It comes in two forms: as a range
/// and a list of valid values.
/// 
/// ## List form
/// 
/// It creates enum with given list of values.
/// 
/// ```rust,ignore
/// small_num! {
///     pub enum ListNum: [<list of values>];
/// }
/// ```
/// 
/// ## Range form
/// 
/// It creates enum with all numbers from given range.
/// 
/// ```rust,ignore
/// small_num! {
///     pub enum RangeNum: <START>..<END>;
/// }
/// ```
/// 
/// ## `small-num` custom traits derivation
/// 
/// ```rust,ignore
/// small_num! {
///     pub enum Num: [10, 9, 8, 7];
///     where
///         Self: <TRAIT_1> + <TRAIT_2>;
/// }
/// ```
#[macro_export]
macro_rules! small_num {
    (
        $( #[$meta:meta] )*
        $vis:vis enum $Name:ident : [ $($value:literal),* $(,)? ]
        $(
            where
                Self: $FirstTrait:ident $( + $TailTraits:ident )*
        )?
        ;
    ) => {
        $crate::util::paste! {
            $( #[$meta] )*
            $vis enum $Name {
                $(
                    [<_ $value>] = $value,
                )*
            }
        }

        $crate::small_num! {
            @derive( $( $FirstTrait, $( $TailTraits, )* )? )
            $Name
        }

        impl $Name {
            #[allow(dead_code)]
            $vis const fn new(value: u32) -> ::core::option::Option<Self> {
                $crate::util::paste! {
                    ::core::option::Option::Some(match value {
                        $(
                            $value => Self::[<_ $value>],
                        )*
                        _ => return ::core::option::Option::None,
                    })
                }
            }

            /// # Safety
            /// 
            /// `value` should be valid.
            #[allow(dead_code)]
            $vis const unsafe fn new_unchecked(value: u32) -> Self {
                $crate::util::paste! {
                    match value {
                        $(
                            $value => Self::[<_ $value>],
                        )*
                        _ => unsafe { ::core::hint::unreachable_unchecked() },
                    }
                }
            }
        }
    };

    (
        $( #[$meta:meta] )*
        $vis:vis enum $Name:ident : $start:literal..$end:literal
        $(
            where
                Self: $FirstTrait:ident $( + $TailTraits:ident )*
        )?
        ;
    ) => {
        $crate::util::seq!(N in $start..$end {
            $( #[$meta] )*
            $vis enum $Name {
                #(
                    _~N = N,
                )*
            }
        });

        $crate::small_num! {
            @derive( $( $FirstTrait, $( $TailTraits, )* )? )
            $Name
        }

        impl $Name {
            #[allow(dead_code)]
            $vis const fn new(value: u32) -> ::core::option::Option<Self> {
                $crate::util::seq!(N in $start..$end {
                    ::core::option::Option::Some(match value {
                        #( N => Self::_~N, )*
                        _ => return ::core::option::Option::None,
                    })
                })
            }

            /// # Safety
            /// 
            /// `value` should be valid.
            #[allow(dead_code)]
            $vis const unsafe fn new_unchecked(value: u32) -> Self {
                $crate::util::seq!(N in $start..$end {
                    match value {
                        #( N => Self::_~N, )*
                        _ => unsafe { ::core::hint::unreachable_unchecked() },
                    }
                })
            }
        }
    };

    (
        $( #[$meta:meta] )*
        $vis:vis enum $Name:ident : $start:literal..=$end:literal
        $(
            where
                Self: $FirstTrait:ident $( + $TailTrait:ident )*
        )?
        ;
    ) => {
        $crate::util::seq!(N in $start..=$end {
            $( #[$meta] )*
            $vis enum $Name {
                #(
                    _~N = N,
                )*
            }
        });

        $crate::small_num! {
            @derive( $( $FirstTrait, $( $TailTraits, )* )? )
            $Name
        }

        impl $Name {
            #[allow(dead_code)]
            $vis const fn new(value: u32) -> ::core::option::Option<Self> {
                $crate::util::seq!(N in $start..=$end {
                    ::core::option::Option::Some(match value {
                        #( N => Self::_~N, )*
                        _ => return None,
                    })
                })
            }

            /// # Safety
            /// 
            /// `value` should be valid.
            #[allow(dead_code)]
            $vis const unsafe fn new_unchecked(value: u32) -> Self {
                $crate::util::seq!(N in $start..=$end {
                    match value {
                        #( N => Self::_~N, )*
                        _ => ::core::hint::unreachable_unchecked(),
                    }
                })
            }
        }
    };

    (
        $( #[$meta:meta] )*
        $vis:vis enum $Name:ident : ..$end:literal
        $(
            where
                Self: $FirstTrait:ident $( + $TailTraits:ident )*
        )?
        ;
    ) => {
        $crate::small_num! {
            $( #[$meta] )*
            $vis enum $Name : 0..$end
            $(
                where
                    Self: $FirstTrait $( + $TailTraits )*
            )?
            ;
        }
    };

    (
        $( #[$meta:meta] )*
        $vis:vis enum $Name:ident : ..=$end:literal
        $(
            where
                Self: $FirstTrait:ident $( + $TailTraits:ident )*
        )?
        ;
    ) => {
        $crate::small_num! {
            $( #[$meta] )*
            $vis enum $Name : 0..=$end
            $(
                where
                    Self: $FirstTrait $( + $TailTraits:ident )*
            )?
            ;
        }
    };

    (
        $( #[$meta:meta] )*
        $vis:vis enum $Name:ident : $( $start:literal )? ..
        $(
            where
                Self: $FirstTrait:ident $( + $TailTraits:ident )*
        )?
        ;
    ) => {
        ::core::compile_error!("RageTo in range_num is unsupported");
    };

    (
        @derive(Serialize)
        $Name:ident
    ) => {
        #[cfg(not(feature = "serde"))]
        compile_error!(concat!(
            "Enable `serde` feature to derive `Serialize` for `",
            stringify!($Name),
            '`',
        ));

        #[cfg(feature = "serde")]
        impl $crate::util::serde::Serialize for $Name {
            fn serialize<S>(&self, serializer: S) -> ::core::result::Result<S::Ok, S::Error>
            where
                S: $crate::util::serde::Serializer,
            {
                serializer.serialize_u32(self.clone() as u32)
            }
        }
    };

    (
        @derive(Deserialize)
        $Name:ident
    ) => {
        #[cfg(not(feature = "serde"))]
        compile_error!(concat!(
            "Enable `serde` feature to derive `Deserialize` for `",
            stringify!($Name),
            '`',
        ));

        #[cfg(feature = "serde")]
        $crate::util::paste! {
            impl<'de> $crate::util::serde::Deserialize<'de> for $Name {
                fn deserialize<D>(deserializer: D) -> ::core::result::Result<Self, D::Error>
                where
                    D: $crate::util::serde::Deserializer<'de>,
                {
                    #[doc(hidden)]
                    struct [<__ $Name Visitor>];

                    const __EXPECTING_STR: &str = concat!("expecting valid small-num '", stringify!($Name), '\'');

                    impl<'de> $crate::util::serde::de::Visitor<'de> for [<__ $Name Visitor>] {
                        type Value = $Name;

                        fn expecting(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
                            f.write_str(__EXPECTING_STR)
                        }

                        fn visit_u32<E>(self, v: u32) -> ::core::result::Result<Self::Value, E>
                        where
                            E: $crate::util::serde::de::Error,
                        {
                            $Name::new(v).ok_or(E::invalid_value(
                                $crate::util::serde::de::Unexpected::Unsigned(v.into()),
                                &__EXPECTING_STR,
                            ))
                        }

                        fn visit_u64<E>(self, v: u64) -> ::core::result::Result<Self::Value, E>
                        where
                            E: $crate::util::serde::de::Error,
                        {
                            let v = u32::try_from(v).map_err(|_| E::invalid_value(
                                $crate::util::serde::de::Unexpected::Unsigned(v),
                                &__EXPECTING_STR,
                            ))?;

                            self.visit_u32(v)
                        }
                    }

                    deserializer.deserialize_u32([<__ $Name Visitor>])
                }
            }
        }
    };

    (
        @derive(Debug)
        $Name:ident
    ) => {
        impl ::core::fmt::Debug for $Name {
            fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
                write!(f, "{}", self.clone() as u32)
            }
        }
    };

    (
        @derive( $Trait:ident )
        $Name:ident
    ) => {
        compile_error!(concat!(
            "Trait '",
            stringify!($Trait),
            "' can not be derived for '",
            stringify!($Name),
            "' by crate small-num.",
        ));
    };

    (
        @derive( $( $Trait:ident ),* $(,)? )
        $Name:ident
    ) => {
        $(
            $crate::small_num! {
                @derive( $Trait )
                $Name
            }
        )*
    };
}



#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_list() {
        small_num! {
            #[derive(Clone, PartialEq, Copy)]
            pub enum ListNum: [1, 2, 4, 8]
            where
                Self: Debug;
        }

        assert_eq!(ListNum::new(1), Some(ListNum::_1));
        assert_eq!(ListNum::new(2), Some(ListNum::_2));
        assert_eq!(ListNum::new(4), Some(ListNum::_4));
        assert_eq!(ListNum::new(8), Some(ListNum::_8));
        assert_eq!(ListNum::new(9), None);
    }

    #[test]
    fn test_range() {
        small_num! {
            #[derive(Clone, PartialEq, Copy)]
            pub enum RangeNum: 10..15
            where
                Self: Debug;
        }

        assert_eq!(RangeNum::new(10), Some(RangeNum::_10));
        assert_eq!(RangeNum::new(11), Some(RangeNum::_11));
        assert_eq!(RangeNum::new(16), None);
    }

    #[test]
    fn debug() {
        small_num! {
            #[derive(Clone)]
            pub enum SmallNum: [1, 2, 3]
            where
                Self: Debug;
        }

        assert_eq!(format!("{:?}", SmallNum::_2), "2");
    }
}