### 16 releases (9 breaking)

0.10.0 | Feb 29, 2024 |
---|---|

0.9.0 | Nov 17, 2023 |

0.8.1 | Dec 6, 2022 |

0.8.0 | Jun 30, 2022 |

0.1.5 | Nov 25, 2019 |

#**52** in Rust patterns

**252,133** downloads per month

Used in **195** crates
(47 directly)

**MIT**license

41KB

635 lines

# Correct by Construction Non-Empty List

This package exposes a type

with a data representation
that guarantees non-emptiness statically:`NonEmpty <T>`

`struct` `NonEmpty``<`T`>``(`T, `Vec``<`T`>``)`

The library is meant to have an interface similar to

:`std ::`

`vec`Vec

`::``use` `nonempty``::`NonEmpty`;`
`let` `mut` l `=` `NonEmpty``::`new`(``42``)``;`
`assert_eq!``(`l`.``first``(``)``,` `&``42``)``;`
l`.``push``(``36``)``;`
l`.``push``(``58``)``;`
`let` v`:` `Vec``<``i32``>` `=` l`.``into``(``)``;`
`assert_eq!``(`v`,` `vec!``[``42``,` `36``,` `58``]``)``;`

###
`lib.rs`

:

A Non-empty growable vector.

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 as 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 `NonEmpty`

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

`NonEmpty``::`last

don't
return in `Option`

, they always succeed.# Examples

The simplest way to construct a

is via the `NonEmpty`

macro:`nonempty`

`use` `nonempty``::``{`NonEmpty`,` nonempty`}``;`
`let` l`:` `NonEmpty``<``u32``>` `=` `nonempty!``[``1``,` `2``,` `3``]``;`
`assert_eq!``(`l`.`head`,` `1``)``;`

Unlike the familiar

macro, `vec!`

requires at least one element:`nonempty!`

`use` `nonempty``::`nonempty`;`
`let` l `=` `nonempty!``[``1``]``;`
`//` Doesn't compile!
`//` let l = nonempty![];

Like

, you can also construct a `Vec`

the old fashioned way with
`NonEmpty`

or its constructor:`NonEmpty ::`new

`use` `nonempty``::`NonEmpty`;`
`let` `mut` l `=` NonEmpty `{` 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``::``{`NonEmpty`,` nonempty`}``;`
`let` l`:` `NonEmpty``<``u32``>` `=` `nonempty!``[``42``,` `36``,` `58``,` `9001``]``;`
`let` v`:` `Vec``<``u32``>` `=` l`.``into``(``)``;`
`assert_eq!``(`v`,` `vec!``[``42``,` `36``,` `58``,` `9001``]``)``;`
`let` u`:` `Option``<`NonEmpty`<``u32``>``>` `=` `NonEmpty``::`from_vec`(`v`)``;`
`assert_eq!``(``Some``(``nonempty!``[``42``,` `36``,` `58``,` `9001``]``)``,` u`)``;`

# Caveats

Since

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

trait for it. We can't know, in general, if
any given `FromInterator`

actually contains something.`Iterator`

# Features

:`serialize`

support.`serde`

:`arbitrary`

support.`arbitrary`

#### Dependencies

~200KB