Merge pull request #39 from jofas/explicitly-typed-macros

Explicit equivalents for every macro and doc enhancements

CHANGELOG.md

@@ -14,6 +14,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * `hashbrown::hash_set` macro
 
+* `hashbrown::hash_set_e` macro
+
+* `binary_heap_e` macro
+
+* `btree_set_e` macro
+
+* `hash_set_e` macro
+
+* `vec_no_clone_e` macro
+
 ### Changed
 
 * Explicitly typed map macros: keys also cast now (before only values were 

README.md

@@ -22,6 +22,8 @@ let hello = hash_map! {
     "de" => "Hallo",
     "fr" => "Bonjour",
     "es" => "Hola",
+    "cat" => "Hola",
+    "🌍" => "👋",
 };
 ```
 

src/_std.rs

@@ -12,6 +12,7 @@
 ///     "de" => "Auf Wiedersehen",
 ///     "fr" => "Au revoir",
 ///     "es" => "Adios",
+///     "cat" => "Adéu",
 /// };
 /// ```
 ///
@@ -22,8 +23,9 @@ macro_rules! hash_map {
     };
 }
 
-/// Explicitly typed equivalent of [`hash_map!`], suitable for
-/// [trait object values](crate#explicitly-typed-values-for-trait-objects).
+/// Explicitly typed equivalent of [`hash_map!`].
+///
+/// See the [explicity typed macros](crate#explicitly-typed-macros) section.
 ///
 /// # Examples
 ///
@@ -38,6 +40,7 @@ macro_rules! hash_map {
 ///     "de" => &"Auf Wiedersehen",
 ///     "fr" => &"Au revoir",
 ///     "es" => &"Adios",
+///     "cat" => &"Adéu",
 /// };
 ///
 /// println!("{:?}", goodbye);
@@ -64,6 +67,7 @@ macro_rules! hash_map_e {
 ///     "de" => "Auf Wiedersehen",
 ///     "fr" => "Au revoir",
 ///     "es" => "Adios",
+///     "cat" => "Adéu",
 /// };
 /// ```
 ///
@@ -74,8 +78,9 @@ macro_rules! btree_map {
     };
 }
 
-/// Explicitly typed equivalent of [`btree_map!`], suitable for
-/// [trait object values](crate#explicitly-typed-values-for-trait-objects).
+/// Explicitly typed equivalent of [`btree_map!`].
+///
+/// See the [explicity typed macros](crate#explicitly-typed-macros) section.
 ///
 /// # Examples
 ///
@@ -90,6 +95,7 @@ macro_rules! btree_map {
 ///     "de" => &"Auf Wiedersehen",
 ///     "fr" => &"Au revoir",
 ///     "es" => &"Adios",
+///     "cat" => &"Adéu",
 /// };
 /// ```
 ///
@@ -121,6 +127,31 @@ macro_rules! hash_set {
     };
 }
 
+/// Explicitly typed equivalent of [`hash_set!`].
+///
+/// See the [explicity typed macros](crate#explicitly-typed-macros) section.
+///
+/// # Examples
+///
+/// ```rust
+/// use std::collections::HashSet;
+///
+/// use map_macro::hash_set_e;
+///
+/// enum Foo { A, B, C, D }
+///
+/// let x: HashSet<u8> = hash_set_e! { Foo::A, Foo::B, Foo::C, Foo::C, Foo::D };
+///
+/// assert_eq!(x.len(), 4);
+/// ```
+///
+#[macro_export]
+macro_rules! hash_set_e {
+    {$($v: expr),* $(,)?} => {
+        ::std::collections::HashSet::from([$($v as _,)*])
+    };
+}
+
 /// Macro for creating a [`BTreeSet`](::std::collections::BTreeSet).
 ///
 /// Syntactic sugar for [`BTreeSet::from`](::std::collections::BTreeSet::from).
@@ -142,6 +173,31 @@ macro_rules! btree_set {
     };
 }
 
