Trait nonempty_collections::iter::NonEmptyIterator

pub trait NonEmptyIterator {
    type Item;
    type IntoIter: IntoIterator<Item = Self::Item>;

    // Required methods
    fn first(self) -> (Self::Item, Self::IntoIter);
    fn next(&mut self) -> Option<Self::Item>;

    // Provided methods
    fn all<F>(&mut self, f: F) -> bool
       where Self: Sized,
             F: FnMut(Self::Item) -> bool { ... }
    fn any<F>(&mut self, f: F) -> bool
       where Self: Sized,
             F: FnMut(Self::Item) -> bool { ... }
    fn chain<U>(self, other: U) -> Chain<Self, U::IntoIter>
       where Self: Sized,
             U: IntoIterator<Item = Self::Item> { ... }
    fn cloned<'a, T>(self) -> Cloned<Self>
       where Self: Sized + NonEmptyIterator<Item = &'a T>,
             T: Clone + 'a { ... }
    fn collect<B>(self) -> B
       where Self: Sized,
             B: FromNonEmptyIterator<Self::Item> { ... }
    fn copied<'a, T>(self) -> Copied<Self>
       where Self: Sized + NonEmptyIterator<Item = &'a T>,
             T: Copy + 'a { ... }
    fn count(self) -> NonZeroUsize
       where Self: Sized { ... }
    fn enumerate(self) -> Enumerate<Self>
       where Self: Sized { ... }
    fn filter<P>(
        self,
        predicate: P
    ) -> Filter<<Self as IntoIterator>::IntoIter, P>
       where Self: Sized + IntoIterator<Item = <Self as NonEmptyIterator>::Item>,
             P: FnMut(&<Self as IntoIterator>::Item) -> bool { ... }
    fn filter_map<B, F>(
        self,
        f: F
    ) -> FilterMap<<Self as IntoIterator>::IntoIter, F>
       where Self: Sized + IntoIterator<Item = <Self as NonEmptyIterator>::Item>,
             F: FnMut(<Self as IntoIterator>::Item) -> Option<B> { ... }
    fn flat_map<U, V, F>(self, f: F) -> FlatMap<Self, V, F>
       where Self: Sized,
             F: FnMut(Self::Item) -> U,
             U: IntoNonEmptyIterator<IntoIter = V, Item = V::Item>,
             V: NonEmptyIterator { ... }
    fn fold<B, F>(self, init: B, f: F) -> B
       where Self: Sized,
             F: FnMut(B, Self::Item) -> B { ... }
    fn map<U, F>(self, f: F) -> Map<Self, F>
       where Self: Sized,
             F: FnMut(Self::Item) -> U { ... }
    fn max(self) -> Self::Item
       where Self: Sized,
             Self::Item: Ord { ... }
    fn max_by<F>(self, compare: F) -> Self::Item
       where Self: Sized,
             F: Fn(&Self::Item, &Self::Item) -> Ordering { ... }
    fn max_by_key<B, F>(self, key: F) -> Self::Item
       where Self: Sized,
             B: Ord,
             F: FnMut(&Self::Item) -> B { ... }
    fn min(self) -> Self::Item
       where Self: Sized,
             Self::Item: Ord { ... }
    fn min_by<F>(self, compare: F) -> Self::Item
       where Self: Sized,
             F: Fn(&Self::Item, &Self::Item) -> Ordering { ... }
    fn min_by_key<B, F>(self, key: F) -> Self::Item
       where Self: Sized,
             B: Ord,
             F: FnMut(&Self::Item) -> B { ... }
    fn nth(&mut self, n: usize) -> Option<Self::Item> { ... }
    fn skip(self, n: usize) -> Skip<<Self as IntoIterator>::IntoIter>
       where Self: Sized + IntoIterator<Item = <Self as NonEmptyIterator>::Item> { ... }
    fn skip_while<P>(
        self,
        pred: P
    ) -> SkipWhile<<Self as IntoIterator>::IntoIter, P>
       where Self: Sized + IntoIterator<Item = <Self as NonEmptyIterator>::Item>,
             P: FnMut(&<Self as IntoIterator>::Item) -> bool { ... }
    fn sum<S>(self) -> S
       where Self: Sized + IntoIterator,
             S: Sum<<Self as IntoIterator>::Item> { ... }
    fn take(self, n: usize) -> Take<Self>
       where Self: Sized { ... }
    fn take_while<P>(
        self,
        pred: P
    ) -> TakeWhile<<Self as IntoIterator>::IntoIter, P>
       where Self: Sized + IntoIterator<Item = <Self as NonEmptyIterator>::Item>,
             P: FnMut(&<Self as IntoIterator>::Item) -> bool { ... }
    fn product<P>(self) -> P
       where Self: Sized + IntoIterator,
             P: Product<<Self as IntoIterator>::Item> { ... }
    fn zip<U>(self, other: U) -> Zip<Self, U::IntoIter>
       where Self: Sized,
             U: IntoNonEmptyIterator { ... }
    fn reduce<F>(self, f: F) -> Self::Item
       where Self: Sized,
             F: FnMut(Self::Item, Self::Item) -> Self::Item { ... }
}

