source
Namespace Subspace :: sus :: iter

Composable external iteration.

If you've found yourself with a collection of some kind, and needed to perform an operation on the elements of said collection, you'll quickly run into 'iterators'. Iterators are heavily used in idiomatic Rust code, so it's worth becoming familiar with them.

The use of iterators with collections is described in the collections documentation.

TODO: Write lots more here.

All iterators implement the Iterator concept. Part of implementing that requires inheriting from IteratorBase which provides a large number of methods for filtering or transforming the items produced by the iterator. All of these methods are "lazy" in that they construct a new iterator but do not touch the source which generates items until iteration begins.

Iterators can interact with standard ranges as well.

Classes

  • ByRef

    An iterator that holds a reference to another iterator and proxies calls through to it. Used to create multiple iterators that share underlying state. The ByRef class must outlive the iterator it refers to.

  • Chain

    An iterator that yields the current count and the element during iteration.

  • Cloned

    An iterator that clones the elements of an underlying iterator.

  • Copied

    An iterator that copies the elements of an underlying iterator.

  • Cycle

    An iterator that repeats endlessly.

  • Empty

    An Iterator that never returns an Item.

  • Enumerate

    An iterator that yields the current count and the element during iteration.

  • Filter

    An iterator that filters based on a predicate function.

  • FilterMap

    An iterator that uses a function to both filter and map elements from another Iterator.

  • FlatMap

    An iterator that maps an iterator of types into an iterator of iterable types through a user-defined function, and then flattens them into an interator of those those iterable types' items.

  • Flatten

    An iterator that flattens an iterator of iterable types into an iterator of those iterable types' items.

  • FromIteratorImpl
  • Fuse

    An iterator that returns the inner iterator's values until it sees None, and then only returns None.

  • Generator

    A generator type that is a sus::iter::Iterator over type T.

  • Inspect

    An iterator that calls a function with a reference to each element before yielding it.

  • IterRef

    An iterator's refcount on the owning collection, preventig mutation while the iterator is alive.

  • IterRefCounter

    Reference counting outstanding iterators (and view types since they need to be able to produce iterators) in order to catch iterator invalidation and prevent them from being used afterward. Mutating the collection should check that the count is empty. This is much like a RefCell in Rust, using runtime verfication that modification does not occur while there are outstanding references.

  • IteratorBase

    The base class for all Iterator types.

  • IteratorOverRange

    The iterator created from a std::range via from_range.

  • IteratorRange

    Support for use of a sus::Iterator as a std::ranges::input_range in the std::ranges library.

  • Map

    An iterator that maps each item to a new type based on a map function.

  • MapWhile

    An iterator that maps each item to a new type based on a map function.

  • Moved

    An iterator that moves from the elements of an underlying iterator.

  • Once

    An Iterator that walks over at most a single Item.

  • OnceWith

    An Iterator that walks over at most a single Item.

  • Peekable

    An iterator with a peek() that returns an optional reference to the next element.

  • Repeat

    An Iterator that walks over at most a single Item.

  • RepeatWith

    An Iterator that walks over at most a single Item.

  • Reverse

    An iterator that iterates over another iterator but in reverse.

  • Scan

    An iterator to maintain state while iterating another iterator.

  • SizeHint
  • Skip

    An iterator that skips over n elements of another iterator.

  • SkipWhile

    An iterator that rejects elements while pred returns true.

  • StepBy

    An iterator that skips over n elements of another iterator.

  • Successors

    An Iterator that generates each item from a function that takes the previous item.

  • Take

    An iterator that only iterates over the first n iterations of another iterator.

  • TakeWhile

    An iterator that only accepts elements while pred returns true.

  • Zip

    An iterator that iterates a group of other iterators simultaneously.

Functions

  • begin
  • empty

    Constructs an Empty iterator, which is an empty iterator that returns nothing.

  • end
  • from_generator

    Produces an iterator over Item from a coroutine function that returns Generator<Item> and yields Items.

  • from_iter

    Constructs ToType from a type that can be turned into an Iterator over elements of type ItemType.

  • from_range

    Constructs an Iterator from a std::ranges::input_range.

  • once

    Constructs a Once iterator that will return o and then None.

  • once_with

    Creates an iterator that lazily generates a value exactly once by invoking the provided closure.

  • repeat

    Creates a new iterator that endlessly repeats a single element.

  • repeat_with

    Creates a new iterator that repeats elements of type Item endlessly by applying the provided closure, the repeater, FnMut<Item()>.

  • successors

    Creates a new iterator where each successive item is computed based on the preceding one.

  • try_from_iter

    Constructs ToType from a type that can be turned into an Iterator over elements of type ItemType.

  • zip

    Converts the arguments to iterators and zips them.

Operators

Concepts

  • DoubleEndedIterator

    An Iterator able to yield elements from both ends.

  • ExactSizeIterator

    An Iterator that knows its exact length.

  • Extend

    Extend a collection with the contents of an iterator.

  • FromIterator

    A concept that indicates ToType can be constructed from an Iterator, via sus::iter::from_iter<ToType>(Iterator<IterType>).

  • IntoIterator

    Conversion into an Iterator.

  • IntoIteratorAny

    Conversion into an Iterator over any type of values.

  • Iterator

    A concept for all implementations of iterators. See IteratorBase for the methods on an Iterator.

  • IteratorAny

    A concept for testing if a type T is an Iterator without testing its Item type.

  • Product

    Trait to represent types that can be created by multiplying elements of an iterator.

  • Sum

    Trait to represent types that can be created by adding elements of an iterator.

  • TrustedLen

    An iterator that reports an accurate length.

Type Aliases

Concept Aliases