+/// Explicitly typed equivalent of [`btree_set!`].
+///
+/// See the [explicity typed macros](crate#explicitly-typed-macros) section.
+///
+/// # Examples
+///
+/// ```rust
+/// use std::collections::BTreeSet;
+///
+/// use map_macro::btree_set_e;
+///
+/// enum Foo { A, B, C, D }
+///
+/// let x: BTreeSet<u8> = btree_set_e! { Foo::A, Foo::B, Foo::C, Foo::C, Foo::D };
+///
+/// assert_eq!(x.len(), 4);
+/// ```
+///
+#[macro_export]
+macro_rules! btree_set_e {
+    {$($v: expr),* $(,)?} => {
+        ::std::collections::BTreeSet::from([$($v as _,)*])
+    };
+}
+
 /// Macro for creating a [`VecDeque`](::std::collections::VecDeque).
 ///
 /// Follows the same syntax as the [`vec!`](::std::vec!) macro.
@@ -173,8 +229,9 @@ macro_rules! vec_deque {
     };
 }
 
-/// Explicitly typed equivalent of [`vec_deque!`], suitable for
-/// [trait object values](crate#explicitly-typed-values-for-trait-objects).
+/// Explicitly typed equivalent of [`vec_deque!`].
+///
+/// See the [explicity typed macros](crate#explicitly-typed-macros) section.
 ///
 /// # Examples
 ///
@@ -237,8 +294,9 @@ macro_rules! linked_list {
     };
 }
 
-/// Explicitly typed equivalent of [`linked_list!`], suitable for
-/// [trait object values](crate#explicitly-typed-values-for-trait-objects).
+/// Explicitly typed equivalent of [`linked_list!`].
+///
+/// See the [explicity typed macros](crate#explicitly-typed-macros) section.
 ///
 /// # Examples
 ///
@@ -301,6 +359,41 @@ macro_rules! binary_heap {
     };
 }
 
+/// Explicitly typed equivalent of [`binary_heap!`].
+///
+/// See the [explicity typed macros](crate#explicitly-typed-macros) section.
+///
+/// # Examples
+///
+/// ```
+/// use std::collections::BinaryHeap;
+///
+/// use map_macro::binary_heap_e;
+///
+/// enum Foo { A, B, C, D }
+///
+/// let v: BinaryHeap<u8> = binary_heap_e![Foo::A, Foo::B, Foo::C, Foo::D];
+/// let v: BinaryHeap<u8> = binary_heap_e![Foo::A; 4];
+/// ```
+///
+#[macro_export]
+macro_rules! binary_heap_e {
+    {$v: expr; $c: expr} => {
+        {
+            let mut bh = ::std::collections::BinaryHeap::with_capacity($c);
+
+            for _ in 0..$c {
+                bh.push($v as _);
+            }
+
+            bh
+        }
+    };
+    {$($v: expr),* $(,)?} => {
+        ::std::collections::BinaryHeap::from([$($v as _,)*])
+    };
+}
+
 /// Version of the [`vec!`](::std::vec!) macro where the value does not have to implement [`Clone`].
 ///
 /// Useful for unclonable types or where `Clone` is exerting undesired behaviour.
