Crate cantrip

Practical extension methods for Rust standard library collections.

Enables direct functional-style collection manipulation without the usual iterator boilerplate.

Overview

• Equivalents of standard iterator methods are added to standard library collections
• Additional utility methods commonly found in collection libraries are also included
• All methods treat collection instances as immutable although some consume them
• Methods which modify a collection return a new collection instead of an iterator
• Performance is near optimal and overhead is 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.