1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

//! This crate generalises traits over the `push`/`insert` methods found in most collections.
//!
//! # What's generalised
//!
//! Conceptually, "pushing" a value to a collection will either move data into the collection, e.g.
//! via `Vec::push`, or copy data into a collection, e.g. via `String::push_str`.
//!
//! Although pushed values themselves are not required to implement `Len`, we conceptually assign
//! them a length relative to the collection into which they're being pushed. For example, a single
//! value pushed onto a `Vec` will have a length of one, whereas a `str` pushed onto a `String` will
//! have a length in some number of bytes.
//!
//! Because not every push is infalliable, collections may also "push out" a value whenever a value
//! is pushed. For example, a FILO buffer pushes out its oldest item if it is full, and a `HashMap`
//! pushes out the old value at a key if a new one is inserted.
//!
//! Pushing to a collection will increase its length by the length of the pushed value, and decrease
//! its length by the length of a value that's pushed out.
//!
//! # Available traits
//!
//! *In this section, let `m` be the length of the inserted item and `n` be the length of the
//! collection.*
//!
//! These traits let you move data into a collection. [`CanPush`] must be implemented for any type
//! that implements these traits.
//!
//! * [`Push`]: `O(m)`
//! * [`PushBack`]: `O(m)`
//! * [`PushFront`]: `O(m)`
//! * [`PushSorted`]: `O(m log n)`
//! * [`Insert`]: `O(n + m)`
//!
//! These variants let you move data without freeing resources. Instead of pushing data out of the
//! collection, data is retained in the second collection.
//!
//! * [`Append`]: `O(m)`
//! * [`AppendBack`]: `O(m)`
//! * [`AppendFront`]: `O(m)`
//!
//! [`CanPush`]: base/trait.CanPush.html
//! [`Push`]: base/trait.Push.html
//! [`PushBack`]: ordered/trait.PushBack.html
//! [`PushFront`]: ordered/trait.PushFront.html
//! [`PushSorted`]: sorted/trait.PushSorted.html
//! [`Insert`]: ordered/trait.Insert.html
//! [`Append`]: append/trait.Append.html
//! [`AppendBack`]: append/trait.AppendBack.html
//! [`AppendFront`]: append/trait.AppendFront.html
#![cfg_attr(all(not(feature = "std"), feature = "alloc"), feature(alloc))]
#![cfg_attr(not(feature = "std"), no_std)]
#![doc(html_root_url = "https://docs.charr.xyz/push-trait/")]
#![cfg_attr(test, deny(warnings))]

// TODO: https://github.com/rust-lang/rust/issues/32310
#![cfg_attr(all(feature = "nightly", feature = "alloc"), feature(splice))]

extern crate len_trait;
extern crate void;

#[macro_use]
extern crate cfg_if;

#[cfg(all(not(feature = "std"), feature = "alloc"))]
extern crate alloc;

pub mod append;
pub mod base;
pub mod ordered;
pub mod sorted;

pub use append::*;
pub use base::*;
pub use ordered::*;
pub use sorted::*;

mod impls;