lit2 1.0.9

#![warn(missing_docs)]
#![warn(unused_results)]
#![doc(html_root_url="https://docs.rs/lit2/1/")]

//! Macros for container literals with specific type.
//!
//! ```
//! use lit2::*;
//!
//! # fn main() {
//! let map = hashmap!{
//!     "a" => 1,
//!     "b" => 2,
//! };
//! 
//! let set = set!{1, 2, 3};
//! # }
//! ```
//!
//! The **lit2** crate uses `=>` syntax to separate the key and value for the
//! mapping macros. It is also possible to use the `:` separator, but the keys cannot
//! be expressions.
//!
//! Note that rust macros are flexible in which brackets you use for the invocation.
//! You can use them as `hashmap!{}` or `hashmap![]` or `hashmap!()`.
//!
//! Generic container macros already exist elsewhere, so those are not provided
//! here at the moment.

#[macro_export(local_inner_macros)]
/// Create a **HashMap** from a list of key-value pairs
///
/// ## Example
///
/// ```
/// use lit2::*;
/// # fn main() {
///
/// let map = hashmap!{
///     "a" => 1,
///     "b" => 2,
/// };
/// assert_eq!(map["a"], 1);
/// assert_eq!(map["b"], 2);
/// assert_eq!(map.get("c"), None);
/// # }
/// ```
macro_rules! hashmap {
    (@single $($x:tt)*) => (());
    (@count $($rest:expr),*) => (<[()]>::len(&[$(hashmap!(@single $rest)),*]));

    ($($key:expr => $value:expr,)+) => { hashmap!($($key => $value),+) };
    ($($key:expr => $value:expr),*) => {
        {
            let _cap = hashmap!(@count $($key),*);
            let mut _map = ::std::collections::HashMap::with_capacity(_cap);
            $(
                let _ = _map.insert($key, $value);
            )*
            _map
        }
    };
}

#[macro_export(local_inner_macros)]
/// Create a **HashMap** with `specific type` from a list of key-value pairs
///
/// ## Example
///
/// ```
/// use maplit::*;
/// use std::collections::HashMap;
/// struct Foo;
/// struct Bar;
///
/// trait Zoo {}
///
/// impl Zoo for Foo {}
/// impl Zoo for Bar {}
///
/// # fn main() {
/// let map = hashmap_ex!(
///     HashMap<_, Box<dyn Zoo>>,
///     {
///         "a" => Box::new(Foo {}),
///         "b" => Box::new(Bar {}),
///     }
/// );
/// # }
/// ```
macro_rules! hashmap_ex {
    (@single $($x:tt)*) => (());
    (@count $($rest:expr),*) => (<[()]>::len(&[$(hashmap_ex!(@single $rest)),*]));

    ($t:ty, { $($key:expr => $value:expr,)+ } ) => { hashmap_ex!($t, { $($key => $value),+ }) };
    ($t:ty, { $($key:expr => $value:expr),* } ) => {
        {
            let _cap = hashmap_ex!(@count $($key),*);
            let mut _map: $t = ::std::collections::HashMap::with_capacity(_cap);
            $(
                let _ = _map.insert($key, $value);
            )*
            _map
        }
    };
}

#[macro_export(local_inner_macros)]
/// A slightly more concise version of "hashmap!" for the concision-minded. Create a **HashMap** from a list of key-value pairs
///
/// ## Example
///
/// ```
/// use lit2::*;
/// # fn main() {
///
/// let map = map!{
///     "a": 1,
///     "b": 2,
/// };
/// assert_eq!(map["a"], 1);
/// assert_eq!(map["b"], 2);
/// assert_eq!(map.get("c"), None);
/// # }
/// ```
macro_rules! map{
    ( $($key:tt : $val:expr),* $(,)? ) =>{{
        #[allow(unused_mut)]
        let mut map = ::std::collections::HashMap::with_capacity(hashmap!(@count $($key),* ));
        $(
            #[allow(unused_parens)]
            let _ = map.insert($key, $val);
        )*
        map
    }};
    (@replace $_t:tt $e:expr ) => { $e };
    (@count $($t:tt)*) => { <[()]>::len(&[$( map!(@replace $t ()) ),*]) }
}

#[macro_export(local_inner_macros)]
/// Alias of "map!". Create a **HashMap** from a list of key-value pairs
///
/// ## Example
///
/// ```
/// use lit2::*;
/// # fn main() {
///
/// let map = dict!{
///     "a": 1,
///     "b": 2,
/// };
/// assert_eq!(map["a"], 1);
/// assert_eq!(map["b"], 2);
/// assert_eq!(map.get("c"), None);
/// # }
/// ```
macro_rules! dict{
    ( $($key:tt : $val:expr),* $(,)? ) =>{{
        #[allow(unused_mut)]
        let mut map = ::std::collections::HashMap::with_capacity(hashmap!(@count $($key),* ));
        $(
            #[allow(unused_parens)]
            let _ = map.insert($key, $val);
        )*
        map
    }};
    (@replace $_t:tt $e:expr ) => { $e };
    (@count $($t:tt)*) => { <[()]>::len(&[$( map!(@replace $t ()) ),*]) }
}

