10 releases
0.1.9 | Jan 6, 2023 |
---|---|
0.1.8 | Oct 12, 2022 |
0.1.7 | Sep 8, 2022 |
0.1.6 | Jun 29, 2022 |
0.1.2 | Dec 11, 2016 |
#35 in Algorithms
124,107 downloads per month
Used in 438 crates
(36 directly)
97KB
3K
SLoC
streaming-iterator
Streaming iterators for Rust.
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
lib.rs
:
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.