push-trait 0.6.0

//! Traits for pushing data to the front or back of a collection.

use len_trait::LenMut;

use base::Push;

/// A trait for moving data onto the back of a collection.
///
/// Some collections have a particular location onto which new values are pushed, and the "back"
/// refers to this canonical location. If you don't care where values are pushed, you should use
/// [`Push`] by itself instead.
///
/// Collections which have two locations to push values should also implement [`PushFront`].
///
/// [`Push`]: ../base/trait.Push.html
/// [`PushFront`]: trait.PushFront.html
pub trait PushBack<T>: Push<T> {
    /// Pushes the value onto the back, yielding the value that was pushed out, if any.
    fn push_back(&mut self, val: T) -> Option<Self::PushedOut> {
        self.push(val)
    }
}

/// A trait for moving data onto the front of a collection.
///
/// Some collections have two locations to push values; for these collections, we assign one
/// location as the "back" and the other as the "front." See [`PushBack`] for more information, or
/// use [`Push`] by itself if you don't care where values are pushed.
///
/// [`PushBack`]: trait.PushBack.html
/// [`Push`]: ../base/trait.Push.html
pub trait PushFront<T>: PushBack<T> {
    /// Pushes the value onto the front, yielding the value that was pushed out, if any.
    fn push_front(&mut self, val: T) -> Option<Self::PushedOut>;
}

/// A trait for moving data to a specific index within a collection.
///
/// Unlike [`Push`], insertions must take a linear amount of time and space with respect to the
/// length of both the collection and the inserted item.
///
/// [`Push`]: ../base/trait.Push.html
pub trait Insert<T>: LenMut + PushBack<T> {
    /// Inserts the value at the given position, yielding the value that was pushed out, if any.
    fn insert(&mut self, index: usize, val: T) -> Option<Self::PushedOut>;
}