### 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 |

#**89** in Data structures

**4,248** downloads per month

Used in **8** crates
(7 directly)

**MIT**license

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

is as
an `Vec`

, then you may not need to distinguish on emptiness. But there
are indeed times when the `Iterator`

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.`Vec`

With

, you're freed from the boilerplate of constantly needing to
check `NEVec`

or pattern matching before proceeding, or erroring if you
can't. So overall, code, type signatures, and logic become cleaner.`is_empty``(``)`

Consider that unlike

, `Vec`

and `NEVec ::`first

`NEVec``::`last

don't
return in `Option`

; they always succeed.Alongside

are its cousins `NEVec`

, `NESlice`

, and `NEMap`

,
which are all guaranteed to contain at least one item.`NESet`

## Examples

The simplest way to construct these non-empty collections is via their
macros:

, `nev!`

, and `nes!`

:`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

macro, `vec!`

and friends require at least one
element:`nev!`

`use` `nonempty_collections``::`nev`;`
`let` v `=` `nev!``[``1``]``;`
`//` Doesn't compile!
`//` let v = nev![];

Like

, you can also construct a `Vec`

the old fashioned way with
`NEVec`

or its constructor:`NEVec ::`new

`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

trait. This has some interesting consequences:`NonEmptyIterator`

- Functions like

preserve non-emptiness.`map` - Functions like

always have a result.`max` - A non-empty Iterator chain can be

ed back into a non-empty structure.`collect` - 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

for converting any given
`IteratorExt ::`to_nonempty_iter

`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

. Instead, we enable them
to be easily iterated over in a compatible way:`crate`` ::`NEVec

`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

for more conversions.`NonEmptyArrayExt`

## Caveats

Since

, `NEVec`

, and `NEMap`

must have a least one element, it is not
possible to implement the `NESet`

trait for them. We can't know, in
general, if any given standard-library `FromIterator`

actually contains
something.`Iterator`

## Features

:`serde`

support.`serde`

: support for non-empty`indexmap``IndexMap`

#### Dependencies

~0–335KB