Merge pull request rust-lang#115 from AndyGauge/examples

crate level examples, including FlateReadExt

examples/deflatedecoder-bufread.rs

@@ -14,7 +14,7 @@ fn main() {
     println!("{}", decode_reader(bytes).unwrap());
 }
 
-// Uncompresses a Gz Encoded vector of bytes and returns a string or error
+// Uncompresses a Deflate Encoded vector of bytes and returns a string or error
 // Here &[u8] implements Read
 fn decode_reader(bytes: Vec<u8>) -> io::Result<String> {
     let mut deflater = DeflateDecoder::new(&bytes[..]);

examples/deflatedecoder-read.rs

@@ -14,7 +14,7 @@ fn main() {
     println!("{}", decode_reader(bytes).unwrap());
 }
 
-// Uncompresses a Gz Encoded vector of bytes and returns a string or error
+// Uncompresses a Deflate Encoded vector of bytes and returns a string or error
 // Here &[u8] implements Read
 fn decode_reader(bytes: Vec<u8>) -> io::Result<String> {
     let mut deflater = DeflateDecoder::new(&bytes[..]);

examples/deflateencoder-read.rs

@@ -10,7 +10,7 @@ fn main() {
     println!("{:?}", deflateencoder_read_hello_world().unwrap());
 }
 
-// Return a vector containing the GZ compressed version of hello world
+// Return a vector containing the Defalte compressed version of hello world
 fn deflateencoder_read_hello_world() -> io::Result<Vec<u8>> {
     let mut ret_vec = [0;100];
     let c = b"hello world";

examples/flatereadext.rs

@@ -0,0 +1,22 @@
+extern crate flate2;
+
+use flate2::{FlateReadExt, Compression};
+use std::io::prelude::*;
+use std::io;
+use std::fs::File;
+
+fn main() {
+    println!("{}", run().unwrap());
+}
+
+fn run() -> io::Result<String> {
+    let f = File::open("examples/hello_world.txt")?;
+
+    //gz_encode method comes from FlateReadExt and applies to a std::fs::File
+    let data = f.gz_encode(Compression::Default);
+    let mut buffer = String::new();
+
+    //gz_decode method comes from FlateReadExt and applies to a &[u8]
+    &data.gz_decode()?.read_to_string(&mut buffer)?;
+    Ok(buffer)
+}

src/deflate.rs

@@ -59,7 +59,7 @@ pub struct EncoderWriter<W: Write> {
 /// #    println!("{:?}", deflateencoder_read_hello_world().unwrap());
 /// # }
 /// #
-/// // Return a vector containing the GZ compressed version of hello world
+/// // Return a vector containing the Deflate compressed version of hello world
 /// fn deflateencoder_read_hello_world() -> io::Result<Vec<u8>> {
 ///    let mut ret_vec = [0;100];
 ///    let c = b"hello world";

src/lib.rs

@@ -16,6 +16,21 @@
 //! of data. All types in the [`write`] module work on instances of [`Write`],
 //! whereas all types in the [`read`] module work on instances of [`Read`].
 //!
+//! ```
+//! use flate2::write::GzEncoder;
+//! use flate2::Compression;
+//! use std::io;
+//! use std::io::prelude::*;
+//!
+//! # fn main() { let _ = run(); }
+//! # fn run() -> io::Result<()> {
+//! let mut encoder = GzEncoder::new(Vec::new(), Compression::Default);
+//! encoder.write(b"Example")?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//!
 //! Other various types are provided at the top-level of the crate for
 //! management and dealing with encoders/decoders.
 //!
@@ -33,6 +48,31 @@
 //! [`FlateReadExt`]: trait.FlateReadExt.html
 //! [`FlateWriteExt`]: trait.FlateWriteExt.html
 //!
+//! ```
+//! use flate2::{FlateReadExt, Compression};
+//! use std::io::prelude::*;
+//! use std::io;
+//! use std::fs::File;
+//!
+//! # fn main() {
+//! #    println!("{}", run().unwrap());
+//! # }
+//! #
+//! // Read contents of file with a compression stream, then decompress with GZ
+//!
+//! # fn run() -> io::Result<String> {
+//! let f = File::open("examples/hello_world.txt")?;
+//!
+//! //gz_encode method comes from FlateReadExt and applies to a std::fs::File
+//! let data = f.gz_encode(Compression::Default);
+//! let mut buffer = String::new();
+//!
+//! //gz_decode method comes from FlateReadExt and applies to a &[u8]
+//! &data.gz_decode()?.read_to_string(&mut buffer)?;
+//! # Ok(buffer)
+//! # }
+//! ```
+//!
 //! # Async I/O
 //!
 //! This crate optionally can support async I/O streams with the [Tokio stack] via