Crate collection_tools

Module :: collection_tools

General purpose tools to manipulate collections( containers like Vec/HashMap/HashSet… ).

Basic Use Case :: Variadic Constructors for Collections

This module encompasses a suite of meta-tools designed to enhance Rust’s collection handling, most notably through the inclusion of variadic constructors. A prime example is the hmap! macro, which facilitates the ergonomic construction of HashMap instances. These constructors allow for the intuitive and concise initialization of collections, mirroring the simplicity found in other programming languages.

Consider the following example, which demonstrates the use of the hmap! macro to effortlessly create a HashMap:

use collection_tools::*;

let meta_map = hmap! { 3 => 13 };

// it is identical to `hashbrown::HashMap` if `use_alloc` feature is on, otherwise `std::collections::HashMap`
let mut std_map = collection_tools::HashMap::new();

std_map.insert( 3, 13 );
assert_eq!( meta_map, std_map );

Another example, this time, into_bset!, providing you a BTreeSet:

use collection_tools::*;

let meta_set = bset! { 3, 13 };

// this `BTreeSet` is just a reexport from `alloc`,
// so it can be used in the same places as `alloc/std::BTreeSet`
let mut std_set = collection_tools::BTreeSet::new();

std_set.insert( 13 );
std_set.insert( 3 );
assert_eq!( meta_set, std_set );

Another example with llist!:

use collection_tools::*;

let meta_list : LinkedList< i32 > = llist! { 3, 13 };

// this `LinkedList` is just a reexport from `alloc`,
// so it can be used in the same places as `alloc/std::LinkedList`
let mut meta_list = collection_tools::LinkedList::new();

meta_list.push_front( 13 );
meta_list.push_front( 3 );
assert_eq!( meta_list, meta_list );

Basic Use Case :: no_std HashSet / HashMap

When implementing a no_std ( !use_std ) environment with the use_alloc feature in your Rust project, you’ll encounter a challenge: collections like Vec are imported differently depending on the availability of the std library. Moreover, to use data structures such as HashSet or HashMap in a no_std context, it’s necessary to depend on third-party crates, as these are not provided by the alloc crate directly. This crate aims to simplify the process of designing Rust libraries or applications that require these collections in a no_std environment, offering a more streamlined approach to working with dynamic data structures without the standard library.

You can do

use collection_tools::HashSet;

let mut vec : HashSet< i32 > = HashSet::new();
vec.insert( 1 );
assert_eq!( vec.contains( &1 ), true );

Instead of

Click to see

#[ cfg( all( feature = "no_std", feature = "use_alloc" ) ) ]
use hashbrown::HashSet; // a `no_std` replacement for `HashSet`
#[ cfg( not( feature = "no_std" ) ) ]
use std::collections::HashSet;

let mut vec : HashSet< i32 > = HashSet::new();
vec.insert( 1 );
assert_eq!( vec.contains( &1 ), true );

Basic Use Case :: no_std HashSet / HashMap

The crate has two classes of macros: strict macros (the one we covered), which require that all collection members are of the same type; and more “relaxed” macros, that use under the hood Into trait to cast to a certain type. They can be accessed by prepending into_ to name of a macro (into_vec, into_bmap, etc).

While strict macros require you to have all members of the same type, more relaxed macros often require you to specify the desired type. So there’s no a clear winner. Choose the right one for each situation separately.

For example:

use std::borrow::Cow;
let vec : Vec< String > = collection_tools::into_vec!( "&str", "String".to_string(), Cow::from( "Cow" ) );

Each strict macro has its relaxed counterpart.

Collections being used

So what’s the deal with collection_tools::<collection>?

Nothing really fancy. We just reuse collections from alloc (same as std).

But not all collections are available in alloc crate. For now, the exceptions are HashMap and HashSet. This leads to the fact that we can’t use them in no_std environment. How did we solve this? By using those collections from hashbrown crate whenever no_std feature is enabled. You can found more details on origin of a collection on its documentation page.

MORE Examples

If you are feeling confused about the syntax you should use for a macro, you can visit its documentation. It is saturated with different examples, so hopefully you’ll not be stuck.

To add to your project

cargo add collection_tools

Try out from the repository

git clone https://github.com/Wandalen/wTools
cd wTools
cd examples/container_tools_trivial
cargo run

Modules

binary_heap

std::collections::BinaryHeap macros

btree_map

std::collections::BTreeMap macros

btree_set

std::collections::BTreeSet macros

collection

Module containing all collection macros

dependency

Namespace with dependencies.

exposed

Exposed namespace of the module.

hash_map

std::collections::HashMap macros

hash_set

std::collections::HashSet macros

linked_list

std::collections::LinkedList macros

orphan

Parented namespace of the module.

own

Own namespace of the module.

prelude

Prelude to use essentials: use my_module::prelude::*.

vec_deque

std::collections::VecDeque macros

vector

Vec macros

Macros

bmap

Creates a BTreeMap from a list of key-value pairs.

bset

Creates a BTreeSet from a list of elements.

deque

Creates a VecDeque from a list of elements.

dlist

Creates a Vec from a list of elements.

heap

Creates a BinaryHeap from a list of elements.

hmap

Creates a HashMap from a list of key-value pairs.

hset

Creates a HashSet from a list of elements.

into_bmap

Creates a BTreeMap from a list of key-value pairs.

into_bset

Creates a BTreeSet from a list of elements.

into_dlist

Creates a Vec from a list of elements.

into_heap

Creates a BinaryHeap from a list of elements.

into_hmap

Creates a HashMap from a list of key-value pairs.

into_hset

Creates a HashSet from a list of elements.

into_llist

Creates a LinkedList from a llist of elements.

into_vec

Creates a Vec from a list of elements.

into_vecd

Creates a VecDeque from a list of elements.

llist

Creates a LinkedList from a llist of elements.

vec

Creates a Vec from a list of elements.

Structs

BTreeMap

An ordered map based on a B-Tree.

BTreeSet

An ordered set based on a B-Tree.

BinaryHeap

A priority queue implemented with a binary heap.

Bmap

An ordered map based on a B-Tree.

Bset

An ordered set based on a B-Tree.

Deque

A double-ended queue implemented with a growable ring buffer.

Dlist

A contiguous growable array type, written as Vec<T>, short for ‘vector’.

HashMap

A hash map implemented with quadratic probing and SIMD lookup.

HashSet

A hash set implemented as a HashMap where the value is ().

Hmap

A hash map implemented with quadratic probing and SIMD lookup.

Hset

A hash set implemented as a HashMap where the value is ().

LinkedList

A doubly-linked list with owned nodes.

Llist

A doubly-linked list with owned nodes.

Map

A hash map implemented with quadratic probing and SIMD lookup.

Set

A hash set implemented as a HashMap where the value is ().

Vec

A contiguous growable array type, written as Vec<T>, short for ‘vector’.

VecDeque

A double-ended queue implemented with a growable ring buffer.