/// Create a **HashSet** from a list of elements.
///
/// ## Example
///
/// ```
/// use lit2::*;
/// # fn main() {
///
/// let set = hashset!{"a", "b"};
/// assert!(set.contains("a"));
/// assert!(set.contains("b"));
/// assert!(!set.contains("c"));
/// # }
/// ```
#[macro_export(local_inner_macros)]
macro_rules! hashset {
    (@single $($x:tt)*) => (());
    (@count $($rest:expr),*) => (<[()]>::len(&[$(hashset!(@single $rest)),*]));

    ($($key:expr,)+) => { hashset!($($key),+) };
    ($($key:expr),*) => {
        {
            let _cap = hashset!(@count $($key),*);
            let mut _set = ::std::collections::HashSet::with_capacity(_cap);
            $(
                let _ = _set.insert($key);
            )*
            _set
        }
    };
}

/// Alias of "hashset!". Create a **HashSet** from a list of elements.
///
/// ## Example
///
/// ```
/// use lit2::*;
/// # fn main() {
///
/// let set = set!{"a", "b"};
/// assert!(set.contains("a"));
/// assert!(set.contains("b"));
/// assert!(!set.contains("c"));
/// # }
/// ```
#[macro_export(local_inner_macros)]
macro_rules! set {
    (@single $($x:tt)*) => (());
    (@count $($rest:expr),*) => (<[()]>::len(&[$(hashset!(@single $rest)),*]));

    ($($key:expr,)+) => { hashset!($($key),+) };
    ($($key:expr),*) => {
        {
            let _cap = hashset!(@count $($key),*);
            let mut _set = ::std::collections::HashSet::with_capacity(_cap);
            $(
                let _ = _set.insert($key);
            )*
            _set
        }
    };
}

#[macro_export(local_inner_macros)]
/// Create a **BTreeMap** from a list of key-value pairs
///
/// ## Example
///
/// ```
/// use lit2::*;
/// # fn main() {
///
/// let map = btreemap!{
///     "a" => 1,
///     "b" => 2,
/// };
/// assert_eq!(map["a"], 1);
/// assert_eq!(map["b"], 2);
/// assert_eq!(map.get("c"), None);
/// # }
/// ```
macro_rules! btreemap {
    // trailing comma case
    ($($key:expr => $value:expr,)+) => (btreemap!($($key => $value),+));

    ( $($key:expr => $value:expr),* ) => {
        {
            let mut _map = ::std::collections::BTreeMap::new();
            $(
                let _ = _map.insert($key, $value);
            )*
            _map
        }
    };
}

#[macro_export(local_inner_macros)]
/// Create a **BTreeSet** from a list of elements.
///
/// ## Example
///
/// ```
/// use lit2::*;
/// # fn main() {
///
/// let set = btreeset!{"a", "b"};
/// assert!(set.contains("a"));
/// assert!(set.contains("b"));
/// assert!(!set.contains("c"));
/// # }
/// ```
macro_rules! btreeset {
    ($($key:expr,)+) => (btreeset!($($key),+));

    ( $($key:expr),* ) => {
        {
            let mut _set = ::std::collections::BTreeSet::new();
            $(
                _set.insert($key);
            )*
            _set
        }
    };
}

/// Identity function. Used as the fallback for conversion.
#[doc(hidden)]
pub fn __id<T>(t: T) -> T { t }