@@ -439,6 +532,7 @@ macro_rules! binary_heap {
 #[macro_export]
 macro_rules! vec_no_clone {
     {$v: expr; $c: expr} => {
+
         {
             let mut vec = Vec::with_capacity($c);
 
@@ -455,3 +549,38 @@ macro_rules! vec_no_clone {
         }
     };
 }
+
+/// Explicitly typed equivalent of [`vec_no_clone!`].
+///
+/// See the [explicity typed macros](crate#explicitly-typed-macros) section.
+///
+/// # Examples
+///
+/// ```
+/// use std::fmt::Display;
+///
+/// use map_macro::vec_no_clone_e;
+///
+/// let v: Vec<&dyn Display> = vec_no_clone_e![&0; 4];
+/// ```
+///
+#[macro_export]
+macro_rules! vec_no_clone_e {
+    {$v: expr; $c: expr} => {
+
+        {
+            let mut vec = Vec::with_capacity($c);
+
+            for _ in 0..$c {
+                vec.push($v as _);
+            }
+
+            vec
+        }
+    };
+    {$($v: expr),* $(,)?} => {
+        {
+            vec![$($v as _),*]
+        }
+    };
+}

src/hashbrown.rs

@@ -1,6 +1,21 @@
 //! Macros for initializing [`hashbrown`] maps and sets.
 //!
-//! # Supported versions of `hashbrown`
+//! # Example
+//!
+//! ```
+//! use map_macro::hashbrown::hash_map;
+//!
+//! let hello = hash_map! {
+//!     "en" => "Hello",
+//!     "de" => "Hallo",
+//!     "fr" => "Bonjour",
+//!     "es" => "Hola",
+//!     "cat" => "Hola",
+//!     "🌍" => "👋",
+//! };
+//! ```
+//!
+//! # Supported Versions of `hashbrown`
 //!
 //! As of writing this, up to the current `hashbrown` version `0.14` **all**
 //! versions of `hashbrown` are supported.
@@ -15,9 +30,10 @@
 //! macros from this module would break for that new version.
 //!
 //! **Note:** to be compatible with all versions of `hashbrown` at once, this
-//! crate doesn't re-export `hashbrown`, which means that if you rename
-//! `hashbrown` in your dependencies, the macros from this module won't be able
-//! to import the needed types resulting in a compile-time error.
+//! crate doesn't re-export `hashbrown`.
+//! That means that (I) you need to specify it as a dependency yourself and
+//! (II) you can't rename it or the macros from this module won't be able to
+//! import the needed types, resulting in a compile-time error.
 //!
 
 /// Macro for creating a [`HashMap`](::hashbrown::HashMap).
@@ -34,6 +50,7 @@
 ///     "de" => "Auf Wiedersehen",
 ///     "fr" => "Au revoir",
 ///     "es" => "Adios",
+///     "cat" => "Adéu",
 /// };
 /// ```
 ///
@@ -45,8 +62,9 @@ macro_rules! __hb_hash_map {
     };
 }
 
-/// Explicitly typed equivalent of [`hash_map!`](self::hash_map), suitable for
-/// [trait object values](crate#explicitly-typed-values-for-trait-objects).
+/// Explicitly typed equivalent of [`hash_map!`](self::hash_map).
+///
+/// See the [explicity typed macros](crate#explicitly-typed-macros) section.
 ///
 /// # Examples
 ///
@@ -62,6 +80,7 @@ macro_rules! __hb_hash_map {
 ///     "de" => &"Auf Wiedersehen",
 ///     "fr" => &"Au revoir",
 ///     "es" => &"Adios",
+///     "cat" => &"Adéu",
 /// };
 ///
 /// println!("{:?}", goodbye);
@@ -97,6 +116,32 @@ macro_rules! __hb_hash_set {
     };
 }
 
+/// Explicitly typed equivalent of [`hash_set!`](self::hash_set).
+///
+/// See the [explicity typed macros](crate#explicitly-typed-macros) section.
+///
+/// # Examples
+///
+/// ```rust
+/// use hashbrown::HashSet;
+///
+/// use map_macro::hashbrown::hash_set_e;
+///
+/// enum Foo { A, B, C, D }
+///
+/// let x: HashSet<u8> = hash_set_e! { Foo::A, Foo::B, Foo::C, Foo::C, Foo::D };
+///
+/// assert_eq!(x.len(), 4);
+/// ```
+///
+#[doc(hidden)]
+#[macro_export]
+macro_rules! __hb_hash_set_e {
+    {$($v: expr),* $(,)?} => {
+        <::hashbrown::HashSet::<_> as ::core::iter::FromIterator<_>>::from_iter([$($v as _,)*])
+    };
+}
+
 #[doc(inline)]
 pub use __hb_hash_map as hash_map;
 
@@ -105,3 +150,6 @@ pub use __hb_hash_map_e as hash_map_e;
 
 #[doc(inline)]
 pub use __hb_hash_set as hash_set;
+
+#[doc(inline)]
+pub use __hb_hash_set_e as hash_set_e;