Merge #172: Add "commonly used operations" examples

c977624 Add "commonly used operations" examples (Dawid Ciężarkiewicz)

Pull request description:

  For a fresh user like me it was was relatively hard to figure out even the basic usage. I hope these simple examples will save some time for other newcomers and help describe what this library is about.

ACKs for top commit:
  tcharding:
    ACK c977624
  apoelstra:
    ACK c977624

Tree-SHA512: 2189bdf9b974c25f2ba56735bbb979317c3f5787fa5decccbcd2fbf846d98a5c6a7f66940e4e5d15b512e84536a5b1358f03e179b11ad5060cb608be471ffe43

Author: apoelstra

src/lib.rs

@@ -19,6 +19,63 @@
 //! thing, it exposes hexadecimal serialization and deserialization, since these
 //! are needed to display hashes anway.
 //!
+//! ## Commonly used operations
+//!
+//! Hashing a single byte slice or a string:
+//!
+//! ```rust
+//! use bitcoin_hashes::sha256;
+//! use bitcoin_hashes::Hash;
+//!
+//! let bytes = [0u8; 5];
+//! let hash_of_bytes = sha256::Hash::hash(&bytes);
+//! let hash_of_string = sha256::Hash::hash("some string".as_bytes());
+//! ```
+//!
+//!
+//! Hashing content from a reader:
+//!
+//! ```rust
+//! use bitcoin_hashes::sha256;
+//! use bitcoin_hashes::Hash;
+//!
+//! #[cfg(std)]
+//! # fn main() -> std::io::Result<()> {
+//! let mut reader: &[u8] = b"hello"; // in real code, this could be a `File` or `TcpStream`
+//! let mut engine = sha256::HashEngine::default();
+//! std::io::copy(&mut reader, &mut engine)?;
+//! let hash = sha256::Hash::from_engine(engine);
+//! # Ok(())
+//! # }
+//!
+//! #[cfg(not(std))]
+//! # fn main() {}
+//! ```
+//!
+//!
+//! Hashing content by [`std::io::Write`] on HashEngine:
+//!
+//! ```rust
+//! use bitcoin_hashes::sha256;
+//! use bitcoin_hashes::Hash;
+//! use std::io::Write;
+//!
+//! #[cfg(std)]
+//! # fn main() -> std::io::Result<()> {
+//! let mut part1: &[u8] = b"hello";
+//! let mut part2: &[u8] = b" ";
+//! let mut part3: &[u8] = b"world";
+//! let mut engine = sha256::HashEngine::default();
+//! engine.write_all(part1)?;
+//! engine.write_all(part2)?;
+//! engine.write_all(part3)?;
+//! let hash = sha256::Hash::from_engine(engine);
+//! # Ok(())
+//! # }
+//!
+//! #[cfg(not(std))]
+//! # fn main() {}
+//! ```
 
 // Coding conventions
 #![deny(non_upper_case_globals)]