Merge pull request #1327 from YBoy-git/collection_tools_refactoring

NOT READY : (collection_tools) : Refactoring

module/core/collection_tools/Cargo.toml

@@ -42,15 +42,13 @@ default = [
   "prelude",
   "collection_constructors",
   "collection_into_constructors",
-  "collection_std",
 ]
 
 full = [
   "enabled",
   "prelude",
   "collection_constructors",
   "collection_into_constructors",
-  "collection_std",
 ]
 
 enabled = []
@@ -60,9 +58,7 @@ prelude = []
 collection_constructors = []
 # Collection constructors, using `into()` under the hood, like `into_hmap!( "key" => "val" )`
 collection_into_constructors = []
-# STD collection for no_std.
-collection_std = []
-# qqq : is this feature used? seems not. if yes, what is it responsible for? discuss
+# qqq : is this feature used? seems not. if yes, what is it responsible for? discuss -- not needed, removed
 
 [dependencies]
 

module/core/collection_tools/Readme.md

@@ -77,7 +77,7 @@ You can do
 
 <!-- // zzz : aaa : rid off `#[ cfg( not( feature = "use_alloc" ) ) ]` -- Rid of by not relying on std -->
 ```rust
-# #[ cfg( all( feature = "enabled", feature = "collection_std" ) ) ]
+# #[ cfg( feature = "enabled" ) ]
 # #[ cfg( any( feature = "use_alloc", not( feature = "no_std" ) ) ) ]
 # {
 use collection_tools::HashSet;

module/core/collection_tools/src/collections.rs

@@ -0,0 +1,32 @@
+/// Not meant to be called directly.
+#[ doc( hidden ) ]
+#[ macro_export( local_inner_macros ) ]
+macro_rules! count
+{
+  ( @single $( $x : tt )* ) => ( () );
+
+  (
+    @count $( $rest : expr ),*
+  )
+  =>
+  (
+    < [ () ] >::len( &[ $( count!( @single $rest ) ),* ] )
+  );
+}
+
+/// [BTreeMap] macros
+pub mod bmap;
+/// [BTreeSet] macros
+pub mod bset;
+/// [BinaryHeap] macros
+pub mod heap;
+/// [HashMap] macros
+pub mod hmap;
+/// [HashSet] macros
+pub mod hset;
+/// [LinkedList] macros
+pub mod list;
+/// [Vec] macros
+pub mod vec;
+/// [VecDeque] macros
+pub mod vecd;

module/core/collection_tools/src/collections/bmap.rs

@@ -0,0 +1,168 @@
+/// Creates a `BTreeMap` from a list of key-value pairs.
+///
+/// The `bmap` macro facilitates the convenient creation of a `BTreeMap` with initial elements.
+///
+/// # Origin
+///
+/// This collection is reexported from `alloc`.
+///
+/// # Syntax
+///
+/// The macro can be called with a comma-separated list of key-value pairs. A trailing comma is optional.
+///
+/// ```rust
+/// # use collection_tools::{ BTreeMap, bmap };
+/// // BTreeMap of &str to i32
+/// let map1 = bmap!( "one" => 1, "two" => 2, "three" => 3 );
+///
+/// // BTreeMap of &str to &str
+/// let map2 = bmap!{ "name" => "value" };
+///
+/// // With trailing comma
+/// let map3 = bmap!( 1 => "one", 2 => "two", 3 => "three", );
+/// ```
+///
+/// # Parameters
+///
+/// - `$( $key:expr => $value:expr ),* $( , )?`: A comma-separated list of key-value pairs to insert into the `BTreeMap`.
+/// Each key and value can be of any type that implements the `Into< K >` and `Into< V >` traits, where `K` and `V` are the
+/// types stored in the `BTreeMap` as keys and values, respectively.
+///
+/// # Returns
+///
+/// Returns a `BTreeMap` containing all the specified key-value pairs. The map's capacity is
+/// automatically determined based on the number of elements provided.
+///
+/// # Example
+///
+/// Basic usage with string slices and integer values:
+///
+/// ```rust
+/// # use collection_tools::{ BTreeMap, bmap };
+/// let map = bmap!( "one" => 1, "two" => 2, "three" => 3 );
+/// assert_eq!( map.get( "one" ), Some( &1 ) );
+/// assert_eq!( map.get( "two" ), Some( &2 ) );
+/// assert_eq!( map.get( "three" ), Some( &3 ) );
+/// ```
+///
+/// # Example
+///
+/// Creating a `BTreeMap` of integers to string slices from literals:
+///
+/// ```rust
+/// # use collection_tools::{ BTreeMap, bmap };
+/// let numbers = bmap!( 1 => "one", 2 => "two", 3 => "three" );
+/// assert_eq!( numbers.get( &1 ), Some( &"one" ) );
+/// assert_eq!( numbers.get( &2 ), Some( &"two" ) );
+/// assert_eq!( numbers.get( &3 ), Some( &"three" ) );
+/// ```
+///
+#[ cfg( feature = "collection_constructors" ) ]
+#[ macro_export( local_inner_macros ) ]
+macro_rules! bmap
+{
+  (
+    $( $key : expr => $value : expr ),* $( , )?
+  )
+  =>
+  {{
+    let mut _map = collection_tools::BTreeMap::new();
+    $(
+      let _ = _map.insert( $key , $value );
+    )*
+    _map
+  }};
+}
+
+/// Creates a `BTreeMap` from a list of key-value pairs.
+///
+/// The `into_bmap` macro facilitates the convenient creation of a `BTreeMap` with initial elements.
+/// Keys and values passed to the macro are automatically converted into the map's key and value types
+/// using `.into()`, enabling the use of literals or values of different, but convertible types.
+///
+/// Note: The `into_bmap` macro relies on the `.into()` method to convert each key and value into the target types
+/// of the `BTreeMap`. This means that the keys and values must be compatible with the `Into< K >` and `Into< V >` traits
+/// for the key type `K` and value type `V` used in the `BTreeMap`. Also, this means that sometimes you must specify the type of collection's items.
+///
+/// # Origin
+///
+/// This collection is reexported from `alloc`.
+///
+/// # Syntax
+///
+/// The macro can be called with a comma-separated list of key-value pairs. A trailing comma is optional.
+///
+/// ```rust
+/// # use collection_tools::{ BTreeMap, into_bmap };
+/// // BTreeMap of &str to i32
+/// let map1 : BTreeMap< &str, i32 > = into_bmap!( "one" => 1, "two" => 2, "three" => 3 );
+///
+/// // BTreeMap of String to String
+/// let map2 : BTreeMap< String, String > = into_bmap!{ "name" => "value" };
+///
+/// // With trailing comma
+/// let map3 : BTreeMap< i32, &str > = into_bmap!( 1 => "one", 2 => "two", 3 => "three", );
+/// ```
+///
+/// # Parameters
+///
+/// - `$( $key:expr => $value:expr ),* $( , )?`: A comma-separated list of key-value pairs to insert into the `BTreeMap`.
+/// Each key and value can be of any type that implements the `Into< K >` and `Into< V >` traits, where `K` and `V` are the
+/// types stored in the `BTreeMap` as keys and values, respectively.
+///
+/// # Returns
+///
+/// Returns a `BTreeMap` containing all the specified key-value pairs. The map's capacity is
+/// automatically determined based on the number of elements provided.
+///
+/// # Example
+///
+/// Basic usage with string slices and integer values:
+///
+/// ```rust
+/// # use collection_tools::{ BTreeMap, into_bmap };
+/// let map : BTreeMap< &str, i32 > = into_bmap!( "one" => 1, "two" => 2, "three" => 3 );
+/// assert_eq!( map.get( "one" ), Some( &1 ) );
+/// assert_eq!( map.get( "two" ), Some( &2 ) );
+/// assert_eq!( map.get( "three" ), Some( &3 ) );
+/// ```
+///
+/// # Example
+///
+/// Using with different types that implement `Into< K >` and `Into< V >`:
+///
+/// ```rust
+/// # use collection_tools::{ BTreeMap, into_bmap };
+/// let months : BTreeMap< String, i32 > = into_bmap!( "January" => 1, "February" => 2, "March" => 3 );
+/// assert_eq!( months.get( &"January".to_string() ), Some( &1 ) );
+/// assert_eq!( months.get( &"February".to_string() ), Some( &2 ) );
+/// ```
+///
+/// # Example
+///
+/// Creating a `BTreeMap` of integers to strings from literals:
+///
+/// ```rust
+/// # use collection_tools::{ BTreeMap, into_bmap };
+/// let numbers : BTreeMap< i32, String > = into_bmap!( 1 => "one", 2 => "two", 3 => "three" );
+/// assert_eq!( numbers.get( &1 ), Some( &"one".to_string() ) );
+/// assert_eq!( numbers.get( &2 ), Some( &"two".to_string() ) );
+/// assert_eq!( numbers.get( &3 ), Some( &"three".to_string() ) );
+/// ```
+///
+#[ cfg( feature = "collection_into_constructors" ) ]
+#[ macro_export( local_inner_macros ) ]
+macro_rules! into_bmap
+{
+  (
+    $( $key : expr => $value : expr ),* $( , )?
+  )
+  =>
+  {{
+    let mut _map = collection_tools::BTreeMap::new();
+    $(
+      let _ = _map.insert( Into::into( $key ), Into::into( $value ) );
+    )*
+    _map
+  }};
+}