An Iterator that is guaranteed to have at least one item.

Required Associated Types

type Item

The value produced by this iterator.

type IntoIter: IntoIterator<Item = Self::Item>

Each NonEmptyIterator knows about a possibly-empty variant of itself, likely from std. Critically, they share an Item.

Required Methods

fn first(self) -> (Self::Item, Self::IntoIter)

A NonEmptyIterator can, by consuming itself, reliably produce its first element, alongside its possibly-empty variant.

fn next(&mut self) -> Option<Self::Item>

Advances the iterator and returns the next value.

See also Iterator::next.

Provided Methods

fn all<F>(&mut self, f: F) -> bool

where Self: Sized, F: FnMut(Self::Item) -> bool,

Tests if every element of the iterator matches a predicate.

See also Iterator::all.

use nonempty_collections::*;

let n = nev![2,2,2];
assert!(n.iter().all(|n| n % 2 == 0));

fn any<F>(&mut self, f: F) -> bool

where Self: Sized, F: FnMut(Self::Item) -> bool,

Tests if any element of the iterator matches a predicate.

See also Iterator::any.

use nonempty_collections::*;

let n = nev![1,1,1,2,1,1];
assert!(n.iter().any(|n| n % 2 == 0));
assert!(!n.iter().any(|n| n % 3 == 0));

fn chain<U>(self, other: U) -> Chain<Self, U::IntoIter>

where Self: Sized, U: IntoIterator<Item = Self::Item>,

Takes two iterators and creates a new non-empty iterator over both in sequence.

Note that the second iterator need not be empty.

See also Iterator::chain.

use nonempty_collections::*;

let v = nev![1,2,3];
let s = nes![4,5,6];
let mut r: Vec<_> = v.into_nonempty_iter().chain(s).collect();
r.sort();

assert_eq!(vec![1,2,3,4,5,6], r);

fn cloned<'a, T>(self) -> Cloned<Self>

where Self: Sized + NonEmptyIterator<Item = &'a T>, T: Clone + 'a,

Creates a non-empty iterator which clones all of its elements.

This is useful when you have an iterator over &T, but you need an iterator over T.

See also Iterator::cloned.

use nonempty_collections::*;
use nonempty_collections::NEVec;

#[derive(Debug, Clone, PartialEq, Eq)]
enum Foo {
    A,
    B,
    C,
}

let v0 = nev![Foo::A, Foo::B, Foo::C];
let v1: NEVec<_> = v0.iter().collect();
let v2: NEVec<_> = v0.iter().cloned().collect();

assert_eq!(nev![&Foo::A, &Foo::B, &Foo::C], v1);
assert_eq!(nev![Foo::A, Foo::B, Foo::C], v2);

fn collect<B>(self) -> B

where Self: Sized, B: FromNonEmptyIterator<Self::Item>,

Transforms an iterator into a collection, or some other concrete value.

See also Iterator::collect.

use nonempty_collections::*;

let n0 = nev![1,2,3,4];
let n1 = n0.into_nonempty_iter().collect();
assert_eq!(nev![1,2,3,4], n1);

fn copied<'a, T>(self) -> Copied<Self>

where Self: Sized + NonEmptyIterator<Item = &'a T>, T: Copy + 'a,

Creates a non-empty iterator which copies all of its elements.

See also Iterator::copied.

use nonempty_collections::*;

let n0 = nev![1,2,3,4];
let n1 = n0.iter().copied().collect();
assert_eq!(n0, n1);

