Crate cantrip 

A Swiss Army Knife for Rust standard library collection types.

Enables direct functional-style collection manipulation without the usual iterator boilerplate and provides many additional operations.

• Enjoy cleaner code with less .into_iter(), .collect() and .clone().
• Leverage non-consuming operations and many convenient utility methods.
• No learning required, use code completion to quickly find a method you need.

Overview

• Existing standard library collections are extended with equivalents of iterator methods
• Additional utility methods commonly found in collection libraries are also included
• Methods which modify a collection return a new collection instead of an iterator
• All methods treat collection instances as immutable, although some consume them
• Standard library method naming conventions are followed as closely as possible
• Performance is near optimal with overhead limited to new collection creation

Functionality

• Searching - Modifying - Filtering - Mapping - Inspecting - Aggregating
• Selecting - Converting - Partitioning - Merging - Sorting - Miscellaneous

Examples

use cantrip::*;

let a = vec![1, 2, 3];

a.fold(0, |r, x| r + x);                 // 6

a.map_ref(|&x| (x, x)).to_map();         // HashMap::from([(1, 1), (2, 2), (3, 3)])

a.flat_map(|x| [x, -x]).sorted();        // vec![-3, -2, -1, 1, 2, 3]

a.filter(|&x| x > 1).to_set();           // HashSet::from([2, 3])

a.group_by(|x| x % 2);                   // HashMap::from([(0, vec![2]), (1, vec![1, 3])])

a.delete(&1).add(2).unique();            // vec![2, 3]

a.substitute_at(0, 4).to_list();         // LinkedList::from([4, 2, 3])

a.position_multi(|&x| x % 2 == 1);       // vec![0, 2]

a.rev().into_iter().to_deque();          // VecDeque::from([3, 2, 1])

Methods

Searching

Method / Collection type	Vec, VecDeque, LinkedList	Slice	HashSet, BTreeSet, BinaryHeap	HashMap, BTreeMap	Consuming
find	*	*	*	*	N
find_map	*		*	*	Y
find_map_ref	*	*	*	*	N
find_position	*	*			N
first	*	*			N
last	*				N
max_by	*	*	*	*	N
max_by_key	*	*	*	*	N
max_of	*	*	*	*	N
min_by	*	*	*	*	N
min_by_key	*	*	*	*	N
min_of	*	*	*	*	N
minmax_by	*	*	*	*	N
minmax_by_key	*	*	*	*	N
minmax_of	*	*	*	*	N
position	*	*			N
position_multi	*	*			N
position_of	*	*			N
position_of_multi	*	*			N
position_sequence	*	*			N
rfind	*	*			N
rposition	*	*			N

Modifying

Method / Collection type	Vec, VecDeque, LinkedList	Slice	HashSet, BTreeSet, BinaryHeap	HashMap, BTreeMap	Consuming
add	*		*	*	Y
add_at	*				Y
add_at_multi	*				Y
add_multi	*		*	*	Y
delete	*		*	*	Y
delete_at	*				Y
delete_at_multi	*				Y
delete_multi	*		*	*	Y
move_at	*				Y
pad_left	*				Y
pad_left_with	*				Y
pad_right	*				Y
pad_right_with	*				Y
rev	*				Y
substitute	*		*	*	Y
substitute_at	*				Y
substitute_at_multi	*				Y
substitute_multi	*		*	*	Y
swap_at	*				Y

Filtering

Method / Collection type	Vec, VecDeque, LinkedList	Slice	HashSet, BTreeSet, BinaryHeap	HashMap, BTreeMap	Consuming
duplicates	*				Y
duplicates_by	*				Y
filter	*		*	*	Y
filter_keys				*	Y
filter_map	*		*	*	Y
filter_map_ref	*		*	*	N
filter_ref	*		*	*	N
filter_values				*	Y
init	*				Y
init_ref		*			Y
intersect	*		*	*	Y
largest	*		*		Y
slice	*				Y
smallest	*		*		Y
skip	*				Y
skip_while	*				Y
skip_ref		*			Y
skip_while_ref		*			Y
step_by	*				Y
take	*				Y
take_while	*				Y
take_ref		*			Y
take_while_ref		*			Y
unique	*				Y
unique_by	*				Y
tail	*				Y
tail_ref		*			N

Mapping

