eclectic 0.11.0

Experimental collection traits.
Documentation

Collection traits for generic programming.

The principal traits in this library are:

When combined with these traits, two marker traits enable the use of additional operations:

Marker Operations Analogous Type
(none) Read-only access to a collection and its items &[T]
Mutate Write access to a collection's items &mut [T]
AddRemove Insertion and removal of a collection's items &mut Vec<T>

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, Mutate};

fn insertion_sort<L: ?Sized + List + Mutate>(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 `Mutate` bound on `L` enables the use of `List::swap`
            j -= 1;
        }
    }
}

use std::collections::VecDeque;

let mut vec = vec!['c', 'a', 'e', 'd', 'b'];
let mut vec_deque: VecDeque<_> = vec.iter().cloned().collect();

insertion_sort(&mut vec);
assert_eq!(vec, ['a', 'b', 'c', 'd', 'e']);

insertion_sort(&mut vec_deque);
assert!(vec_deque.iter().eq(&['a', 'b', 'c', 'd', 'e']));

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: AddRemove;
}

If Rust acquires such types, the iterator- and entry-returning methods will be changed to use them.