fn count(self) -> NonZeroUsize

where Self: Sized,

Consumes the non-empty iterator, counting the number of iterations and returning it.

See also Iterator::count.

use nonempty_collections::*;

let n = nev![1];
assert_eq!(1, n.iter().count().get());

let n = nev![1,2,3,4,5,6];
assert_eq!(6, n.iter().count().get());

fn enumerate(self) -> Enumerate<Self>

where Self: Sized,

Creates a non-empty iterator which gives the current iteration count as well as the next value.

See also Iterator::enumerate.

use nonempty_collections::*;

let s = nes!["Doriath", "Gondolin", "Nargothrond"];
let total: usize = s.iter().enumerate().map(|(c, _)| c).sum();
assert_eq!(3, total);

fn filter<P>(self, predicate: P) -> Filter<<Self as IntoIterator>::IntoIter, P>

where Self: Sized + IntoIterator<Item = <Self as NonEmptyIterator>::Item>, P: FnMut(&<Self as IntoIterator>::Item) -> bool,

Creates an iterator which uses a closure to determine if an element should be yielded.

Note: The iterator returned by this method is not a NonEmptyIterator, since there is never a guarantee that any element will pass the predicate.

See also Iterator::filter.

use nonempty_collections::*;

let n = nev![1,2,3,4,5,6];
let v: Vec<_> = n.iter().map(|x| x * 2).filter(|&x| x % 3 == 0).collect();
assert_eq!(vec![6, 12], v);

fn filter_map<B, F>( self, f: F ) -> FilterMap<<Self as IntoIterator>::IntoIter, F>

where Self: Sized + IntoIterator<Item = <Self as NonEmptyIterator>::Item>, F: FnMut(<Self as IntoIterator>::Item) -> Option<B>,

Creates an iterator that both filters and maps.

Note: The iterator returned by this method is not a NonEmptyIterator, since there is never a guarantee that any element will yield Some from the given function.

See also Iterator::filter_map.

use nonempty_collections::*;

let v = nev!["Frodo", "Sam", "", "Peregrin", "Meriadoc"];
let firsts: Vec<char> = v.into_nonempty_iter().filter_map(|s| s.chars().next()).collect();
assert_eq!(vec!['F', 'S', 'P', 'M'], firsts);

fn flat_map<U, V, F>(self, f: F) -> FlatMap<Self, V, F>

where Self: Sized, F: FnMut(Self::Item) -> U, U: IntoNonEmptyIterator<IntoIter = V, Item = V::Item>, V: NonEmptyIterator,

Creates an iterator that works like map, but flattens nested, non-empty structure.

See also Iterator::flat_map.

use nonempty_collections::*;

let v = nev![1, 2, 3];
let r = v.into_nonempty_iter().flat_map(|n| nev![n]).collect();
assert_eq!(nev![1, 2, 3], r);

fn fold<B, F>(self, init: B, f: F) -> B

where Self: Sized, F: FnMut(B, Self::Item) -> B,

Folds every element into an accumulator by applying an operation, returning the final result.

See also Iterator::fold.

use nonempty_collections::*;

let n = nev![1,2,3,4];
let r = n.into_nonempty_iter().fold(0, |acc, x| acc + x);
assert_eq!(10, r);

fn map<U, F>(self, f: F) -> Map<Self, F>

where Self: Sized, F: FnMut(Self::Item) -> U,

Takes a closure and creates a non-empty iterator which calls that closure on each element.

If self is a NonEmptyIterator, then so is Map.

See also Iterator::map.

use nonempty_collections::*;
use nonempty_collections::NEVec;

let s = nes![1,2,3];
let mut v: NEVec<_> = s.iter().map(|n| n * 2).collect();
v.sort();
assert_eq!(nev![2,4,6], v);

fn max(self) -> Self::Item

where Self: Sized, Self::Item: Ord,

Returns the maximum element of a non-empty iterator.

Unlike Iterator::max, this always yields a value.

use nonempty_collections::*;

let v = nev![1, 1000, 2, 3];
assert_eq!(1000, v.into_nonempty_iter().max());

fn max_by<F>(self, compare: F) -> Self::Item

where Self: Sized, F: Fn(&Self::Item, &Self::Item) -> Ordering,

