Crate cc_traits

This crate provide traits to describe common operations available on data structures. This is particularly useful when building new types on top of generic data structures without relying on the actual implementation of the underlying data structure.

Here is an example of the kind of traits provided by this crate:

/// Mutable collection where new elements can be inserted.
pub trait Insert: Collection {
    /// The output of the insertion function.
    type Output;

    /// Insert a new element in the collection.
    fn insert(&mut self, element: Self::Item) -> Self::Output;
}

Usage

Such traits can be used to define collections with special properties, independently of the actual internal data structure. For instance the following code defines an Ordered<S> stack collection, guarantying the well-sortedness of the elements in the stack.

use cc_traits::{
    Collection,
    Back,
    PushBack
};

/// Ordered stack.
pub struct Ordered<S> {
    inner: S
}

impl<S> Ordered<S> {
    pub fn new() -> Self where S: Default {
        Ordered {
            inner: S::default()
        }
    }
}

impl<S> Ordered<S> {
    /// Push the given element on the stack iff it is grater or equal
    /// to every other element already in the stack.
    pub fn try_push<T>(&mut self, element: T) -> Result<(), T>
    where
        T: PartialOrd,
        S: Collection<Item=T> + Back + PushBack, // `S` must be a stack providing `back` and `push_back`.
        for<'a> S::ItemRef<'a>: PartialOrd<&'a T> // The reference type must be comparable with other reference types.
    {
        if self.inner.back().map(|back| back <= &element).unwrap_or(true) {
            self.inner.push_back(element);
            Ok(())
        } else {
            Err(element)
        }
    }
}

#[cfg(feature = "std")]
fn ordered_stack_usage<S>()
where
    S: Default + Collection<Item = i32> + Back + PushBack,
    for<'a> S::ItemRef<'a>: PartialOrd<&'a i32>,
{
    let mut ordered: Ordered<S> = Ordered::new();
    assert!(ordered.try_push(1).is_ok());
    assert!(ordered.try_push(2).is_ok());
    assert!(ordered.try_push(0).is_err());
}

#[cfg(feature = "std")]
ordered_stack_usage::<Vec<i32>>(); // a `Vec` is a stack so it works.

#[cfg(feature = "std")]
use std::collections::VecDeque;
#[cfg(feature = "std")]
ordered_stack_usage::<VecDeque<i32>>(); // a `VecDeque` is also a stack.

Trait aliases

By enabling the nightly you can get access to some trait alias definitions that can be useful to reduce the verbosity of your code. Here is an example of such aliases defining the common interface of stacks:

pub trait Stack<T> = Collection<Item=T> + Len + Back;
pub trait StackMut<T> = Stack<T> + BackMut + PushBack + PopBack;

As of version 0.8.0, those traits are also available without the nightly feature as regular trait definitions.

Standard library

By default, all the traits defined in this crate are implemented (when relevant) for the standard library collections. You can disable it by using the nostd feature.

Foreign implementations

In addition to the standard library, traits are implemented for some popular crates if you enable the feature of the same name. Here are the supported crates:

• slab providing the Slab collection.
• smallvec providing the SmallVec collection.
• serde_json providing the Map<String, Value> collection for JSON objects.
• ijson providing the IObject and IArray collections.

Macros

• covariant_item_mut
  Automatically defines the CollectionMut::upcast_item_mut function using the covariance of the ItemMut<'a> type with regards to 'a.
• covariant_item_ref
  Automatically defines the CollectionRef::upcast_item_ref function using the covariance of the ItemRef<'a> type with regards to 'a.
• covariant_key_ref
  Automatically defines the KeyedRef::upcast_item_ref function using the covariance of the KeyRef<'a> type with regards to 'a.
• simple_collection_mut
  Automatically defines the CollectionMut::upcast_item_mut function using the covariance of the ItemMut<'a> type with regards to 'a.
• simple_collection_ref
  Automatically defines the SimpleCollectionRef::into_ref function.
• simple_keyed_ref
  Automatically defines the SimpleKeyedRef::into_ref function.

Traits

• Back
  Collection exposing a reference to its back element.
• BackMut
  Collection exposing a mutable reference to its back element.
• Capacity
  Collection with known capacity.
• CapacityMut
  Collection with mutable capacity.
• Clear
  Clearable collection.
• Collection
  Abstract collection.
• CollectionMut
  Abstract collection that can be mutably referenced.
• CollectionRef
  Abstract collection that can be immutably referenced.
• Deque
  Immutable double-ended queue.
• DequeMut
  Mutable double-ended queue.
• Front
  Collection exposing a reference to its front element.
• FrontMut
  Collection exposing a mutable reference to its front element.
• Get
  Queryable collection.
• GetKeyValue
  Queryable map.
• GetKeyValueMut
  Mutably queryable map.
• GetMut
  Mutably queryable collection.
• Insert
  Mutable collection where new elements can be inserted.
• Iter
  Iterable collection.
• IterMut
  Mutably iterable collection.
• Keyed
  Abstract keyed collection.
• KeyedRef
  Abstract keyed collection whose key can be referenced.
• Len
  Sized collection.
• Map
  Imutable map data structure.
• MapInsert
  Mutable map where new new key-value pairs can be inserted.
• MapIter
• MapIterMut
• MapMut
  Mutable map data structure.
• PopBack
  Mutable collection where elements can be popped from the back.
• PopFront
  Mutable collection where elements can be popped from the front.
• PushBack
  Mutable collection where new elements can be pushed on the back.
• PushFront
  Mutable collection where new elements can be pushed on the front.
• Remove
  Mutable collection where elements can be removed from.
• Reserve
  Collection that can extend their capacity.
• Set
  Imutable set data structure.
• SetMut
  Mutable set data structure.
• SimpleCollectionMut
  Collection where each item reference can be converted into a standard “simple” rust reference.
• SimpleCollectionRef
  Collection where each item reference can be converted into a standard “simple” rust reference.
• SimpleKeyedRef
  Keyed collection where each key reference can be converted into a standard “simple” rust reference.
• Slab
  Imutable slab data structure.
• SlabMut
  Mutable slab data structure.
• Stack
  Immutable stack data structure.
• StackMut
  Mutable stack data structure.
• Vec
  Immutable array data structure (conventionally nammed “Vec”).
• VecDeque
  Immutable indexable deque.
• VecDequeMut
  Mutable indexable deque.
• VecMut
  Mutable Vec data structure.
• WithCapacity
  Collection that can be created with a minimum given capacity.