/// Macro that converts the keys or key-value pairs passed to another lit2
/// macro. The default conversion is to use the [`Into`] trait, if no
/// custom conversion is passed.
///
/// The syntax is:
///
/// `convert_args!(` `keys=` *function* `,` `values=` *function* `,`
///     *macro_name* `!(` [ *key* => *value* [, *key* => *value* ... ] ] `))`
///
/// Here *macro_name* is any other lit2 macro and either or both of the
/// explicit `keys=` and `values=` parameters can be omitted.
///
/// [`Into`]: https://doc.rust-lang.org/std/convert/trait.Into.html
///
/// **Note** To use `convert_args`, the macro that is being wrapped
/// must itself be brought into the current scope with `#[macro_use]` or `use`.
///
/// # Examples
///
/// ```
/// use lit2::*;
/// # fn main() {
///
/// use std::collections::HashMap;
/// use std::collections::BTreeSet;
///
/// // a. Use the default conversion with the Into trait.
/// // Here this converts both the key and value string literals to `String`,
/// // but we need to specify the map type exactly!
///
/// let map1: HashMap<String, String> = convert_args!(hashmap!(
///     "a" => "b",
///     "c" => "d",
/// ));
///
/// // b. Specify an explicit custom conversion for the keys. If we don't specify
/// // a conversion for the values, they are not converted at all.
///
/// let map2 = convert_args!(keys=String::from, hashmap!(
///     "a" => 1,
///     "c" => 2,
/// ));
///
/// // Note: map2 is a HashMap<String, i32>, but we didn't need to specify the type
/// let _: HashMap<String, i32> = map2;
///
/// // c. convert_args! works with all the lit2 macros -- and macros from other
/// // crates that have the same "signature".
/// // For example, btreeset and conversion from &str to Vec<u8>.
///
/// let set: BTreeSet<Vec<u8>> = convert_args!(btreeset!(
///     "a", "b", "c", "d", "a", "e", "f",
/// ));
/// assert_eq!(set.len(), 6);
///
///
/// # }
/// ```
#[macro_export(local_inner_macros)]
macro_rules! convert_args {
    (keys=$kf:expr, $macro_name:ident !($($k:expr),* $(,)*)) => {
        $macro_name! { $(($kf)($k)),* }
    };
    (keys=$kf:expr, values=$vf:expr, $macro_name:ident !($($k:expr),* $(,)*)) => {
        $macro_name! { $(($kf)($k)),* }
    };
    (keys=$kf:expr, values=$vf:expr, $macro_name:ident !( $($k:expr => $v:expr),* $(,)*)) => {
        $macro_name! { $(($kf)($k) => ($vf)($v)),* }
    };
    (keys=$kf:expr, $macro_name:ident !($($rest:tt)*)) => {
        convert_args! {
            keys=$kf, values=$crate::__id,
            $macro_name !(
                $($rest)*
            )
        }
    };
    (values=$vf:expr, $macro_name:ident !($($rest:tt)*)) => {
        convert_args! {
            keys=$crate::__id, values=$vf,
            $macro_name !(
                $($rest)*
            )
        }
    };
    ($macro_name:ident ! $($rest:tt)*) => {
        convert_args! {
            keys=::std::convert::Into::into, values=::std::convert::Into::into,
            $macro_name !
            $($rest)*
        }
    };
}

#[test]
fn test_hashmap() {
    use std::collections::HashMap;
    use std::collections::HashSet;
    let names = hashmap!{
        1 => "one",
        2 => "two",
    };
    assert_eq!(names.len(), 2);
    assert_eq!(names[&1], "one");
    assert_eq!(names[&2], "two");
    assert_eq!(names.get(&3), None);

    let empty: HashMap<i32, i32> = hashmap!{};
    assert_eq!(empty.len(), 0);

    let _nested_compiles = hashmap!{
        1 => hashmap!{0 => 1 + 2,},
        2 => hashmap!{1 => 1,},
    };

    let _: HashMap<String, i32> = convert_args!(keys=String::from, hashmap!(
        "one" => 1,
        "two" => 2,
    ));

    let _: HashMap<String, i32> = convert_args!(keys=String::from, values=__id, hashmap!(
        "one" => 1,
        "two" => 2,
    ));

    let names: HashSet<String> = convert_args!(hashset!(
        "one",
        "two",
    ));
    assert!(names.contains("one"));
    assert!(names.contains("two"));

    let lengths: HashSet<usize> = convert_args!(keys=str::len, hashset!(
        "one",
        "two",
    ));
    assert_eq!(lengths.len(), 1);

    let _no_trailing: HashSet<usize> = convert_args!(keys=str::len, hashset!(
        "one",
        "two"
    ));
}

#[test]
fn test_hashmap_ex() {
    use std::collections::HashMap;
    let names: HashMap<i32, &str> = hashmap_ex!{
        HashMap<i32, &str>,
        {
            1 => "one",
            2 => "two",
        }
    };
    assert_eq!(names.len(), 2);
    assert_eq!(names[&1], "one");
    assert_eq!(names[&2], "two");
    assert_eq!(names.get(&3), None);

    let empty: HashMap<i32, i32> = hashmap_ex!{
        HashMap<i32, i32>, {}
    };
    assert_eq!(empty.len(), 0);

    let _nested_compiles = hashmap_ex!{
        HashMap<i32, _>,
        {
            1 => hashmap!{0 => 1 + 2,},
            2 => hashmap!{1 => 1,},
        }
    };

    struct Foo(i32);
    struct Bar(i32);

    trait Ret {
        fn ret(&self) -> i32;
    }

    impl Ret for Foo {
        fn ret(&self) -> i32 { self.0 }
    }
    impl Ret for Bar {
        fn ret(&self) -> i32 { self.0 }
    }

    let func_map = hashmap_ex!(
        HashMap<_, Box<dyn Ret>>,
        {
            "foo" => Box::new(Foo(1)),
            "bar" => Box::new(Bar(2)),
        }
    );

    assert_eq!(func_map["foo"].ret(), 1);
    assert_eq!(func_map["bar"].ret(), 2);
}

#[test]
fn test_btreemap() {
    use std::collections::BTreeMap;
    let names = btreemap!{
        1 => "one",
        2 => "two",
    };
    assert_eq!(names.len(), 2);
    assert_eq!(names[&1], "one");
    assert_eq!(names[&2], "two");
    assert_eq!(names.get(&3), None);

    let empty: BTreeMap<i32, i32> = btreemap!{};
    assert_eq!(empty.len(), 0);

    let _nested_compiles = btreemap!{
        1 => btreemap!{0 => 1 + 2,},
        2 => btreemap!{1 => 1,},
    };
}