Practical extensions for standard Rust collections.

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

Inspired by

• Rust Collections
• Scala Collections
• Haskell Collections
• Python Collections
• Qt Collections
• Itertools
• More Itertools

Build

Requirements

• Rust 1.85+

Test

cargo test

Benchmark

cargo bench

Contributing

Please feel free to open an issue or a pull request with questions, ideas, features, improvements or fixes.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.