pub struct NonEmpty<T>(/* private fields */);
Expand description
A non-empty list which statically guarantees certain operations
cannot return zero, using std::num::NonZeroUsize
.
Experimental
Implementations§
source§impl<T> NonEmpty<T>
impl<T> NonEmpty<T>
sourcepub fn len(&self) -> NonZeroUsize
pub fn len(&self) -> NonZeroUsize
Get the length of the list.
sourcepub fn capacity(&self) -> NonZeroUsize
pub fn capacity(&self) -> NonZeroUsize
Get the capacity of the list.
sourcepub fn truncate(&mut self, len: NonZeroUsize)
pub fn truncate(&mut self, len: NonZeroUsize)
Truncate the list to a certain size.
Methods from Deref<Target = NonEmpty<T>>§
sourcepub fn first_mut(&mut self) -> &mut T
pub fn first_mut(&mut self) -> &mut T
Get the mutable reference to the first element. Never fails.
Examples
use nonempty::NonEmpty;
let mut non_empty = NonEmpty::new(42);
let head = non_empty.first_mut();
*head += 1;
assert_eq!(non_empty.first(), &43);
let mut non_empty = NonEmpty::from((1, vec![4, 2, 3]));
let head = non_empty.first_mut();
*head *= 42;
assert_eq!(non_empty.first(), &42);
sourcepub fn tail(&self) -> &[T]
pub fn tail(&self) -> &[T]
Get the possibly-empty tail of the list.
use nonempty::NonEmpty;
let non_empty = NonEmpty::new(42);
assert_eq!(non_empty.tail(), &[]);
let non_empty = NonEmpty::from((1, vec![4, 2, 3]));
assert_eq!(non_empty.tail(), &[4, 2, 3]);
sourcepub fn insert(&mut self, index: usize, element: T)
pub fn insert(&mut self, index: usize, element: T)
Inserts an element at position index within the vector, shifting all elements after it to the right.
Panics
Panics if index > len.
Examples
use nonempty::NonEmpty;
let mut non_empty = NonEmpty::from((1, vec![2, 3]));
non_empty.insert(1, 4);
assert_eq!(non_empty, NonEmpty::from((1, vec![4, 2, 3])));
non_empty.insert(4, 5);
assert_eq!(non_empty, NonEmpty::from((1, vec![4, 2, 3, 5])));
non_empty.insert(0, 42);
assert_eq!(non_empty, NonEmpty::from((42, vec![1, 4, 2, 3, 5])));
sourcepub fn len_nonzero(&self) -> NonZeroUsize
pub fn len_nonzero(&self) -> NonZeroUsize
Gets the length of the list as a NonZeroUsize.
sourcepub fn contains(&self, x: &T) -> boolwhere
T: PartialEq,
pub fn contains(&self, x: &T) -> boolwhere T: PartialEq,
Check whether an element is contained in the list.
use nonempty::NonEmpty;
let mut l = NonEmpty::from((42, vec![36, 58]));
assert!(l.contains(&42));
assert!(!l.contains(&101));
sourcepub fn truncate(&mut self, len: usize)
pub fn truncate(&mut self, len: usize)
Truncate the list to a certain size. Must be greater than 0
.
sourcepub fn iter(&self) -> Iter<'_, T> ⓘ
pub fn iter(&self) -> Iter<'_, T> ⓘ
use nonempty::NonEmpty;
let mut l = NonEmpty::from((42, vec![36, 58]));
let mut l_iter = l.iter();
assert_eq!(l_iter.len(), 3);
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);
sourcepub fn iter_mut(
&mut self
) -> impl Iterator<Item = &mut T> + DoubleEndedIterator + '_
pub fn iter_mut( &mut self ) -> impl Iterator<Item = &mut T> + DoubleEndedIterator + '_
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);
sourcepub fn split_first(&self) -> (&T, &[T])
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, &[][..]));
sourcepub fn split(&self) -> (&T, &[T], &T)
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));
sourcepub fn append(&mut self, other: &mut Vec<T>)
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);
sourcepub fn binary_search(&self, x: &T) -> Result<usize, usize>where
T: Ord,
pub fn binary_search(&self, x: &T) -> Result<usize, usize>where T: Ord,
Binary searches this sorted non-empty vector for a given element.
If the value is found then Result::Ok is returned, containing the index of the matching element. If there are multiple matches, then any one of the matches could be returned.
If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order.
Examples
use nonempty::NonEmpty;
let non_empty = NonEmpty::from((0, vec![1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]));
assert_eq!(non_empty.binary_search(&0), Ok(0));
assert_eq!(non_empty.binary_search(&13), Ok(9));
assert_eq!(non_empty.binary_search(&4), Err(7));
assert_eq!(non_empty.binary_search(&100), Err(13));
let r = non_empty.binary_search(&1);
assert!(match r { Ok(1..=4) => true, _ => false, });
If you want to insert an item to a sorted non-empty vector, while maintaining sort order:
use nonempty::NonEmpty;
let mut non_empty = NonEmpty::from((0, vec![1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]));
let num = 42;
let idx = non_empty.binary_search(&num).unwrap_or_else(|x| x);
non_empty.insert(idx, num);
assert_eq!(non_empty, NonEmpty::from((0, vec![1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55])));
sourcepub fn binary_search_by<'a, F>(&'a self, f: F) -> Result<usize, usize>where
F: FnMut(&'a T) -> Ordering,
pub fn binary_search_by<'a, F>(&'a self, f: F) -> Result<usize, usize>where F: FnMut(&'a T) -> Ordering,
Binary searches this sorted non-empty with a comparator function.
The comparator function should implement an order consistent with the sort order of the underlying slice, returning an order code that indicates whether its argument is Less, Equal or Greater the desired target.
If the value is found then Result::Ok is returned, containing the index of the matching element. If there are multiple matches, then any one of the matches could be returned. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order.
Examples
Looks up a series of four elements. The first is found, with a uniquely determined position; the second and third are not found; the fourth could match any position in [1,4].
use nonempty::NonEmpty;
let non_empty = NonEmpty::from((0, vec![1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]));
let seek = 0;
assert_eq!(non_empty.binary_search_by(|probe| probe.cmp(&seek)), Ok(0));
let seek = 13;
assert_eq!(non_empty.binary_search_by(|probe| probe.cmp(&seek)), Ok(9));
let seek = 4;
assert_eq!(non_empty.binary_search_by(|probe| probe.cmp(&seek)), Err(7));
let seek = 100;
assert_eq!(non_empty.binary_search_by(|probe| probe.cmp(&seek)), Err(13));
let seek = 1;
let r = non_empty.binary_search_by(|probe| probe.cmp(&seek));
assert!(match r { Ok(1..=4) => true, _ => false, });
sourcepub fn binary_search_by_key<'a, B, F>(
&'a self,
b: &B,
f: F
) -> Result<usize, usize>where
B: Ord,
F: FnMut(&'a T) -> B,
pub fn binary_search_by_key<'a, B, F>( &'a self, b: &B, f: F ) -> Result<usize, usize>where B: Ord, F: FnMut(&'a T) -> B,
Binary searches this sorted non-empty vector with a key extraction function.
Assumes that the vector is sorted by the key.
If the value is found then Result::Ok is returned, containing the index of the matching element. If there are multiple matches, then any one of the matches could be returned. If the value is not found then Result::Err is returned, containing the index where a matching element could be inserted while maintaining sorted order.
Examples
Looks up a series of four elements in a non-empty vector of pairs sorted by their second elements. The first is found, with a uniquely determined position; the second and third are not found; the fourth could match any position in [1, 4].
use nonempty::NonEmpty;
let non_empty = NonEmpty::from((
(0, 0),
vec![(2, 1), (4, 1), (5, 1), (3, 1),
(1, 2), (2, 3), (4, 5), (5, 8), (3, 13),
(1, 21), (2, 34), (4, 55)]
));
assert_eq!(non_empty.binary_search_by_key(&0, |&(a,b)| b), Ok(0));
assert_eq!(non_empty.binary_search_by_key(&13, |&(a,b)| b), Ok(9));
assert_eq!(non_empty.binary_search_by_key(&4, |&(a,b)| b), Err(7));
assert_eq!(non_empty.binary_search_by_key(&100, |&(a,b)| b), Err(13));
let r = non_empty.binary_search_by_key(&1, |&(a,b)| b);
assert!(match r { Ok(1..=4) => true, _ => false, });
sourcepub fn maximum(&self) -> &Twhere
T: Ord,
pub fn maximum(&self) -> &Twhere T: Ord,
Returns the maximum element in the non-empty vector.
This will return the first item in the vector if the tail is empty.
Examples
use nonempty::NonEmpty;
let non_empty = NonEmpty::new(42);
assert_eq!(non_empty.maximum(), &42);
let non_empty = NonEmpty::from((1, vec![-34, 42, 76, 4, 5]));
assert_eq!(non_empty.maximum(), &76);
sourcepub fn minimum(&self) -> &Twhere
T: Ord,
pub fn minimum(&self) -> &Twhere T: Ord,
Returns the minimum element in the non-empty vector.
This will return the first item in the vector if the tail is empty.
Examples
use nonempty::NonEmpty;
let non_empty = NonEmpty::new(42);
assert_eq!(non_empty.minimum(), &42);
let non_empty = NonEmpty::from((1, vec![-34, 42, 76, 4, 5]));
assert_eq!(non_empty.minimum(), &-34);
sourcepub fn maximum_by<'a, F>(&'a self, compare: F) -> &Twhere
F: FnMut(&'a T, &'a T) -> Ordering,
pub fn maximum_by<'a, F>(&'a self, compare: F) -> &Twhere F: FnMut(&'a T, &'a T) -> Ordering,
Returns the element that gives the maximum value with respect to the specified comparison function.
This will return the first item in the vector if the tail is empty.
Examples
use nonempty::NonEmpty;
let non_empty = NonEmpty::new((0, 42));
assert_eq!(non_empty.maximum_by(|(k, _), (l, _)| k.cmp(l)), &(0, 42));
let non_empty = NonEmpty::from(((2, 1), vec![(2, -34), (4, 42), (0, 76), (1, 4), (3, 5)]));
assert_eq!(non_empty.maximum_by(|(k, _), (l, _)| k.cmp(l)), &(4, 42));
sourcepub fn minimum_by<'a, F>(&'a self, compare: F) -> &Twhere
F: FnMut(&'a T, &'a T) -> Ordering,
pub fn minimum_by<'a, F>(&'a self, compare: F) -> &Twhere F: FnMut(&'a T, &'a T) -> Ordering,
Returns the element that gives the minimum value with respect to the specified comparison function.
This will return the first item in the vector if the tail is empty.
use nonempty::NonEmpty;
let non_empty = NonEmpty::new((0, 42));
assert_eq!(non_empty.minimum_by(|(k, _), (l, _)| k.cmp(l)), &(0, 42));
let non_empty = NonEmpty::from(((2, 1), vec![(2, -34), (4, 42), (0, 76), (1, 4), (3, 5)]));
assert_eq!(non_empty.minimum_by(|(k, _), (l, _)| k.cmp(l)), &(0, 76));
sourcepub fn maximum_by_key<'a, U, F>(&'a self, f: F) -> &Twhere
U: Ord,
F: FnMut(&'a T) -> U,
pub fn maximum_by_key<'a, U, F>(&'a self, f: F) -> &Twhere U: Ord, F: FnMut(&'a T) -> U,
Returns the element that gives the maximum value with respect to the specified function.
This will return the first item in the vector if the tail is empty.
Examples
use nonempty::NonEmpty;
let non_empty = NonEmpty::new((0, 42));
assert_eq!(non_empty.maximum_by_key(|(k, _)| k), &(0, 42));
let non_empty = NonEmpty::from(((2, 1), vec![(2, -34), (4, 42), (0, 76), (1, 4), (3, 5)]));
assert_eq!(non_empty.maximum_by_key(|(k, _)| k), &(4, 42));
assert_eq!(non_empty.maximum_by_key(|(k, _)| -k), &(0, 76));
sourcepub fn minimum_by_key<'a, U, F>(&'a self, f: F) -> &Twhere
U: Ord,
F: FnMut(&'a T) -> U,
pub fn minimum_by_key<'a, U, F>(&'a self, f: F) -> &Twhere U: Ord, F: FnMut(&'a T) -> U,
Returns the element that gives the minimum value with respect to the specified function.
This will return the first item in the vector if the tail is empty.
Examples
use nonempty::NonEmpty;
let non_empty = NonEmpty::new((0, 42));
assert_eq!(non_empty.minimum_by_key(|(k, _)| k), &(0, 42));
let non_empty = NonEmpty::from(((2, 1), vec![(2, -34), (4, 42), (0, 76), (1, 4), (3, 5)]));
assert_eq!(non_empty.minimum_by_key(|(k, _)| k), &(0, 76));
assert_eq!(non_empty.minimum_by_key(|(k, _)| -k), &(4, 42));
Trait Implementations§
source§impl<T: Ord> Ord for NonEmpty<T>
impl<T: Ord> Ord for NonEmpty<T>
1.21.0 · source§fn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere Self: Sized,
source§impl<T: PartialEq> PartialEq for NonEmpty<T>
impl<T: PartialEq> PartialEq for NonEmpty<T>
source§impl<T: PartialOrd> PartialOrd for NonEmpty<T>
impl<T: PartialOrd> PartialOrd for NonEmpty<T>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read more