Crate eclectic

Collection traits for generic programming.

The principal traits in this library are:

• Collection
  • List
  • Map
  • Set
  • Queue
    • FifoQueue
    • PrioQueue
  • Deque
    • FifoDeque
    • PrioDeque

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.

Re-exports

pub use map::Map;

pub use set::Set;

Modules

map

Maps.

set

Sets.

Traits

AddRemove

A marker that indicates that a collection supports the insertion of new items and the removal of existing items.

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.

Mutate

A marker that indicates that a collection supports the mutation of its items.

PrioDeque

A double-ended priority queue.

PrioQueue

A priority queue.

Queue

A queue.