Returns the element that gives the maximum value with respect to the given comparison function.

Unlike Iterator::max_by, this always yields a value.

fn max_by_key<B, F>(self, key: F) -> Self::Item

where Self: Sized, B: Ord, F: FnMut(&Self::Item) -> B,

Returns the element that gives the maximum value from the specified function.

There are two differences with Iterator::max_by_key:

• this function always yields a value while Iterator::max_by_key yields an Option.
• if several elements are equally maximum, the first element is returned (unlike Iterator::max_by_key which returns the last element).

Examples

use nonempty_collections::*;
let max = nev!["hi", "hey", "rust", "yolo"].into_nonempty_iter().max_by_key(|item| item.len());
assert_eq!("rust", max);

fn min(self) -> Self::Item

where Self: Sized, Self::Item: Ord,

Returns the minimum element of a non-empty iterator.

Unlike Iterator::min, this always yields a value.

use nonempty_collections::*;

let v = nev![1000, 1, 2000, 3000];
assert_eq!(1, v.into_nonempty_iter().min());

fn min_by<F>(self, compare: F) -> Self::Item

where Self: Sized, F: Fn(&Self::Item, &Self::Item) -> Ordering,

Returns the element that gives the minimum value with respect to the given comparison function.

Unlike Iterator::min_by, this always yields a value.

fn min_by_key<B, F>(self, key: F) -> Self::Item

where Self: Sized, B: Ord, F: FnMut(&Self::Item) -> B,

Returns the element that gives the minimum value from the specified function.

There are two differences with Iterator::min_by_key:

• this function always yields a value while Iterator::min_by_key yields an Option.
• if several elements are equally minimum, the first element is returned (unlike Iterator::min_by_key which returns the last element).

Examples

use nonempty_collections::*;
let min = nev!["hi", "hello", "greetings", "hy"].into_nonempty_iter().min_by_key(|item| item.len());
assert_eq!("hi", min);

fn nth(&mut self, n: usize) -> Option<Self::Item>

Returns the nth element of the iterator.

See also Iterator::nth.

use nonempty_collections::*;

let n = nev![0,1,2,3,4,5,6];
assert_eq!(Some(&0), n.iter().nth(0));

let n = nev![0,1,2,3,4,5,6];
assert_eq!(Some(&6), n.iter().nth(6));

let n = nev![0,1,2,3,4,5,6];
assert_eq!(None, n.iter().nth(100));

fn skip(self, n: usize) -> Skip<<Self as IntoIterator>::IntoIter>

where Self: Sized + IntoIterator<Item = <Self as NonEmptyIterator>::Item>,

Skip the first n elements.

Note that the result will not be non-empty.

See also Iterator::skip.

use nonempty_collections::*;

let v = nev![1, 2, 3];
assert_eq!(Some(&3), v.iter().skip(2).next());

fn skip_while<P>( self, pred: P ) -> SkipWhile<<Self as IntoIterator>::IntoIter, P>

where Self: Sized + IntoIterator<Item = <Self as NonEmptyIterator>::Item>, P: FnMut(&<Self as IntoIterator>::Item) -> bool,

Skips over all initial elements that pass a given predicate.

Note: This does not yield a non-empty iterator, since there is no guarantee that anything will fail the predicate.

See also Iterator::skip_while.

use nonempty_collections::*;

let v = nev![2, 4, 6, 7, 8];
let r: Vec<_> = v.into_nonempty_iter().skip_while(|n| n % 2 == 0).collect();
assert_eq!(vec![7, 8], r);

fn sum<S>(self) -> S

where Self: Sized + IntoIterator, S: Sum<<Self as IntoIterator>::Item>,

Sums the elements of a non-empty iterator.

See also Iterator::sum.

use nonempty_collections::*;

let sum: u32 = nev![1,2,3,4].iter().sum();
assert_eq!(10, sum);

fn take(self, n: usize) -> Take<Self>

where Self: Sized,

Iterates over the first n elements, or fewer if the underlying iterator ends sooner.

See also Iterator::take.

Panics

Panics if n == 0.

Examples

use nonempty_collections::*;
use nonempty_collections::NEVec;

let n: NEVec<_> = nev![1,2,3].iter().map(|n| n * 2).take(2).collect();
assert_eq!(nev![2,4], n);

