push_trait/
lib.rs

1//! This crate generalises traits over the `push`/`insert` methods found in most collections.
2//!
3//! # What's generalised
4//!
5//! Conceptually, "pushing" a value to a collection will either move data into the collection, e.g.
6//! via `Vec::push`, or copy data into a collection, e.g. via `String::push_str`.
7//!
8//! Although pushed values themselves are not required to implement `Len`, we conceptually assign
9//! them a length relative to the collection into which they're being pushed. For example, a single
10//! value pushed onto a `Vec` will have a length of one, whereas a `str` pushed onto a `String` will
11//! have a length in some number of bytes.
12//!
13//! Because not every push is infalliable, collections may also "push out" a value whenever a value
14//! is pushed. For example, a FILO buffer pushes out its oldest item if it is full, and a `HashMap`
15//! pushes out the old value at a key if a new one is inserted.
16//!
17//! Pushing to a collection will increase its length by the length of the pushed value, and decrease
18//! its length by the length of a value that's pushed out.
19//!
20//! # Available traits
21//!
22//! *In this section, let `m` be the length of the inserted item and `n` be the length of the
23//! collection.*
24//!
25//! These traits let you move data into a collection. [`CanPush`] must be implemented for any type
26//! that implements these traits.
27//!
28//! * [`Push`]: `O(m)`
29//! * [`PushBack`]: `O(m)`
30//! * [`PushFront`]: `O(m)`
31//! * [`PushSorted`]: `O(m log n)`
32//! * [`Insert`]: `O(n + m)`
33//!
34//! These variants let you move data without freeing resources. Instead of pushing data out of the
35//! collection, data is retained in the second collection.
36//!
37//! * [`Append`]: `O(m)`
38//! * [`AppendBack`]: `O(m)`
39//! * [`AppendFront`]: `O(m)`
40//!
41//! [`CanPush`]: base/trait.CanPush.html
42//! [`Push`]: base/trait.Push.html
43//! [`PushBack`]: ordered/trait.PushBack.html
44//! [`PushFront`]: ordered/trait.PushFront.html
45//! [`PushSorted`]: sorted/trait.PushSorted.html
46//! [`Insert`]: ordered/trait.Insert.html
47//! [`Append`]: append/trait.Append.html
48//! [`AppendBack`]: append/trait.AppendBack.html
49//! [`AppendFront`]: append/trait.AppendFront.html
50#![cfg_attr(all(not(feature = "std"), feature = "alloc"), feature(alloc))]
51#![cfg_attr(not(feature = "std"), no_std)]
52#![doc(html_root_url = "https://docs.charr.xyz/push-trait/")]
53#![cfg_attr(test, deny(warnings))]
54
55// TODO: https://github.com/rust-lang/rust/issues/32310
56#![cfg_attr(all(feature = "nightly", feature = "alloc"), feature(splice))]
57
58extern crate len_trait;
59extern crate void;
60
61#[macro_use]
62extern crate cfg_if;
63
64#[cfg(all(not(feature = "std"), feature = "alloc"))]
65extern crate alloc;
66
67pub mod append;
68pub mod base;
69pub mod ordered;
70pub mod sorted;
71
72pub use append::*;
73pub use base::*;
74pub use ordered::*;
75pub use sorted::*;
76
77mod impls;
push_trait/lib.rs

push_trait/
lib.rs