Method / Collection type	Vec, VecDeque, LinkedList	Slice	HashSet, BTreeSet, BinaryHeap	HashMap, BTreeMap	Consuming
coalesce	*				Y
enumerate	*				Y
flat_map	*		*	*	Y
flat_map_ref	*		*	*	N
map	*		*	*	Y
map_ref	*		*	*	N
map_keys				*	Y
map_values				*	Y
map_while	*				N
scan	*				Y
scan_ref	*				N

Inspecting

Method / Collection type	Vec, VecDeque, LinkedList	Slice	HashSet, BTreeSet, BinaryHeap	HashMap, BTreeMap	Consuming
all	*	*	*	*	N
any	*	*	*	*	N
common_prefix_length	*	*			N
common_suffix_length	*	*			N
count_by	*	*	*	*	N
count_unique	*	*		*	N
disjoint	*	*	*	*	N
equivalent	*	*			N
frequencies	*	*			N
frequencies_by	*	*			N
subset	*	*	*	*	N
superset	*	*	*	*	N

Aggregating

Method / Collection type	Vec, VecDeque, LinkedList	Slice	HashSet, BTreeSet, BinaryHeap	HashMap, BTreeMap	Consuming
fold	*		*	*	Y
fold_ref	*	*	*	*	N
group_fold	*		*		Y
group_fold_ref	*	*	*		N
group_reduce	*		*		Y
group_reduce_ref	*	*	*		N
product	*		*		Y
product_keys				*	Y
product_values				*	Y
reduce	*		*	*	Y
reduce_ref	*	*	*	*	N
rfold	*				Y
rfold_ref	*	*			N
sum	*		*		Y
sum_keys				*	Y
sum_values				*	Y

Selecting

Method / Collection type	Vec, VecDeque, LinkedList	Slice	HashSet, BTreeSet, BinaryHeap	HashMap, BTreeMap	Consuming
chunked	*				Y
chunked_by	*				Y
chunked_exact	*				Y
cartesian_product	*				N
combinations	*		*		N
combinations_multi	*				N
powerset	*		*		N
variations	*				N
windowed	*				N
windowed_circular	*				N

Partitioning

Method / Collection type	Vec, VecDeque, LinkedList	Slice	HashSet, BTreeSet, BinaryHeap	HashMap, BTreeMap	Consuming
divide	*				Y
divide_by	*				Y
group_by	*		*		Y
partition	*		*	*	Y
partitions	*		*		N
partition_map	*		*	*	Y
partition_map_ref	*		*	*	N
unzip	*				Y

Merging

Method / Collection type	Vec, VecDeque, LinkedList	Slice	HashSet, BTreeSet, BinaryHeap	HashMap, BTreeMap	Consuming
flat	*		*		Y
interleave	*				Y
interleave_exact	*				Y
intersperse	*				Y
intersperse_with	*				Y
joined	*				N
merge	*				Y
merge_by	*				Y
zip	*				Y
zip_padded	*				Y

Sorting

Method / Collection type	Vec, VecDeque, LinkedList	Slice	HashSet, BTreeSet, BinaryHeap	HashMap, BTreeMap	Consuming
sorted	*				Y
sorted_by	*				Y
sorted_by_cached_key	*				Y
sorted_by_key	*				Y
sorted_unstable	*				Y
sorted_unstable_by	*				Y
sorted_unstable_by_key	*				Y

Converting

Method / Collection type	Vec, VecDeque, LinkedList	Slice	HashSet, BTreeSet, BinaryHeap	HashMap, BTreeMap	Consuming
collect	*		*	*	Y
to_bmap	*		*	*	Y
to_bset	*		*	*	Y
to_heap	*		*	*	Y
to_keys				*	Y
to_list	*		*	*	Y
to_map	*		*	*	Y
to_set	*		*	*	Y
to_values				*	Y
to_vec	*		*	*	Y
to_deque	*		*	*	Y

Miscellaneous

Method / Collection type	Vec, VecDeque, LinkedList	Slice	HashSet, BTreeSet, BinaryHeap	HashMap, BTreeMap	Consuming
fill	*				Y
fill_with	*		*	*	Y
for_each	*	*	*	*	N
repeat	*
unit	*		*	*	Y

Traits

Collection

Non-consuming collection operations.

CollectionTo

Consuming collection operations.

Convert

Conversion operations.

Iterable

Conversion into an Iterator over references.

List

List operations.

Map

Map operations.

Sequence

Ordered collection operations.

SequenceTo

Sequence operations.

Slice

Slice operations.