Crate eclectic [−] [src]
Collection traits for generic programming.
This crate distinguishes three modes of access to a collection, as determined by marker bounds on the methods of each collection trait:
Marker Bound | Enables | Analogous To |
---|---|---|
(none) | Read-only access to items and state | &[T] |
Mut |
Write access to items | &mut [T] |
Own |
Insertion and removal of items | &mut Vec<T> |
These bounds can be combined with each of the collection traits to enable different operations
on the collection. For example, List
on its own provides len
and get
, while
List + Mut
additionally provides get_mut
and swap
, and List + Own
additionally
provides clear
and push
.
Generic code should specify only those bounds that are needed for its operation, but may
specify additional bounds for future compatibility. Generic code should also use the collection
traits with a ?Sized
bound in order to support slices and trait objects whenever possible.
Examples
Insertion sort:
use eclectic::{List, Mut}; fn insertion_sort<L: ?Sized + List + Mut>(list: &mut L) where L::Item: Ord { for i in 1..list.len() { // `len` is defined on `Collection`, a supertrait of `List` let mut j = i; while j > 0 && list.get(j) < list.get(j - 1) { list.swap(j, j - 1); // the `Mut` bound on `L` enables the use of `List::swap` j -= 1; } } } use std::collections::VecDeque; let mut slice = ["c", "b", "a"]; insertion_sort(&mut slice as &mut [_]); assert_eq!(slice, ["a", "b", "c"]); let mut vec = vec!['c', 'b', 'a']; insertion_sort(&mut vec); assert_eq!(vec, ['a', 'b', 'c']); let mut vec_deque: VecDeque<_> = vec![3, 2, 1].into_iter().collect(); insertion_sort(&mut vec_deque); assert!(vec_deque.iter().eq(&[1, 2, 3]));
A Note on Trait Objects
A number of trait methods in this crate return a Box<Iterator>
, which requires unnecessary
heap allocation and opaqueness (e.g. erasure of traits like Clone
and DoubleEndedIterator
).
This is to make up for the (hopefully temporary) inability to define higher-kinded associated
types like:
trait Collection { type Drain<'a>: 'a + Iterator<Item = Self::Item>; fn drain<'a>(&'a mut self) -> Self::Drain<'a> where Self: Own; }
If Rust acquires such types, the iterator- and entry-returning methods will be changed to use them.
Reexports
pub use map::Map; |
pub use set::Set; |
Modules
map |
Maps. |
set |
Sets. |
Traits
Collection |
A collection. |
Deque |
A double-ended queue. |
DrainRange |
A collection that supports draining a range of its items. |
FifoDeque |
A double-ended first-in, first-out queue. |
FifoQueue |
A first-in, first-out queue. |
Iter |
A collection that supports by-reference iteration. |
List |
A list. |
Mut |
A marker trait that enables write access to a collection's items. |
Own |
A marker trait that enables insertion and removal of a collection's items. |
PrioDeque |
A double-ended priority queue. |
PrioQueue |
A priority queue. |
Queue |
A queue. |