fn take_while<P>( self, pred: P ) -> TakeWhile<<Self as IntoIterator>::IntoIter, P>

where Self: Sized + IntoIterator<Item = <Self as NonEmptyIterator>::Item>, P: FnMut(&<Self as IntoIterator>::Item) -> bool,

Iterates over all initial elements that pass a given predicate.

Note: This does not yield a non-empty iterator, since there is no guarantee that anything will pass the predicate.

See also Iterator::take_while.

use nonempty_collections::*;

let v = nev![2, 4, 6, 7, 8];
let r: Vec<_> = v.into_nonempty_iter().take_while(|n| n % 2 == 0).collect();
assert_eq!(vec![2, 4, 6], r);

fn product<P>(self) -> P

where Self: Sized + IntoIterator, P: Product<<Self as IntoIterator>::Item>,

Iterates over the entire non-empty iterator, multiplying all the elements.

See also Iterator::product.

use nonempty_collections::*;

let prod: u32 = nev![1,2,3,4].iter().product();
assert_eq!(24, prod);

fn zip<U>(self, other: U) -> Zip<Self, U::IntoIter>

where Self: Sized, U: IntoNonEmptyIterator,

“Zips up” two non-empty iterators into a single one, while preserving non-emptiness.

See also Iterator::zip.

use nonempty_collections::*;

let a = nev![1, 2, 3];
let b = nev![4, 5, 6, 7];
let r = a.into_nonempty_iter().zip(b).map(|(av, bv)| av + bv).collect();
assert_eq!(nev![5, 7, 9], r);

fn reduce<F>(self, f: F) -> Self::Item

where Self: Sized, F: FnMut(Self::Item, Self::Item) -> Self::Item,

Reduces the elements to a single one, by repeatedly applying a reducing operation.

See also Iterator::reduce.

use nonempty_collections::*;

let a = nev![1, 2, 3, 4];
let b = a.clone();

let x = a.into_nonempty_iter().reduce(|acc, v| acc + v);
assert_eq!(x, 10);

let y = b.into_nonempty_iter().reduce(|acc, v| acc * v);
assert_eq!(y, 24);

Implementors

impl<'a, I, T> NonEmptyIterator for Cloned<I>

where I: NonEmptyIterator<Item = &'a T>, T: Clone + 'a,

type Item = T

type IntoIter = Cloned<<<I as NonEmptyIterator>::IntoIter as IntoIterator>::IntoIter>

impl<'a, I, T> NonEmptyIterator for Copied<I>

where I: NonEmptyIterator<Item = &'a T>, T: Copy + 'a,

type Item = T

type IntoIter = Copied<<<I as NonEmptyIterator>::IntoIter as IntoIterator>::IntoIter>

impl<'a, K, V> NonEmptyIterator for nonempty_collections::index_map::Iter<'a, K, V>

type Item = (&'a K, &'a V)

type IntoIter = Skip<Chain<Once<(&'a K, &'a V)>, Iter<'a, K, V>>>

impl<'a, K, V> NonEmptyIterator for nonempty_collections::index_map::IterMut<'a, K, V>

type Item = (&'a K, &'a mut V)

type IntoIter = Chain<Once<(&'a K, &'a mut V)>, IterMut<'a, K, V>>

impl<'a, K, V> NonEmptyIterator for nonempty_collections::index_map::Keys<'a, K, V>

type Item = &'a K

type IntoIter = Skip<Chain<Once<&'a K>, Keys<'a, K, V>>>

impl<'a, K, V> NonEmptyIterator for nonempty_collections::index_map::Values<'a, K, V>

type Item = &'a V

type IntoIter = Skip<Chain<Once<&'a V>, Values<'a, K, V>>>

impl<'a, K, V> NonEmptyIterator for ValuesMut<'a, K, V>

type Item = &'a mut V

type IntoIter = Chain<Once<&'a mut V>, ValuesMut<'a, K, V>>

impl<'a, K, V> NonEmptyIterator for nonempty_collections::map::Iter<'a, K, V>

type Item = (&'a K, &'a V)

type IntoIter = Skip<Chain<Once<(&'a K, &'a V)>, Iter<'a, K, V>>>

impl<'a, K, V> NonEmptyIterator for nonempty_collections::map::IterMut<'a, K, V>

