[![API Docs][Doc Version]][Doc]
[![Downloads][Downloads]][Crate]

# stream-unconsume

Poll stream partially and get emitted items back!
Sometimes it is useful to let someone poll you stream but be able to get it back as if it was never polled.
To do so, this crate provides function `remember`, that, given stream, returns tuple of future and stream.
You can move returned stream to any function, losing it, but, when it gets dropped,
future, returned from `remember`, is resolved with new stream that provides all items that was consumed from
original stream, as well as the rest of this stream, so you can use it as if you never poll original stream.

You may specify any type to be used as buffer, as long as it implements `IntoIterator<Item=Source::Item>` and
`Push<Source::Item>`, where `Source` is the type of stream you want to unconsume.
There is convenience function `remember_vec`, to use `Vec` as buffer backend
(other backends may be `LinkedList`, `VecDeque` and so on).
We use `Push` instead of, say, `PushBack`, to let users ignore order if they wish.
For example, consider if you collect stream to HashSet. If you do that reducing stream,
you will skip repeating elements right when they arrive. However, if you use our `remember_vec` function,
StreamBuffer will keep all these repeating elements, consuming memory,
to let you just drop them when you get your stream back.
Note, that `Push` will add elements using such methods, that, if backend collection preserver insertion order
(`Vec`, but not i.e `HashSet`), iteration over this collection will be in insert order too. In other words,
if you use `LinkedList`, `Push` will perform `push_back`, not `push_front` as you may expect.
Note: Rust doesn't guarantee that Drop is ever called, so you may need to use timeout when you await returned future,
otherwise you will wait for it's resolve forever!

Current Version: 0.3.0

License: MIT OR Apache-2.0

[Doc Version]: https://docs.rs/stream-unconsume/badge.svg
[Doc]: https://docs.rs/stream-unconsume
[Downloads]: https://img.shields.io/crates/d/stream-unconsume.svg
[Crate]: https://crates.io/crates/stream-unconsume