add recipes to convert a BufList into a Stream or a TryStream

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## [1.0.1] - 2023-02-16
+
+### Added
+
+- Add recipes for converting a `BufList` into a `Stream` or a `TryStream`.
+
 ## [1.0.0] - 2023-01-06
 
 ### Added
@@ -32,6 +38,7 @@ This project adheres to [Semantic Versioning](https://semver.org).
 
 - Initial release.
 
+[1.0.1]: https://github.com/sunshowers-code/buf-list/releases/tag/1.0.1
 [1.0.0]: https://github.com/sunshowers-code/buf-list/releases/tag/1.0.0
 [0.1.3]: https://github.com/sunshowers-code/buf-list/releases/tag/0.1.3
 [0.1.2]: https://github.com/sunshowers-code/buf-list/releases/tag/0.1.2

README.md

@@ -37,7 +37,7 @@ Collect a fallible stream of `Bytes` into a `BufList`:
 ```rust
 use buf_list::BufList;
 use bytes::Bytes;
-use futures::stream::TryStreamExt;
+use futures::TryStreamExt;
 
 // A common example is a stream of bytes read over HTTP.
 let stream = futures::stream::iter(
@@ -52,6 +52,28 @@ let buf_list = stream.try_collect::<BufList>().await?;
 assert_eq!(buf_list.num_chunks(), 3);
 ```
 
+## Converting to `Stream`s
+
+A `BufList` can be converted into a `futures::Stream`, or a `TryStream`, of `Bytes` chunks. Use
+this recipe to do so:
+
+(This will be exposed as an API on `BufList` once `Stream` and/or `TryStream` become part of
+stable Rust.)
+
+```rust
+use buf_list::BufList;
+use bytes::Bytes;
+use futures::{Stream, TryStream};
+
+fn into_stream(buf_list: BufList) -> impl Stream<Item = Bytes> {
+    futures::stream::iter(buf_list)
+}
+
+fn into_try_stream<E>(buf_list: BufList) -> impl TryStream<Ok = Bytes, Error = E> {
+    futures::stream::iter(buf_list.into_iter().map(Ok))
+}
+```
+
 ## Minimum supported Rust version
 
 The minimum supported Rust version (MSRV) is **1.39**, same as the `bytes` crate.

src/lib.rs

@@ -42,7 +42,7 @@
 //! ```
 //! use buf_list::BufList;
 //! use bytes::Bytes;
-//! use futures::stream::TryStreamExt;
+//! use futures::TryStreamExt;
 //!
 //! # #[tokio::main(flavor = "current_thread")]
 //! # async fn main() -> Result<(), ()> {
@@ -60,6 +60,28 @@
 //! # Ok(()) }
 //! ```
 //!
+//! # Converting to `Stream`s
+//!
+//! A `BufList` can be converted into a `futures::Stream`, or a `TryStream`, of `Bytes` chunks. Use
+//! this recipe to do so:
+//!
+//! (This will be exposed as an API on `BufList` once `Stream` and/or `TryStream` become part of
+//! stable Rust.)
+//!
+//! ```rust
+//! use buf_list::BufList;
+//! use bytes::Bytes;
+//! use futures::{Stream, TryStream};
+//!
+//! fn into_stream(buf_list: BufList) -> impl Stream<Item = Bytes> {
+//!     futures::stream::iter(buf_list)
+//! }
+//!
+//! fn into_try_stream<E>(buf_list: BufList) -> impl TryStream<Ok = Bytes, Error = E> {
+//!     futures::stream::iter(buf_list.into_iter().map(Ok))
+//! }
+//! ```
+//!
 //! # Minimum supported Rust version
 //!
 //! The minimum supported Rust version (MSRV) is **1.39**, same as the `bytes` crate.