Skip to content

Latest commit

 

History

History
331 lines (261 loc) · 42.3 KB

README.md

File metadata and controls

331 lines (261 loc) · 42.3 KB
Raw

API Artifacts License Build

A Swiss Army knife for for Rust standard library collections.

Enable direct functional-style collection manipulation without the usual iterator boilerplate and provides various utility operations.

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

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

Build

Requirements

Setup

cargo install cargo-make

Test

makers build

Benchmark

makers 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

at your option.