module/core/collection_tools/src/collections/bset.rs

@@ -0,0 +1,154 @@
+/// Creates a `BTreeSet` from a list of elements.
+///
+/// The `bset` macro allows for convenient creation of a `BTreeSet` with initial elements.
+///
+/// # Origin
+///
+/// This collection is reexported from `alloc`.
+///
+/// # Syntax
+///
+/// The macro can be called with a comma-separated list of elements. A trailing comma is optional.
+///
+/// ```rust
+/// # use collection_tools::{ BTreeSet, bset };
+/// // BTreeSet of &str
+/// let set1 = bset!( "a", "b", "c" );
+///
+/// // With trailing comma
+/// let set3 = bset!( 1, 2, 3, );
+/// ```
+///
+/// # Parameters
+///
+/// - `$( $key:expr ),* $( , )?`: A comma-separated list of elements to insert into the `BTreeSet`.
+/// Each element can be of any type that implements the `Into<T>` trait, where `T` is the
+/// type stored in the `BTreeSet`.
+///
+/// # Returns
+///
+/// Returns a `BTreeSet` containing all the specified elements. The capacity of the set is
+/// automatically determined based on the number of elements provided.
+///
+/// # Example
+///
+/// Basic usage with string slices:
+///
+/// ```rust
+/// # use collection_tools::{ BTreeSet, bset };
+/// let set = bset!( "one", "two", "three" );
+/// assert!( set.contains( "one" ) );
+/// assert!( set.contains( "two" ) );
+/// assert!( set.contains( "three" ) );
+/// assert_eq!( set.len(), 3 );
+/// ```
+///
+#[ cfg( feature = "collection_constructors" ) ]
+#[ macro_export( local_inner_macros ) ]
+macro_rules! bset
+{
+  (
+    $( $key : expr ),* $( , )?
+  )
+  =>
+  {{
+    let mut _set = collection_tools::BTreeSet::new();
+    $(
+      _set.insert( $key );
+    )*
+    _set
+  }};
+}
+
+/// Creates a `BTreeSet` from a list of elements.
+///
+/// The `into_bset` macro allows for convenient creation of a `BTreeSet` with initial elements.
+/// Elements passed to the macro are automatically converted into the set's element type
+/// using `.into()`, facilitating the use of literals or values of different, but convertible types.
+///
+/// Note: The `into_bset` macro relies on the `.into()` method to convert each element into the target type
+/// of the `BTreeSet`. This means that the elements must be compatible with the `Into<T>` trait for the
+/// type `T` used in the `BTreeSet`. Also, this means that sometimes you must specify the type of collection's items.
+///
+/// # Origin
+///
+/// This collection is reexported from `alloc`.
+///
+/// # Syntax
+///
+/// The macro can be called with a comma-separated list of elements. A trailing comma is optional.
+///
+/// ```rust
+/// # use collection_tools::{ BTreeSet, into_bset };
+/// // BTreeSet of &str
+/// let set1 : BTreeSet< &str > = into_bset!( "a", "b", "c" );
+///
+/// // BTreeSet of String
+/// let set2 : BTreeSet< String > = into_bset!{ "a".to_string(), "b", "c" };
+///
+/// // With trailing comma
+/// let set3 : BTreeSet< i32 > = into_bset!( 1, 2, 3, );
+/// ```
+///
+/// # Parameters
+///
+/// - `$( $key:expr ),* $( , )?`: A comma-separated list of elements to insert into the `BTreeSet`.
+/// Each element can be of any type that implements the `Into<T>` trait, where `T` is the
+/// type stored in the `BTreeSet`.
+///
+/// # Returns
+///
+/// Returns a `BTreeSet` containing all the specified elements. The capacity of the set is
+/// automatically determined based on the number of elements provided.
+///
+/// # Example
+///
+/// Basic usage with string slices:
+///
+/// ```rust
+/// # use collection_tools::{ BTreeSet, into_bset };
+/// let set  : BTreeSet< &str > = into_bset!( "one", "two", "three" );
+/// assert!( set.contains( "one" ) );
+/// assert!( set.contains( "two" ) );
+/// assert!( set.contains( "three" ) );
+/// assert_eq!( set.len(), 3 );
+/// ```
+///
+/// # Example
+///
+/// Using with different types that implement `Into<T>`:
+///
+/// ```rust
+/// # use collection_tools::{ BTreeSet, into_bset };
+/// let numbers : BTreeSet< i32 > = into_bset!( 1, 2, 3 );
+/// assert!( numbers.contains( &1 ) );
+/// assert!( numbers.contains( &2 ) );
+/// assert!( numbers.contains( &3 ) );
+/// ```
+///
+/// # Example
+///
+/// Creating a `BTreeSet` of `String` from string literals:
+///
+/// ```rust
+/// # use collection_tools::{ BTreeSet, into_bset };
+/// let s : BTreeSet< String > = into_bset!{ "value" };
+/// assert!( s.contains( "value" ) );
+/// ```
+///
+#[ cfg( feature = "collection_into_constructors" ) ]
+#[ macro_export( local_inner_macros ) ]
+macro_rules! into_bset
+{
+  (
+    $( $key : expr ),* $( , )?
+  )
+  =>
+  {{
+    let mut _set = collection_tools::BTreeSet::new();
+    $(
+      _set.insert( Into::into( $key ) );
+    )*
+    _set
+  }};
+}