Struct nonempty::NonEmpty

pub struct NonEmpty<T>(_, _);

Methods

impl<T> NonEmpty<T>

pub const fn new(e: T) -> Self

Alias for NonEmpty::singleton.

pub const fn singleton(e: T) -> Self

Create a new non-empty list with an initial element.

pub const fn is_empty(&self) -> bool

Always returns false.

pub const fn first(&self) -> &T

Get the first element. Never fails.

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

Push an element to the end of the list.

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

Pop an element from the end of the list.

pub fn len(&self) -> usize

Get the length of the list.

pub fn last(&self) -> &T

Get the last element. Never fails.

pub fn last_mut(&mut self) -> &mut T

Get the last element mutably.

pub fn get(&self, index: usize) -> Option<&T>

Get an element by index.

pub fn get_mut(&mut self, index: usize) -> Option<&mut T>

Get an element by index, mutably.

pub fn truncate(&mut self, len: usize)

Truncate the list to a certain size. Must be greater than 0.

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

use nonempty::NonEmpty;

let mut l = NonEmpty::from((42, vec![36, 58]));

let mut l_iter = l.iter();

assert_eq!(l_iter.next(), Some(&42));
assert_eq!(l_iter.next(), Some(&36));
assert_eq!(l_iter.next(), Some(&58));
assert_eq!(l_iter.next(), None);

pub fn iter_mut<'a>(&'a mut self) -> impl Iterator<Item = &mut T> + 'a

use nonempty::NonEmpty;

let mut l = NonEmpty::new(42);
l.push(36);
l.push(58);

for i in l.iter_mut() {
    *i *= 10;
}

let mut l_iter = l.iter();

assert_eq!(l_iter.next(), Some(&420));
assert_eq!(l_iter.next(), Some(&360));
assert_eq!(l_iter.next(), Some(&580));
assert_eq!(l_iter.next(), None);

pub fn from_slice(slice: &[T]) -> Option<NonEmpty<T>> where
    T: Clone, 

Often we have a Vec (or slice &[T]) but want to ensure that it is NonEmpty before proceeding with a computation. Using from_slice will give us a proof that we have a NonEmpty in the Some branch, otherwise it allows the caller to handle the None case.

Example Use

use nonempty::NonEmpty;

let non_empty_vec = NonEmpty::from_slice(&[1, 2, 3, 4, 5]);
assert_eq!(non_empty_vec, Some(NonEmpty::from((1, vec![2, 3, 4, 5]))));

let empty_vec: Option<NonEmpty<&u32>> = NonEmpty::from_slice(&[]);
assert!(empty_vec.is_none());

pub fn split_first(&self) -> (&T, &[T])

Deconstruct a NonEmpty into its head and tail. This operation never fails since we are guranteed to have a head element.

Example Use

use nonempty::NonEmpty;

let mut non_empty = NonEmpty::from((1, vec![2, 3, 4, 5]));

// Guaranteed to have the head and we also get the tail.
assert_eq!(non_empty.split_first(), (&1, &[2, 3, 4, 5][..]));

let non_empty = NonEmpty::new(1);

// Guaranteed to have the head element.
assert_eq!(non_empty.split_first(), (&1, &[][..]));

pub fn split(&self) -> (&T, &[T], &T)

Deconstruct a NonEmpty into its first, last, and middle elements, in that order.

If there is only one element then first == last.

Example Use

use nonempty::NonEmpty;

let mut non_empty = NonEmpty::from((1, vec![2, 3, 4, 5]));

// Guaranteed to have the last element and the elements
// preceding it.
assert_eq!(non_empty.split(), (&1, &[2, 3, 4][..], &5));

let non_empty = NonEmpty::new(1);

// Guaranteed to have the last element.
assert_eq!(non_empty.split(), (&1, &[][..], &1));

pub fn append(&mut self, other: &mut Vec<T>)

Append a Vec to the tail of the NonEmpty.

Example Use

use nonempty::NonEmpty;

let mut non_empty = NonEmpty::new(1);
let mut vec = vec![2, 3, 4, 5];
non_empty.append(&mut vec);

let mut expected = NonEmpty::from((1, vec![2, 3, 4, 5]));

assert_eq!(non_empty, expected);

pub fn map<U, F>(&self, f: F) -> NonEmpty<U> where
    F: Fn(&T) -> U, 

A structure preserving map. This is useful for when we wish to keep the NonEmpty structure guaranteeing that there is at least one element. Otherwise, we can use nonempty.iter().map(f).

Example Use

use nonempty::NonEmpty;

let non_empty = NonEmpty::from((1, vec![2, 3, 4, 5]));

let squares = non_empty.map(|i| i * i);

let expected = NonEmpty::from((1, vec![4, 9, 16, 25]));

assert_eq!(squares, expected);

Trait Implementations

impl<T> Into<Vec<T>> for NonEmpty<T>

fn into(self) -> Vec<T>

Turns a non-empty list into a Vec.

impl<T> From<(T, Vec<T>)> for NonEmpty<T>

fn from((head, tail): (T, Vec<T>)) -> Self

Turns a pair of an element and a Vec into a NonEmpty.

impl<T: Clone> Clone for NonEmpty<T>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Eq> Eq for NonEmpty<T>

impl<T: Ord> Ord for NonEmpty<T>

fn cmp(&self, other: &NonEmpty<T>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<T: PartialEq> PartialEq<NonEmpty<T>> for NonEmpty<T>

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &NonEmpty<T>) -> bool

This method tests for !=.

impl<T: PartialOrd> PartialOrd<NonEmpty<T>> for NonEmpty<T>

fn partial_cmp(&self, other: &NonEmpty<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &NonEmpty<T>) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &NonEmpty<T>) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &NonEmpty<T>) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &NonEmpty<T>) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: Debug> Debug for NonEmpty<T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T: Hash> Hash for NonEmpty<T>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl<T> StructuralPartialEq for NonEmpty<T>

impl<T> StructuralEq for NonEmpty<T>