push_trait/
base.rs

1//! Basic traits and types for moving or copying data into a collection.
2use len_trait::Clear;
3
4/// A trait for collections which *can* implement some form of [`Push`] trait.
5///
6/// Some containers have limitations on which elements can be stored at once; these collections will
7/// "push out" a value after the push happens. A finite-size buffer may push out the oldest value,
8/// or a map may push out a value at the same key.
9///
10/// [`Push`]: trait.Push.html
11pub trait CanPush<T>: Clear {
12    /// Type of value that would get pushed out, if any.
13    type PushedOut;
14}
15
16/// A trait for moving data into a collection.
17///
18/// Some containers have limitations on which elements can be stored at once; these collections will
19/// "push out" a value after the push happens. A finite-size buffer may push out the oldest value,
20/// or a map may push out a value at the same key.
21///
22/// Pushing an item must take a linear amount of time and space with respect to the length of the
23/// pushed item. References can be pushed to "copy" data.
24pub trait Push<T>: CanPush<T> {
25    /// Moves the value into the collection, yielding the value that was pushed out, if any.
26    fn push(&mut self, val: T) -> Option<Self::PushedOut>;
27}
28
29/// Represents a pushed value that has been dropped.
30///
31/// Some collections may refuse to push a value for a variety of different reasons. These
32/// collections will return `Some(PushedVal)` to represent that, even though the pushed value was
33/// dropped, it was "pushed out" instead of being pushed.
34#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
35pub struct PushedVal;
36
37/// Represents that no value can ever be pushed out of a collection.
38///
39/// These collections will continue to allocate memory for every push, and will successfully push
40/// values until memory is exhausted.
41pub type Nothing = ::void::Void;
push_trait/base.rs

push_trait/
base.rs
