Crate rin::ecs::streaming_iterator [−][src]
Streaming iterators.
The iterator APIs in the Rust standard library do not allow elements to be yielded which borrow
from the iterator itself. That means, for example, that the std::io::Lines
iterator must
allocate a new String
for each line rather than reusing an internal buffer. The
StreamingIterator
trait instead provides access to elements being iterated over only by
reference rather than by value.
StreamingIterator
s cannot be used in Rust for
loops, but while let
loops offer a similar
level of ergonomics:
while let Some(item) = iter.next() { // work with item }
However, make sure to only use the above form with a mutable reference to an existing iterator, not with an expression that creates an iterator. For example, the following code will loop forever over the first element of the array:
use streaming_iterator::{convert, StreamingIterator}; let array = [0, 1, 2, 3]; while let Some(item) = convert(array.iter()).next() { // This is an infinite loop! }
While the standard Iterator
trait’s functionality is based off of the next
method,
StreamingIterator
’s functionality is based off of a pair of methods: advance
and get
. This
essentially splits the logic of next
in half (in fact, StreamingIterator
’s next
method
does nothing but call advance
followed by get
).
This is required because of Rust’s lexical handling of borrows (more specifically a lack of
single entry, multiple exit borrows). If StreamingIterator
was defined like Iterator
with
just a required next
method, operations like filter
would be impossible to define.
Structs
Chain | A streaming iterator that concatenates two streaming iterators |
Cloned | A normal, non-streaming, iterator which converts the elements of a streaming iterator into owned values by cloning them. |
Convert | A streaming iterator which yields elements from a normal, non-streaming, iterator. |
ConvertMut | A streaming iterator which yields elements from an iterator of mutable references. |
ConvertRef | A streaming iterator which yields elements from an iterator of references. |
Empty | A simple iterator that returns nothing. |
Filter | A streaming iterator which filters the elements of a streaming iterator with a predicate. |
FilterMap | An iterator which both filters and maps elements of a streaming iterator with a closure. |
FilterMapDeref | A regular, non-streaming iterator which both filters and maps elements of a streaming iterator with a closure. |
FlatMap | A streaming iterator that maps elements to iterators with a closure and then yields the concatenation of the obtained iterators |
FromFn | A simple iterator that returns items from a function call. |
Fuse | A streaming iterator which is well-defined before and after iteration. |
Inspect | A streaming iterator that calls a function with element before yielding it. |
Map | A streaming iterator which transforms the elements of a streaming iterator. |
MapDeref | A regular, non-streaming iterator which transforms the elements of a streaming iterator. |
MapDerefMut | A regular, non-streaming iterator which transforms the elements of a mutable streaming iterator. |
MapRef | A streaming iterator which transforms the elements of a streaming iterator. |
Once | A simple iterator that returns exactly one item. |
OnceWith | A simple iterator that returns exactly one item from a function call. |
Repeat | A simple iterator that repeats an item endlessly. |
RepeatWith | A simple iterator that endlessly returns items from a function call. |
Rev | A streaming iterator which returns elements in the opposite order. |
Skip | A streaming iterator which skips a number of elements in a streaming iterator. |
SkipWhile | A streaming iterator which skips initial elements that match a predicate |
Successors | An iterator where each successive item is computed from the preceding one. |
Take | A streaming iterator which only yields a limited number of elements in a streaming iterator. |
TakeWhile | A streaming iterator which only returns initial elements matching a predicate. |
Traits
DoubleEndedStreamingIterator | A streaming iterator able to yield elements from both ends. |
DoubleEndedStreamingIteratorMut | A mutable streaming iterator able to yield elements from both ends. |
StreamingIterator | An interface for dealing with streaming iterators. |
StreamingIteratorMut | An interface for dealing with mutable streaming iterators. |
Functions
convert | Turns a normal, non-streaming iterator into a streaming iterator. |
convert_mut | Turns an iterator of mutable references into a streaming iterator. |
convert_ref | Turns an iterator of references into a streaming iterator. |
empty | Creates an empty iterator. |
from_fn | Creates an iterator that returns items from a function call. |
once | Creates an iterator that returns exactly one item. |
once_with | Creates an iterator that returns exactly one item from a function call. |
repeat | Creates an iterator that returns an item endlessly. |
repeat_with | Creates an iterator that endlessly returns items from a function call. |
successors | Creates an iterator where each successive item is computed from the preceding one. |