From 4f949ba2623b0bc11ae7961d53c54409e84834fa Mon Sep 17 00:00:00 2001 From: Andy Gauge Date: Tue, 9 May 2017 14:59:57 -0700 Subject: [PATCH] Examples directory provides runnable examples and doc comments have examples to be compiled into documentation. Examples are for Zlib and Gzip structs --- examples/gzbuilder.rs | 24 ++++ examples/gzdecoder-bufread.rs | 24 ++++ examples/gzdecoder-read.rs | 24 ++++ examples/gzencoder-bufread.rs | 24 ++++ examples/gzencoder-read.rs | 20 +++ examples/gzencoder-write.rs | 12 ++ examples/gzmultidecoder-bufread.rs | 24 ++++ examples/gzmultidecoder-read.rs | 24 ++++ examples/hello_world.txt | 1 + examples/zlibdecoder-bufread.rs | 24 ++++ examples/zlibdecoder-read.rs | 24 ++++ examples/zlibdecoder-write.rs | 26 ++++ examples/zlibencoder-bufread.rs | 24 ++++ examples/zlibencoder-read.rs | 21 +++ examples/zlibencoder-write.rs | 12 ++ src/gz.rs | 204 ++++++++++++++++++++++++++++- src/zlib.rs | 140 ++++++++++++++++++++ 17 files changed, 645 insertions(+), 7 deletions(-) create mode 100644 examples/gzbuilder.rs create mode 100644 examples/gzdecoder-bufread.rs create mode 100644 examples/gzdecoder-read.rs create mode 100644 examples/gzencoder-bufread.rs create mode 100644 examples/gzencoder-read.rs create mode 100644 examples/gzencoder-write.rs create mode 100644 examples/gzmultidecoder-bufread.rs create mode 100644 examples/gzmultidecoder-read.rs create mode 100644 examples/hello_world.txt create mode 100644 examples/zlibdecoder-bufread.rs create mode 100644 examples/zlibdecoder-read.rs create mode 100644 examples/zlibdecoder-write.rs create mode 100644 examples/zlibencoder-bufread.rs create mode 100644 examples/zlibencoder-read.rs create mode 100644 examples/zlibencoder-write.rs diff --git a/examples/gzbuilder.rs b/examples/gzbuilder.rs new file mode 100644 index 000000000..a61a03f4f --- /dev/null +++ b/examples/gzbuilder.rs @@ -0,0 +1,24 @@ +extern crate flate2; + +use std::io::prelude::*; +use std::io; +use std::fs::File; +use flate2::GzBuilder; +use flate2::Compression; + +// Open file and debug print the contents compressed with gzip +fn main() { + sample_builder().unwrap(); +} + +// GzBuilder opens a file and writes a sample string using Builder pattern +fn sample_builder() -> Result<(), io::Error> { + let f = File::create("examples/hello_world.gz")?; + let mut gz = GzBuilder::new() + .filename("hello_world.txt") + .comment("test file, please delete") + .write(f, Compression::Default); + gz.write(b"hello world")?; + gz.finish()?; + Ok(()) +} diff --git a/examples/gzdecoder-bufread.rs b/examples/gzdecoder-bufread.rs new file mode 100644 index 000000000..77f325194 --- /dev/null +++ b/examples/gzdecoder-bufread.rs @@ -0,0 +1,24 @@ +extern crate flate2; + +use std::io::prelude::*; +use std::io; +use flate2::Compression; +use flate2::write::GzEncoder; +use flate2::bufread::GzDecoder; + +// Compress a sample string and print it after transformation. +fn main() { + let mut e = GzEncoder::new(Vec::new(), Compression::Default); + e.write(b"Hello World").unwrap(); + let bytes = e.finish().unwrap(); + println!("{}", decode_reader(bytes).unwrap()); +} + +// Uncompresses a Gz Encoded vector of bytes and returns a string or error +// Here &[u8] implements BufRead +fn decode_reader(bytes: Vec) -> io::Result { + let mut gz = GzDecoder::new(&bytes[..])?; + let mut s = String::new(); + gz.read_to_string(&mut s)?; + Ok(s) +} diff --git a/examples/gzdecoder-read.rs b/examples/gzdecoder-read.rs new file mode 100644 index 000000000..843d7bd6a --- /dev/null +++ b/examples/gzdecoder-read.rs @@ -0,0 +1,24 @@ +extern crate flate2; + +use std::io::prelude::*; +use std::io; +use flate2::Compression; +use flate2::write::GzEncoder; +use flate2::read::GzDecoder; + +// Compress a sample string and print it after transformation. +fn main() { + let mut e = GzEncoder::new(Vec::new(), Compression::Default); + e.write(b"Hello World").unwrap(); + let bytes = e.finish().unwrap(); + println!("{}", decode_reader(bytes).unwrap()); +} + +// Uncompresses a Gz Encoded vector of bytes and returns a string or error +// Here &[u8] implements Read +fn decode_reader(bytes: Vec) -> io::Result { + let mut gz = GzDecoder::new(&bytes[..])?; + let mut s = String::new(); + gz.read_to_string(&mut s)?; + Ok(s) +} diff --git a/examples/gzencoder-bufread.rs b/examples/gzencoder-bufread.rs new file mode 100644 index 000000000..8b320d813 --- /dev/null +++ b/examples/gzencoder-bufread.rs @@ -0,0 +1,24 @@ +extern crate flate2; + +use std::io::prelude::*; +use std::io; +use flate2::Compression; +use flate2::bufread::GzEncoder; +use std::fs::File; +use std::io::BufReader; + +// Open file and debug print the contents compressed with gzip +fn main() { + println!("{:?}", open_hello_world().unwrap()); +} + +// Opens sample file, compresses the contents and returns a Vector or error +// File wrapped in a BufReader implements Bufread +fn open_hello_world() -> io::Result> { + let f = File::open("examples/hello_world.txt")?; + let b = BufReader::new(f); + let mut gz = GzEncoder::new(b, Compression::Fast); + let mut buffer = Vec::new(); + gz.read_to_end(&mut buffer)?; + Ok(buffer) +} diff --git a/examples/gzencoder-read.rs b/examples/gzencoder-read.rs new file mode 100644 index 000000000..65dd26bc4 --- /dev/null +++ b/examples/gzencoder-read.rs @@ -0,0 +1,20 @@ +extern crate flate2; + +use std::io::prelude::*; +use std::io; +use flate2::Compression; +use flate2::read::GzEncoder; + +// Print the GZ compressed representation of hello world +fn main() { + println!("{:?}", gzencoder_read_hello_world().unwrap()); +} + +// Return a vector containing the GZ compressed version of hello world +fn gzencoder_read_hello_world() -> io::Result> { + let mut ret_vec = [0;100]; + let c = b"hello world"; + let mut z = GzEncoder::new(&c[..], Compression::Fast); + let count = z.read(&mut ret_vec)?; + Ok(ret_vec[0..count].to_vec()) +} diff --git a/examples/gzencoder-write.rs b/examples/gzencoder-write.rs new file mode 100644 index 000000000..b423b5241 --- /dev/null +++ b/examples/gzencoder-write.rs @@ -0,0 +1,12 @@ +extern crate flate2; + +use std::io::prelude::*; +use flate2::Compression; +use flate2::write::GzEncoder; + +// Vec implements Write to print the compressed bytes of sample string +fn main() { + let mut e = GzEncoder::new(Vec::new(), Compression::Default); + e.write(b"Hello World").unwrap(); + println!("{:?}", e.finish().unwrap()); +} diff --git a/examples/gzmultidecoder-bufread.rs b/examples/gzmultidecoder-bufread.rs new file mode 100644 index 000000000..d5db3673e --- /dev/null +++ b/examples/gzmultidecoder-bufread.rs @@ -0,0 +1,24 @@ +extern crate flate2; + +use std::io::prelude::*; +use std::io; +use flate2::Compression; +use flate2::write::GzEncoder; +use flate2::bufread::MultiGzDecoder; + +// Compress a sample string and print it after transformation. +fn main() { + let mut e = GzEncoder::new(Vec::new(), Compression::Default); + e.write(b"Hello World").unwrap(); + let bytes = e.finish().unwrap(); + println!("{}", decode_reader(bytes).unwrap()); +} + +// Uncompresses a Gz Encoded vector of bytes and returns a string or error +// Here &[u8] implements BufRead +fn decode_reader(bytes: Vec) -> io::Result { + let mut gz = MultiGzDecoder::new(&bytes[..])?; + let mut s = String::new(); + gz.read_to_string(&mut s)?; + Ok(s) +} diff --git a/examples/gzmultidecoder-read.rs b/examples/gzmultidecoder-read.rs new file mode 100644 index 000000000..9263292c9 --- /dev/null +++ b/examples/gzmultidecoder-read.rs @@ -0,0 +1,24 @@ +extern crate flate2; + +use std::io::prelude::*; +use std::io; +use flate2::Compression; +use flate2::write::GzEncoder; +use flate2::read::MultiGzDecoder; + +// Compress a sample string and print it after transformation. +fn main() { + let mut e = GzEncoder::new(Vec::new(), Compression::Default); + e.write(b"Hello World").unwrap(); + let bytes = e.finish().unwrap(); + println!("{}", decode_reader(bytes).unwrap()); +} + +// Uncompresses a Gz Encoded vector of bytes and returns a string or error +// Here &[u8] implements Read +fn decode_reader(bytes: Vec) -> io::Result { + let mut gz = MultiGzDecoder::new(&bytes[..])?; + let mut s = String::new(); + gz.read_to_string(&mut s)?; + Ok(s) +} diff --git a/examples/hello_world.txt b/examples/hello_world.txt new file mode 100644 index 000000000..557db03de --- /dev/null +++ b/examples/hello_world.txt @@ -0,0 +1 @@ +Hello World diff --git a/examples/zlibdecoder-bufread.rs b/examples/zlibdecoder-bufread.rs new file mode 100644 index 000000000..7216f801e --- /dev/null +++ b/examples/zlibdecoder-bufread.rs @@ -0,0 +1,24 @@ +extern crate flate2; + +use std::io::prelude::*; +use std::io; +use flate2::Compression; +use flate2::write::ZlibEncoder; +use flate2::bufread::ZlibDecoder; + +// Compress a sample string and print it after transformation. +fn main() { + let mut e = ZlibEncoder::new(Vec::new(), Compression::Default); + e.write(b"Hello World").unwrap(); + let bytes = e.finish().unwrap(); + println!("{}", decode_bufreader(bytes).unwrap()); +} + +// Uncompresses a Zlib Encoded vector of bytes and returns a string or error +// Here &[u8] implements BufRead +fn decode_bufreader(bytes: Vec) -> io::Result { + let mut z = ZlibDecoder::new(&bytes[..]); + let mut s = String::new(); + z.read_to_string(&mut s)?; + Ok(s) +} diff --git a/examples/zlibdecoder-read.rs b/examples/zlibdecoder-read.rs new file mode 100644 index 000000000..ab82413fb --- /dev/null +++ b/examples/zlibdecoder-read.rs @@ -0,0 +1,24 @@ +extern crate flate2; + +use std::io::prelude::*; +use std::io; +use flate2::Compression; +use flate2::write::ZlibEncoder; +use flate2::read::ZlibDecoder; + +// Compress a sample string and print it after transformation. +fn main() { + let mut e = ZlibEncoder::new(Vec::new(), Compression::Default); + e.write(b"Hello World").unwrap(); + let bytes = e.finish().unwrap(); + println!("{}", decode_reader(bytes).unwrap()); +} + +// Uncompresses a Zlib Encoded vector of bytes and returns a string or error +// Here &[u8] implements Read +fn decode_reader(bytes: Vec) -> io::Result { + let mut z = ZlibDecoder::new(&bytes[..]); + let mut s = String::new(); + z.read_to_string(&mut s)?; + Ok(s) +} diff --git a/examples/zlibdecoder-write.rs b/examples/zlibdecoder-write.rs new file mode 100644 index 000000000..c70ded3c1 --- /dev/null +++ b/examples/zlibdecoder-write.rs @@ -0,0 +1,26 @@ +extern crate flate2; + +use std::io::prelude::*; +use std::io; +use flate2::Compression; +use flate2::write::ZlibEncoder; +use flate2::write::ZlibDecoder; + +// Compress a sample string and print it after transformation. +fn main() { + let mut e = ZlibEncoder::new(Vec::new(), Compression::Default); + e.write(b"Hello World").unwrap(); + let bytes = e.finish().unwrap(); + println!("{}", decode_reader(bytes).unwrap()); +} + +// Uncompresses a Zlib Encoded vector of bytes and returns a string or error +// Here Vec implements Write +fn decode_reader(bytes: Vec) -> io::Result { + let mut writer = Vec::new(); + let mut z = ZlibDecoder::new(writer); + z.write(&bytes[..])?; + writer = z.finish()?; + let return_string = String::from_utf8(writer).expect("String parsing error"); + Ok(return_string) +} diff --git a/examples/zlibencoder-bufread.rs b/examples/zlibencoder-bufread.rs new file mode 100644 index 000000000..39d93611a --- /dev/null +++ b/examples/zlibencoder-bufread.rs @@ -0,0 +1,24 @@ +extern crate flate2; + +use std::io::prelude::*; +use std::io; +use flate2::Compression; +use flate2::bufread::ZlibEncoder; +use std::fs::File; +use std::io::BufReader; + +// Open file and debug print the contents compressed with zlib +fn main() { + println!("{:?}", open_hello_world().unwrap()); +} + +// Opens sample file, compresses the contents and returns a Vector or error +// File wrapped in a BufReader implements Bufread +fn open_hello_world() -> io::Result> { + let f = File::open("examples/hello_world.txt")?; + let b = BufReader::new(f); + let mut z = ZlibEncoder::new(b, Compression::Fast); + let mut buffer = Vec::new(); + z.read_to_end(&mut buffer)?; + Ok(buffer) +} diff --git a/examples/zlibencoder-read.rs b/examples/zlibencoder-read.rs new file mode 100644 index 000000000..3aef92ca4 --- /dev/null +++ b/examples/zlibencoder-read.rs @@ -0,0 +1,21 @@ +extern crate flate2; + +use std::io::prelude::*; +use flate2::Compression; +use flate2::read::ZlibEncoder; +use std::fs::File; + +// Open file and debug print the compressed contents +fn main() { + println!("{:?}", open_hello_world().unwrap()); +} + +// Opens sample file, compresses the contents and returns a Vector or error +// File implements Read +fn open_hello_world() -> std::io::Result> { + let f = File::open("examples/hello_world.txt")?; + let mut z = ZlibEncoder::new(f, Compression::Fast); + let mut buffer = [0;50]; + let byte_count = z.read(&mut buffer)?; + Ok(buffer[0..byte_count].to_vec()) +} diff --git a/examples/zlibencoder-write.rs b/examples/zlibencoder-write.rs new file mode 100644 index 000000000..9152b30ea --- /dev/null +++ b/examples/zlibencoder-write.rs @@ -0,0 +1,12 @@ +extern crate flate2; + +use std::io::prelude::*; +use flate2::Compression; +use flate2::write::ZlibEncoder; + +// Vec implements Write to print the compressed bytes of sample string +fn main() { + let mut e = ZlibEncoder::new(Vec::new(), Compression::Default); + e.write(b"Hello World").unwrap(); + println!("{:?}", e.finish().unwrap()); +} diff --git a/src/gz.rs b/src/gz.rs index 7976c51e5..2f26d96f2 100644 --- a/src/gz.rs +++ b/src/gz.rs @@ -32,6 +32,22 @@ static FCOMMENT: u8 = 1 << 4; /// to the underlying writer `W`. /// /// [`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html +/// +/// # Examples +/// +/// ``` +/// use std::io::prelude::*; +/// use flate2::Compression; +/// use flate2::write::GzEncoder; +/// +/// // Vec implements Write to print the compressed bytes of sample string +/// # fn main() { +/// +/// let mut e = GzEncoder::new(Vec::new(), Compression::Default); +/// e.write(b"Hello World").unwrap(); +/// println!("{:?}", e.finish().unwrap()); +/// # } +/// ``` #[derive(Debug)] pub struct EncoderWriter { inner: zio::Writer, @@ -47,6 +63,25 @@ pub struct EncoderWriter { /// interface. /// /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html +/// +/// # Examples +/// +/// ``` +/// use std::io::prelude::*; +/// use std::io; +/// use flate2::Compression; +/// use flate2::read::GzEncoder; +/// +/// // Return a vector containing the GZ compressed version of hello world +/// +/// fn gzencode_hello_world() -> io::Result> { +/// let mut ret_vec = [0;100]; +/// let bytestring = b"hello world"; +/// let mut gz = GzEncoder::new(&bytestring[..], Compression::Fast); +/// let count = gz.read(&mut ret_vec)?; +/// Ok(ret_vec[0..count].to_vec()) +/// } +/// ``` #[derive(Debug)] pub struct EncoderReader { inner: EncoderReaderBuf>, @@ -54,11 +89,34 @@ pub struct EncoderReader { /// A gzip streaming encoder /// -/// This structure exposes a [`Read`] interface that will read uncompressed data -/// from the underlying reader and expose the compressed version as a [`Read`] +/// This structure exposes a [`BufRead`] interface that will read uncompressed data +/// from the underlying reader and expose the compressed version as a [`BufRead`] /// interface. /// -/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html +/// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html +/// +/// # Examples +/// +/// ``` +/// use std::io::prelude::*; +/// use std::io; +/// use flate2::Compression; +/// use flate2::bufread::GzEncoder; +/// use std::fs::File; +/// use std::io::BufReader; +/// +/// // Opens sample file, compresses the contents and returns a Vector or error +/// // File wrapped in a BufReader implements BufRead +/// +/// fn open_hello_world() -> io::Result> { +/// let f = File::open("examples/hello_world.txt")?; +/// let b = BufReader::new(f); +/// let mut gz = GzEncoder::new(b, Compression::Fast); +/// let mut buffer = Vec::new(); +/// gz.read_to_end(&mut buffer)?; +/// Ok(buffer) +/// } +/// ``` #[derive(Debug)] pub struct EncoderReaderBuf { inner: deflate::EncoderReaderBuf>, @@ -70,6 +128,29 @@ pub struct EncoderReaderBuf { /// A builder structure to create a new gzip Encoder. /// /// This structure controls header configuration options such as the filename. +/// +/// # Examples +/// +/// ``` +/// use std::io::prelude::*; +/// # use std::io; +/// use std::fs::File; +/// use flate2::GzBuilder; +/// use flate2::Compression; +/// +/// // GzBuilder opens a file and writes a sample string using Builder pattern +/// +/// # fn sample_builder() -> Result<(), io::Error> { +/// let f = File::create("examples/hello_world.gz")?; +/// let mut gz = GzBuilder::new() +/// .filename("hello_world.txt") +/// .comment("test file, please delete") +/// .write(f, Compression::Default); +/// gz.write(b"hello world")?; +/// gz.finish()?; +/// # Ok(()) +/// # } +/// ``` #[derive(Debug)] pub struct Builder { extra: Option>, @@ -84,6 +165,34 @@ pub struct Builder { /// data from the underlying reader and emit uncompressed data. /// /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html +/// +/// # Examples +/// +/// ``` +/// +/// use std::io::prelude::*; +/// use std::io; +/// # use flate2::Compression; +/// # use flate2::write::GzEncoder; +/// use flate2::read::GzDecoder; +/// +/// # fn main() { +/// # let mut e = GzEncoder::new(Vec::new(), Compression::Default); +/// # e.write(b"Hello World").unwrap(); +/// # let bytes = e.finish().unwrap(); +/// # println!("{}", decode_reader(bytes).unwrap()); +/// # } +/// # +/// // Uncompresses a Gz Encoded vector of bytes and returns a string or error +/// // Here &[u8] implements Read +/// +/// fn decode_reader(bytes: Vec) -> io::Result { +/// let mut gz = GzDecoder::new(&bytes[..])?; +/// let mut s = String::new(); +/// gz.read_to_string(&mut s)?; +/// Ok(s) +/// } +/// ``` #[derive(Debug)] pub struct DecoderReader { inner: DecoderReaderBuf>, @@ -102,6 +211,33 @@ pub struct DecoderReader { /// from the underlying reader and emit uncompressed data. /// /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html +/// +/// # Examples +/// +/// ``` +/// use std::io::prelude::*; +/// use std::io; +/// # use flate2::Compression; +/// # use flate2::write::GzEncoder; +/// use flate2::read::MultiGzDecoder; +/// +/// # fn main() { +/// # let mut e = GzEncoder::new(Vec::new(), Compression::Default); +/// # e.write(b"Hello World").unwrap(); +/// # let bytes = e.finish().unwrap(); +/// # println!("{}", decode_reader(bytes).unwrap()); +/// # } +/// # +/// // Uncompresses a Gz Encoded vector of bytes and returns a string or error +/// // Here &[u8] implements Read +/// +/// fn decode_reader(bytes: Vec) -> io::Result { +/// let mut gz = MultiGzDecoder::new(&bytes[..])?; +/// let mut s = String::new(); +/// gz.read_to_string(&mut s)?; +/// Ok(s) +/// } +/// ``` #[derive(Debug)] pub struct MultiDecoderReader { inner: MultiDecoderReaderBuf>, @@ -109,10 +245,37 @@ pub struct MultiDecoderReader { /// A gzip streaming decoder /// -/// This structure exposes a [`Read`] interface that will consume compressed +/// This structure exposes a [`ReadBuf`] interface that will consume compressed /// data from the underlying reader and emit uncompressed data. /// -/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html +/// [`ReadBuf`]: https://doc.rust-lang.org/std/io/trait.BufRead.html +/// +/// # Examples +/// +/// ``` +/// use std::io::prelude::*; +/// use std::io; +/// # use flate2::Compression; +/// # use flate2::write::GzEncoder; +/// use flate2::bufread::GzDecoder; +/// +/// # fn main() { +/// # let mut e = GzEncoder::new(Vec::new(), Compression::Default); +/// # e.write(b"Hello World").unwrap(); +/// # let bytes = e.finish().unwrap(); +/// # println!("{}", decode_reader(bytes).unwrap()); +/// # } +/// # +/// // Uncompresses a Gz Encoded vector of bytes and returns a string or error +/// // Here &[u8] implements BufRead +/// +/// fn decode_reader(bytes: Vec) -> io::Result { +/// let mut gz = GzDecoder::new(&bytes[..])?; +/// let mut s = String::new(); +/// gz.read_to_string(&mut s)?; +/// Ok(s) +/// } +/// ``` #[derive(Debug)] pub struct DecoderReaderBuf { inner: CrcReader>, @@ -129,10 +292,37 @@ pub struct DecoderReaderBuf { /// the first gzip member. The multistream format is commonly used in /// bioinformatics, for example when using the BGZF compressed data. /// -/// This structure exposes a [`Read`] interface that will consume all gzip members +/// This structure exposes a [`BufRead`] interface that will consume all gzip members /// from the underlying reader and emit uncompressed data. /// -/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html +/// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html +/// +/// # Examples +/// +/// ``` +/// use std::io::prelude::*; +/// use std::io; +/// # use flate2::Compression; +/// # use flate2::write::GzEncoder; +/// use flate2::bufread::MultiGzDecoder; +/// +/// # fn main() { +/// # let mut e = GzEncoder::new(Vec::new(), Compression::Default); +/// # e.write(b"Hello World").unwrap(); +/// # let bytes = e.finish().unwrap(); +/// # println!("{}", decode_reader(bytes).unwrap()); +/// # } +/// # +/// // Uncompresses a Gz Encoded vector of bytes and returns a string or error +/// // Here &[u8] implements BufRead +/// +/// fn decode_reader(bytes: Vec) -> io::Result { +/// let mut gz = MultiGzDecoder::new(&bytes[..])?; +/// let mut s = String::new(); +/// gz.read_to_string(&mut s)?; +/// Ok(s) +/// } +/// ``` #[derive(Debug)] pub struct MultiDecoderReaderBuf { inner: CrcReader>, diff --git a/src/zlib.rs b/src/zlib.rs index 86d2246a1..3a81f2fad 100644 --- a/src/zlib.rs +++ b/src/zlib.rs @@ -19,6 +19,23 @@ use {Compress, Decompress}; /// uncompressed data, writing the compressed data to the wrapped writer. /// /// [`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html +/// +/// # Examples +/// +/// ``` +/// use std::io::prelude::*; +/// use flate2::Compression; +/// use flate2::write::ZlibEncoder; +/// +/// // Vec implements Write, assigning the compressed bytes of sample string +/// +/// # fn zlib_encoding() -> std::io::Result<()> { +/// let mut e = ZlibEncoder::new(Vec::new(), Compression::Default); +/// e.write(b"Hello World")?; +/// let compressed = e.finish()?; +/// # Ok(()) +/// # } +/// ``` #[derive(Debug)] pub struct EncoderWriter { inner: zio::Writer, @@ -30,6 +47,25 @@ pub struct EncoderWriter { /// data from an underlying stream and emit a stream of compressed data. /// /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html +/// +/// # Examples +/// +/// ``` +/// use std::io::prelude::*; +/// use flate2::Compression; +/// use flate2::read::ZlibEncoder; +/// use std::fs::File; +/// +/// // Open example file and compress the contents using Read interface +/// +/// # fn open_hello_world() -> std::io::Result> { +/// let f = File::open("examples/hello_world.txt")?; +/// let mut z = ZlibEncoder::new(f, Compression::Fast); +/// let mut buffer = [0;50]; +/// let byte_count = z.read(&mut buffer)?; +/// # Ok(buffer[0..byte_count].to_vec()) +/// # } +/// ``` #[derive(Debug)] pub struct EncoderReader { inner: EncoderReaderBuf>, @@ -41,6 +77,27 @@ pub struct EncoderReader { /// data from an underlying stream and emit a stream of compressed data. /// /// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html +/// +/// # Examples +/// +/// ``` +/// use std::io::prelude::*; +/// use flate2::Compression; +/// use flate2::bufread::ZlibEncoder; +/// use std::fs::File; +/// use std::io::BufReader; +/// +/// // Use a buffered file to compress contents into a Vec +/// +/// # fn open_hello_world() -> std::io::Result> { +/// let f = File::open("examples/hello_world.txt")?; +/// let b = BufReader::new(f); +/// let mut z = ZlibEncoder::new(b, Compression::Fast); +/// let mut buffer = Vec::new(); +/// z.read_to_end(&mut buffer)?; +/// # Ok(buffer) +/// # } +/// ``` #[derive(Debug)] pub struct EncoderReaderBuf { obj: R, @@ -53,6 +110,33 @@ pub struct EncoderReaderBuf { /// compressed data as input, providing the decompressed data when read from. /// /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html +/// +/// # Examples +/// +/// ``` +/// use std::io::prelude::*; +/// use std::io; +/// # use flate2::Compression; +/// # use flate2::write::ZlibEncoder; +/// use flate2::read::ZlibDecoder; +/// +/// # fn main() { +/// # let mut e = ZlibEncoder::new(Vec::new(), Compression::Default); +/// # e.write(b"Hello World").unwrap(); +/// # let bytes = e.finish().unwrap(); +/// # println!("{}", decode_reader(bytes).unwrap()); +/// # } +/// # +/// // Uncompresses a Zlib Encoded vector of bytes and returns a string or error +/// // Here &[u8] implements Read +/// +/// fn decode_reader(bytes: Vec) -> io::Result { +/// let mut z = ZlibDecoder::new(&bytes[..]); +/// let mut s = String::new(); +/// z.read_to_string(&mut s)?; +/// Ok(s) +/// } +/// ``` #[derive(Debug)] pub struct DecoderReader { inner: DecoderReaderBuf>, @@ -64,6 +148,33 @@ pub struct DecoderReader { /// compressed data as input, providing the decompressed data when read from. /// /// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html +/// +/// # Examples +/// +/// ``` +/// use std::io::prelude::*; +/// use std::io; +/// # use flate2::Compression; +/// # use flate2::write::ZlibEncoder; +/// use flate2::bufread::ZlibDecoder; +/// +/// # fn main() { +/// # let mut e = ZlibEncoder::new(Vec::new(), Compression::Default); +/// # e.write(b"Hello World").unwrap(); +/// # let bytes = e.finish().unwrap(); +/// # println!("{}", decode_bufreader(bytes).unwrap()); +/// # } +/// # +/// // Uncompresses a Zlib Encoded vector of bytes and returns a string or error +/// // Here &[u8] implements BufRead +/// +/// fn decode_bufreader(bytes: Vec) -> io::Result { +/// let mut z = ZlibDecoder::new(&bytes[..]); +/// let mut s = String::new(); +/// z.read_to_string(&mut s)?; +/// Ok(s) +/// } +/// ``` #[derive(Debug)] pub struct DecoderReaderBuf { obj: R, @@ -76,6 +187,35 @@ pub struct DecoderReaderBuf { /// data when fed a stream of compressed data. /// /// [`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html +/// +/// # Examples +/// +/// ``` +/// use std::io::prelude::*; +/// use std::io; +/// # use flate2::Compression; +/// # use flate2::write::ZlibEncoder; +/// use flate2::write::ZlibDecoder; +/// +/// # fn main() { +/// # let mut e = ZlibEncoder::new(Vec::new(), Compression::Default); +/// # e.write(b"Hello World").unwrap(); +/// # let bytes = e.finish().unwrap(); +/// # println!("{}", decode_reader(bytes).unwrap()); +/// # } +/// # +/// // Uncompresses a Zlib Encoded vector of bytes and returns a string or error +/// // Here Vec implements Write +/// +/// fn decode_reader(bytes: Vec) -> io::Result { +/// let mut writer = Vec::new(); +/// let mut z = ZlibDecoder::new(writer); +/// z.write(&bytes[..])?; +/// writer = z.finish()?; +/// let return_string = String::from_utf8(writer).expect("String parsing error"); +/// Ok(return_string) +/// } +/// ``` #[derive(Debug)] pub struct DecoderWriter { inner: zio::Writer,