13 releases
0.2.9 | Aug 26, 2024 |
---|---|
0.2.7 | Jul 22, 2024 |
0.2.3 | Mar 19, 2024 |
0.1.4 | Nov 2, 2023 |
0.1.1 | Apr 8, 2023 |
#115 in Data structures
2,337 downloads per month
Used in 8 crates
(7 directly)
165KB
3K
SLoC
Correct-by-Construction Collections
Non-empty variants of the standard collections.
Non-emptiness can be a powerful guarantee. If your main use of Vec
is as
an Iterator
, then you may not need to distinguish on emptiness. But there
are indeed times when the Vec
you receive as a function argument needs to
be non-empty or your function can't proceed. Similarly, there are times when
the Vec
you return to a calling user needs to promise it actually contains
something.
With NEVec
, you're freed from the boilerplate of constantly needing to
check is_empty()
or pattern matching before proceeding, or erroring if you
can't. So overall, code, type signatures, and logic become cleaner.
Consider that unlike Vec
, NEVec::first
and NEVec::last
don't
return in Option
; they always succeed.
Alongside NEVec
are its cousins NESlice
, NEMap
, and NESet
,
which are all guaranteed to contain at least one item.
Examples
The simplest way to construct these non-empty collections is via their
macros: nev!
, nes!
, and nem!
:
use nonempty_collections::*;
let v: NEVec<u32> = nev![1, 2, 3];
let s: NESet<u32> = nes![1, 2, 2, 3]; // 1 2 3
let m: NEMap<&str, bool> = nem!["a" => true, "b" => false];
assert_eq!(1, v.head);
assert_eq!(3, s.len().get());
assert!(m.get("a").unwrap());
Unlike the familiar vec!
macro, nev!
and friends require at least one
element:
use nonempty_collections::nev;
let v = nev![1];
// Doesn't compile!
// let v = nev![];
Like Vec
, you can also construct a NEVec
the old fashioned way with
NEVec::new
or its constructor:
use nonempty_collections::NEVec;
let mut l = NEVec { head: 42, tail: vec![36, 58] };
assert_eq!(l.head, 42);
l.push(9001);
assert_eq!(l.last(), &9001);
And if necessary, you're free to convert to and from Vec
:
use nonempty_collections::{NEVec, nev};
let l: NEVec<u32> = nev![42, 36, 58, 9001];
let v: Vec<u32> = l.into();
assert_eq!(v, vec![42, 36, 58, 9001]);
let u: Option<NEVec<u32>> = NEVec::from_vec(v);
assert_eq!(Some(nev![42, 36, 58, 9001]), u);
Iterators
This library extends the notion of non-emptiness to Iterators, and provides
the NonEmptyIterator
trait. This has some interesting consequences:
- Functions like
map
preserve non-emptiness. - Functions like
max
always have a result. - A non-empty Iterator chain can be
collect
ed back into a non-empty structure. - You can chain many operations together without having to double-check for emptiness.
use nonempty_collections::*;
let v: NEVec<_> = nev![1, 2, 3].into_nonempty_iter().map(|n| n + 1).collect();
assert_eq!(2, v.head);
Consider also IteratorExt::to_nonempty_iter
for converting any given
Iterator
into a non-empty one, if it contains at least one item.
Arrays
Since fixed-size arrays are by definition already not empty, they aren't
given a special wrapper type like crate::NEVec
. Instead, we enable them
to be easily iterated over in a compatible way:
use nonempty_collections::*;
let a: [u32; 4] = [1, 2, 3, 4];
let v: NEVec<_> = a.into_nonempty_iter().map(|n| n + 1).collect();
assert_eq!(nev![2, 3, 4, 5], v);
See NonEmptyArrayExt
for more conversions.
Caveats
Since NEVec
, NEMap
, and NESet
must have a least one element, it is not
possible to implement the FromIterator
trait for them. We can't know, in
general, if any given standard-library Iterator
actually contains
something.
Features
serde
:serde
support.indexmap
: support for non-emptyIndexMap
Dependencies
~0–325KB