Skip to content

Commit

Permalink
Merge pull request rust-lang#408 from marxin/document-read-after-end
Browse files Browse the repository at this point in the history
docs: Document expected behavior when Read is done for ZLIB and DEFLATE decoders
  • Loading branch information
Byron authored Apr 29, 2024
2 parents d3bea90 + f37b1b0 commit 1a0daec
Show file tree
Hide file tree
Showing 6 changed files with 30 additions and 0 deletions.
5 changes: 5 additions & 0 deletions src/deflate/bufread.rs
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,11 @@ impl<W: BufRead + Write> Write for DeflateEncoder<W> {
/// This structure implements a [`Read`] interface. When read from, it reads
/// compressed data from the underlying [`BufRead`] and provides the uncompressed data.
///
/// After reading a single member of the DEFLATE data this reader will return
/// Ok(0) even if there are more bytes available in the underlying reader.
/// If you need the following bytes, call `into_inner()` after Ok(0) to
/// recover the underlying reader.
///
/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
/// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
///
Expand Down
6 changes: 6 additions & 0 deletions src/deflate/read.rs
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,12 @@ impl<W: Read + Write> Write for DeflateEncoder<W> {
/// This structure implements a [`Read`] interface. When read from, it reads
/// compressed data from the underlying [`Read`] and provides the uncompressed data.
///
/// After reading a single member of the DEFLATE data this reader will return
/// Ok(0) even if there are more bytes available in the underlying reader.
/// `DeflateDecoder` may have read additional bytes past the end of the DEFLATE data.
/// If you need the following bytes, wrap the `Reader` in a `std::io::BufReader`
/// and use `bufread::DeflateDecoder` instead.
///
/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
///
/// # Examples
Expand Down
4 changes: 4 additions & 0 deletions src/deflate/write.rs
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,10 @@ impl<W: Read + Write> Read for DeflateEncoder<W> {
/// This structure implements a [`Write`] and will emit a stream of decompressed
/// data when fed a stream of compressed data.
///
/// After decoding a single member of the DEFLATE data this writer will return the number of bytes up to
/// to the end of the DEFLATE member and subsequent writes will return Ok(0) allowing the caller to
/// handle any data following the DEFLATE member.
///
/// [`Write`]: https://doc.rust-lang.org/std/io/trait.Read.html
///
/// # Examples
Expand Down
5 changes: 5 additions & 0 deletions src/zlib/bufread.rs
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,11 @@ impl<R: BufRead + Write> Write for ZlibEncoder<R> {
/// This structure implements a [`Read`] interface. When read from, it reads
/// compressed data from the underlying [`BufRead`] and provides the uncompressed data.
///
/// After reading a single member of the ZLIB data this reader will return
/// Ok(0) even if there are more bytes available in the underlying reader.
/// If you need the following bytes, call `into_inner()` after Ok(0) to
/// recover the underlying reader.
///
/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
/// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
///
Expand Down
6 changes: 6 additions & 0 deletions src/zlib/read.rs
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,12 @@ impl<W: Read + Write> Write for ZlibEncoder<W> {
/// This structure implements a [`Read`] interface. When read from, it reads
/// compressed data from the underlying [`Read`] and provides the uncompressed data.
///
/// After reading a single member of the ZLIB data this reader will return
/// Ok(0) even if there are more bytes available in the underlying reader.
/// `ZlibDecoder` may have read additional bytes past the end of the ZLIB data.
/// If you need the following bytes, wrap the `Reader` in a `std::io::BufReader`
/// and use `bufread::ZlibDecoder` instead.
///
/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
///
/// # Examples
Expand Down
4 changes: 4 additions & 0 deletions src/zlib/write.rs
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,10 @@ impl<W: Read + Write> Read for ZlibEncoder<W> {
/// This structure implements a [`Write`] and will emit a stream of decompressed
/// data when fed a stream of compressed data.
///
/// After decoding a single member of the ZLIB data this writer will return the number of bytes up to
/// to the end of the ZLIB member and subsequent writes will return Ok(0) allowing the caller to
/// handle any data following the ZLIB member.
///
/// [`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
///
/// # Examples
Expand Down

0 comments on commit 1a0daec

Please sign in to comment.