Crate populated

Expand description

A library for working with non-empty collections i.e. populated collections. Mirrors std collections in its populated versions that guarantee always containing at least one element in the collection.

These collections are useful when you want to ensure that a collection is never empty. Any attempt to make it empty will result in a compile-time error. Also, these collections provide additional guarantees about their length and capacity, which are always non-zero. This means that you do not need to deal with Option in cases where you know that the collection will always have at least one element. For example, you call first() on a PopulatedVec and you are guaranteed to get a reference to the first element without having to deal with Option.

§Safe transition to `std` collections when emptying a populated collection

If you invoke an operation that empties a populated collection, the library provides a safe way to transition to the corresponding std collection. For example, if you call clear() on a PopulatedVec, it will return the underlying Vec. clear() on a PopulatedVec will take ownership of the PopulatedVec and return the underlying Vec. This way any attempt to use a cleared PopulatedVec will result in a compile-time error. At the same time, you can safely and efficiently transition to the Vec when you need to.

§Collections

The following std collections have been mirrored in this library:

Vec → PopulatedVec
Slice → PopulatedSlice
BinaryHeap → PopulatedBinaryHeap
HashMap → PopulatedHashMap
HashSet → PopulatedHashSet
BTreeMap → PopulatedBTreeMap
BTreeSet → PopulatedBTreeSet
VecDeque → PopulatedVecDeque

§Examples

first() on a PopulatedVec and PopulatedSlice:

use populated::{PopulatedVec, PopulatedSlice};

let vec = PopulatedVec::new(1);
assert_eq!(vec.len().get(), 1);
assert_eq!(vec.first(), &1);

let slice = vec.as_slice();
assert_eq!(slice.len().get(), 1);
assert_eq!(slice.first(), &1);

clear() on a BTreeMap:

use populated::PopulatedBTreeMap;

let mut map = PopulatedBTreeMap::new("a", 1);
map.insert("b", 2);
assert_eq!(map.len().get(), 2);

// Safe transition to std BTreeMap on clear
let map = map.clear();
assert_eq!(map.len(), 0);

Modules§

binary_heap
btree_map
btree_set
hash_map
hash_set
iter
slice
str
vec
vec_deque

Macros§

pstr: Constructs a PopulatedStr from a string literal safely.
pvec: A macro pvec! to create a PopulatedVec with a list of elements.

Structs§

PopulatedBTreeMap: An ordered map based on a B-Tree that is guaranteed to have at least one key-value pair.
PopulatedBTreeSet: A populated (i.e. guaranteed to be non-empty) ordered set based on a B-Tree.
PopulatedBinaryHeap
PopulatedHashMap: PopulatedHashMap is a wrapper around HashMap that guarantees that the map is non-empty. This is useful when you want to ensure that a map is populated before using it.
PopulatedHashSet: A hash set that is populated i.e. guaranteed to have at least one element.
PopulatedSlice
PopulatedStr
PopulatedString
PopulatedVec: A non-empty Vec with at least one element.
PopulatedVecDeque: A populated double-ended queue implemented with a growable ring buffer. This type is guaranteed to contain at least one element, so the underlying VecDeque is guaranteed to be non-empty.
UnpopulatedError

Traits§

FromPopulatedIterator: Conversion from a PopulatedIterator.
IntoPopulatedIterator: Conversion into a PopulatedIterator.
PopulatedDoubleEndedIterator
PopulatedIterator: An iterator that guaratees that there is at least one element.
PotentiallyUnpopulated: A trait for types that may be unpopulated. This trait is used to mark types that may be unpopulated. This is used to allow for the conversion of a PopulatedIterator into a type that may be unpopulated.

Type Aliases§

EntryRemovalResult: The result of removing an entry from a PopulatedBTreeMap.

Crate populatedCopy item path

§Safe transition to std collections when emptying a populated collection