Push trait

Push trait for collections. You may freely use and modify this code under the CC0 1.0 Universal License.

Usage

To use in your own project, just add the below to your Cargo.toml file.

[dependencies]
push-trait = "0.5"

For more formal documentation, you can find the rustdoc here.

lib.rs:

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.

• 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.