type Item = (&'a K, &'a mut V)

type IntoIter = Chain<Once<(&'a K, &'a mut V)>, IterMut<'a, K, V>>

impl<'a, K, V> NonEmptyIterator for nonempty_collections::map::Keys<'a, K, V>

type Item = &'a K

type IntoIter = Skip<Chain<Once<&'a K>, Keys<'a, K, V>>>

impl<'a, K, V> NonEmptyIterator for nonempty_collections::map::Values<'a, K, V>

type Item = &'a V

type IntoIter = Skip<Chain<Once<&'a V>, Values<'a, K, V>>>

impl<'a, T> NonEmptyIterator for nonempty_collections::set::Iter<'a, T>

type Item = &'a T

type IntoIter = Skip<Chain<Once<&'a T>, Iter<'a, T>>>

impl<'a, T> NonEmptyIterator for nonempty_collections::slice::Iter<'a, T>

type Item = &'a T

type IntoIter = Skip<Chain<Once<&'a T>, Iter<'a, T>>>

impl<'a, T> NonEmptyIterator for NEChunks<'a, T>

type Item = NESlice<'a, T>

type IntoIter = FilterMap<Chunks<'a, T>, fn(_: &'a [T]) -> Option<NESlice<'a, T>>>

impl<'a, T> NonEmptyIterator for nonempty_collections::vector::Iter<'a, T>

type Item = &'a T

type IntoIter = Skip<Chain<Once<&'a T>, Iter<'a, T>>>

impl<'a, T> NonEmptyIterator for nonempty_collections::vector::IterMut<'a, T>

type Item = &'a mut T

type IntoIter = IterMut<'a, T>

impl<'a, T, S> NonEmptyIterator for Union<'a, T, S>

where T: Eq + Hash, S: BuildHasher,

type Item = &'a T

type IntoIter = Union<'a, T, S>

impl<A, B> NonEmptyIterator for Chain<A, B>

where A: NonEmptyIterator, B: Iterator<Item = A::Item>,

type Item = <A as NonEmptyIterator>::Item

type IntoIter = Chain<<<A as NonEmptyIterator>::IntoIter as IntoIterator>::IntoIter, B>

impl<A, B> NonEmptyIterator for Zip<A, B>

where A: NonEmptyIterator, B: NonEmptyIterator,

type Item = (<A as NonEmptyIterator>::Item, <B as NonEmptyIterator>::Item)

type IntoIter = Zip<<<A as NonEmptyIterator>::IntoIter as IntoIterator>::IntoIter, <<B as NonEmptyIterator>::IntoIter as IntoIterator>::IntoIter>

impl<I> NonEmptyIterator for Enumerate<I>

where I: NonEmptyIterator,

type Item = (usize, <I as NonEmptyIterator>::Item)

type IntoIter = Enumerate<<<I as NonEmptyIterator>::IntoIter as IntoIterator>::IntoIter>

impl<I> NonEmptyIterator for Take<I>

where I: NonEmptyIterator,

type Item = <I as NonEmptyIterator>::Item

type IntoIter = Take<<<I as NonEmptyIterator>::IntoIter as IntoIterator>::IntoIter>

impl<I, U, V, F> NonEmptyIterator for FlatMap<I, U, F>

where I: NonEmptyIterator, F: FnMut(I::Item) -> V, U: NonEmptyIterator, V: IntoNonEmptyIterator<IntoIter = U, Item = U::Item> + IntoIterator<Item = U::Item>,

type Item = <V as IntoNonEmptyIterator>::Item

type IntoIter = Chain<<<U as NonEmptyIterator>::IntoIter as IntoIterator>::IntoIter, FlatMap<<<I as NonEmptyIterator>::IntoIter as IntoIterator>::IntoIter, V, F>>

impl<T> NonEmptyIterator for Once<T>

type Item = T

type IntoIter = IntoIter<T>

impl<T, const C: usize> NonEmptyIterator for ArrayNonEmptyIterator<T, C>

type Item = T

type IntoIter = IntoIter<T, C>

impl<U, I, F> NonEmptyIterator for Map<I, F>

where I: NonEmptyIterator, F: FnMut(I::Item) -> U,

type Item = U

type IntoIter = Map<<<I as NonEmptyIterator>::IntoIter as IntoIterator>::IntoIter, F>