Struct NonEmptyVec 

pub struct NonEmptyVec<T> { /* private fields */ }

A non-empty vector guaranteed to contain at least one element.

This type provides type-level guarantees that operations like head(), max(), and min() will always succeed without returning Option.

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::new(1, vec![2, 3, 4]);
assert_eq!(nev.head(), &1);
assert_eq!(nev.tail(), &[2, 3, 4]);
assert_eq!(nev.len(), 4);

Implementations

impl<T> NonEmptyVec<T>

pub fn new(head: T, tail: Vec<T>) -> NonEmptyVec<T>

Create a new non-empty vector with a head element and tail.

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::new(1, vec![2, 3]);
assert_eq!(nev.len(), 3);

pub fn singleton(value: T) -> NonEmptyVec<T>

Create a non-empty vector from a single element.

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::singleton(42);
assert_eq!(nev.len(), 1);
assert_eq!(nev.head(), &42);

pub fn from_vec(vec: Vec<T>) -> Option<NonEmptyVec<T>>

Try to create a non-empty vector from a Vec.

Returns None if the vector is empty.

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::from_vec(vec![1, 2, 3]).unwrap();
assert_eq!(nev.len(), 3);

let empty = NonEmptyVec::from_vec(Vec::<i32>::new());
assert!(empty.is_none());

pub fn from_vec_unchecked(vec: Vec<T>) -> NonEmptyVec<T>

Create a non-empty vector from a Vec without checking.

Panics

Panics if the vector is empty.

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::from_vec_unchecked(vec![1, 2, 3]);
assert_eq!(nev.len(), 3);

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::from_vec_unchecked(Vec::<i32>::new()); // panics

pub fn head(&self) -> &T

Get the first element (always succeeds).

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::new(1, vec![2, 3]);
assert_eq!(nev.head(), &1);

pub fn tail(&self) -> &[T]

Get the tail (all elements except the first).

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::new(1, vec![2, 3]);
assert_eq!(nev.tail(), &[2, 3]);

pub fn last(&self) -> &T

Get the last element (always succeeds).

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::new(1, vec![2, 3]);
assert_eq!(nev.last(), &3);

let single = NonEmptyVec::singleton(42);
assert_eq!(single.last(), &42);

pub fn len(&self) -> usize

Get the number of elements.

Always >= 1.

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::new(1, vec![2, 3]);
assert_eq!(nev.len(), 3);

pub fn is_empty(&self) -> bool

Check if the vector is empty.

Always returns false since a NonEmptyVec is guaranteed to have at least one element.

This method exists to satisfy clippy’s len_without_is_empty lint.

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::singleton(42);
assert!(!nev.is_empty());

pub fn push(&mut self, value: T)

Push an element to the end.

Example

use stillwater::NonEmptyVec;

let mut nev = NonEmptyVec::singleton(1);
nev.push(2);
nev.push(3);
assert_eq!(nev.len(), 3);

pub fn pop(&mut self) -> Option<T>

Pop an element from the end.

Returns None if there’s only one element (the head).

Example

use stillwater::NonEmptyVec;

let mut nev = NonEmptyVec::new(1, vec![2, 3]);
assert_eq!(nev.pop(), Some(3));
assert_eq!(nev.pop(), Some(2));
assert_eq!(nev.pop(), None); // Can't remove head

pub fn map<U, F>(self, f: F) -> NonEmptyVec<U>

where F: FnMut(T) -> U,

Map a function over all elements.

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::new(1, vec![2, 3]);
let doubled = nev.map(|x| x * 2);
assert_eq!(doubled.head(), &2);
assert_eq!(doubled.tail(), &[4, 6]);

pub fn filter<F>(self, predicate: F) -> Vec<T>

where F: FnMut(&T) -> bool,

Filter elements (may return empty Vec).

Since filtering might remove all elements, this returns Vec<T>.

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::new(1, vec![2, 3, 4]);
let evens = nev.filter(|x| x % 2 == 0);
assert_eq!(evens, vec![2, 4]);

let none = NonEmptyVec::singleton(1).filter(|x| x % 2 == 0);
assert_eq!(none, vec![]);

pub fn into_vec(self) -> Vec<T>

Convert to a regular Vec.

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::new(1, vec![2, 3]);
let vec = nev.into_vec();
assert_eq!(vec, vec![1, 2, 3]);

pub fn iter(&self) -> impl Iterator<Item = &T>

Iterate over all elements.

Example

use stillwater::NonEmptyVec;

let nev = NonEmptyVec::new(1, vec![2, 3]);
let sum: i32 = nev.iter().sum();
assert_eq!(sum, 6);

Trait Implementations

impl<T> Clone for NonEmptyVec<T>

where T: Clone,

fn clone(&self) -> NonEmptyVec<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for NonEmptyVec<T>

where T: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Index<usize> for NonEmptyVec<T>

type Output = T

The returned type after indexing.

fn index(&self, index: usize) -> &<NonEmptyVec<T> as Index<usize>>::Output

Performs the indexing (container[index]) operation.

impl<T> IntoIterator for NonEmptyVec<T>

type Item = T

The type of the elements being iterated over.

type IntoIter = Chain<Once<T>, IntoIter<T>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <NonEmptyVec<T> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<T> PartialEq for NonEmptyVec<T>

where T: PartialEq,

fn eq(&self, other: &NonEmptyVec<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Semigroup for NonEmptyVec<T>

fn combine(self, other: NonEmptyVec<T>) -> NonEmptyVec<T>

Combine this value with another value associatively

impl<T> Eq for NonEmptyVec<T>

where T: Eq,

impl<T> StructuralPartialEq for NonEmptyVec<T>