Add an example of calculating the SHA-256 digest of a file using ring

Cargo.toml

@@ -31,6 +31,7 @@ petgraph = "0.4"
 rand = "0.3"
 rayon = "0.8"
 reqwest = "0.6"
+ring = "0.11.0"
 select = "0.4"
 serde = "1.0"
 serde_derive = "1.0"

src/basics.md

@@ -17,6 +17,7 @@
 | [Extract a list of unique #Hashtags from a text][ex-extract-hashtags] | [![regex-badge]][regex] [![lazy_static-badge]][lazy_static] | [![cat-text-processing-badge]][cat-text-processing] |
 | [Replace all occurrences of one text pattern with another pattern.][ex-regex-replace-named] | [![regex-badge]][regex] [![lazy_static-badge]][lazy_static] | [![cat-text-processing-badge]][cat-text-processing] |
 | [Extract phone numbers from text][ex-phone] | [![regex-badge]][regex] | [![cat-text-processing-badge]][cat-text-processing] |
+| [Calculate the SHA-256 digest of a file][ex-sha-digest] | [![ring-badge]][ring] [![data-encoding-badge]][data-encoding] | [![cat-filesystem-badge]][cat-filesystem] |
 
 
 [ex-std-read-lines]: #ex-std-read-lines
@@ -748,6 +749,67 @@ fn run() -> Result<()> {
 
 ```
 
+[ex-sha-digest]: #ex-sha-digest
+<a name="ex-sha-digest"></a>
+## Calculate the SHA-256 digest of a file
+
+[![ring-badge]][ring] [![data-encoding-badge]][data-encoding] [![cat-filesystem-badge]][cat-filesystem]
+
+Writes some data to a file, then calculates the SHA-256 [digest] of
+the file's contents using [`digest::Context`].
+
+```rust
+# #[macro_use]
+# extern crate error_chain;
+#
+extern crate data_encoding;
+extern crate ring;
+
+use data_encoding::HEXUPPER;
+use ring::digest::{Context, Digest, SHA256};
+use std::fs::File;
+use std::io::{BufReader, Read, Write};
+#
+# error_chain! {
+#     foreign_links {
+#         Io(std::io::Error);
+#         Decode(data_encoding::DecodeError);
+#     }
+# }
+
+fn sha256_digest_from_read<R: Read>(mut reader: R) -> Result<Digest> {
+    let mut context = Context::new(&SHA256);
+    loop {
+        let mut buffer = [0; 1024];
+        let count = reader.read(&mut buffer[..])?;
+        if count == 0 {
+            break;
+        }
+        context.update(&buffer[..count]);
+    }
+
+    Ok(context.finish())
+}
+
+fn run() -> Result<()> {
+    let path = "file.txt";
+
+    let mut output = File::create(path)?;
+    write!(output, "We will generate a digest of this text")?;
+
+    let input = File::open(path)?;
+    let reader = BufReader::new(input);
+    let digest = sha256_digest_from_read(reader)?;
+
+    // digest.as_ref() provides the digest as a byte slice: &[u8]
+    println!("SHA-256 digest is {}", HEXUPPER.encode(digest.as_ref()));
+
+    Ok(())
+}
+#
+# quick_main!(run);
+```
+
 <!-- Categories -->
 
 [cat-no-std-badge]: https://badge-cache.kominick.com/badge/no_std--x.svg?style=social
@@ -773,6 +835,8 @@ fn run() -> Result<()> {
 [bitflags]: https://docs.rs/bitflags/
 [byteorder-badge]: https://badge-cache.kominick.com/crates/v/byteorder.svg?label=byteorder
 [byteorder]: https://docs.rs/byteorder/
+[data-encoding-badge]: https://badge-cache.kominick.com/crates/v/data-encoding.svg?label=data-encoding
+[data-encoding]: https://docs.rs/data-encoding/
 [lazy_static]: https://docs.rs/lazy_static/
 [lazy_static-badge]: https://badge-cache.kominick.com/crates/v/lazy_static.svg?label=lazy_static
 [rand-badge]: https://badge-cache.kominick.com/crates/v/rand.svg?label=rand
@@ -783,6 +847,8 @@ fn run() -> Result<()> {
 [regex-badge]: https://badge-cache.kominick.com/crates/v/regex.svg?label=regex
 [memmap]: https://docs.rs/memmap/
 [memmap-badge]: https://badge-cache.kominick.com/crates/v/memmap.svg?label=memmap
+[ring]: https://docs.rs/ring/
+[ring-badge]: https://badge-cache.kominick.com/crates/v/ring.svg?label=ring
 
 <!-- API links -->
 
@@ -818,6 +884,8 @@ fn run() -> Result<()> {
 [`MutexGuard`]: https://doc.rust-lang.org/std/sync/struct.MutexGuard.html
 [`Mmap::as_slice`]: https://docs.rs/memmap/*/memmap/struct.Mmap.html#method.as_slice
 [`seek`]: https://doc.rust-lang.org/std/fs/struct.File.html#method.seek
+[`digest::Context`]: https://docs.rs/ring/*/ring/digest/struct.Context.html
+[digest]: https://docs.rs/ring/*/ring/digest/struct.Digest.html
 
 <!-- Reference -->
 

src/encoding.md

@@ -553,7 +553,7 @@ fn run() -> Result<()> {
 [base64-badge]: https://badge-cache.kominick.com/crates/v/base64.svg?label=base64
 [base64]: https://docs.rs/base64/
 [data-encoding-badge]: https://badge-cache.kominick.com/crates/v/data-encoding.svg?label=data-encoding
-[data-encoding]: https://github.com/ia0/data-encoding
+[data-encoding]: https://docs.rs/data-encoding/
 [serde-json-badge]: https://badge-cache.kominick.com/crates/v/serde_json.svg?label=serde_json
 [serde-json]: https://docs.serde.rs/serde_json/
 [toml-badge]: https://badge-cache.kominick.com/crates/v/toml.svg?label=toml

src/intro.md

@@ -35,6 +35,8 @@ community. It needs and welcomes help. For details see
 | [Extract a list of unique #Hashtags from a text][ex-extract-hashtags] | [![regex-badge]][regex] [![lazy_static-badge]][lazy_static] | [![cat-text-processing-badge]][cat-text-processing] |
 | [Replace all occurrences of one text pattern with another pattern.][ex-regex-replace-named] | [![regex-badge]][regex] [![lazy_static-badge]][lazy_static] | [![cat-text-processing-badge]][cat-text-processing] |
 | [Extract phone numbers from text][ex-phone] | [![regex-badge]][regex] | [![cat-text-processing-badge]][cat-text-processing] |
+| [Calculate the SHA-256 digest of a file][ex-sha-digest] | [![ring-badge]][ring] [![data-encoding-badge]][data-encoding] | [![cat-filesystem-badge]][cat-filesystem] |
+
 
 ## [Encoding](encoding.html)
 
@@ -200,6 +202,8 @@ Keep lines sorted.
 [regex]: https://docs.rs/regex/
 [reqwest-badge]: https://badge-cache.kominick.com/crates/v/reqwest.svg?label=reqwest
 [reqwest]: https://docs.rs/reqwest/
+[ring-badge]: https://badge-cache.kominick.com/crates/v/ring.svg?label=ring
+[ring]: https://docs.rs/ring/
 [same_file-badge]: https://badge-cache.kominick.com/crates/v/same_file.svg?label=same_file
 [same_file]: https://docs.rs/same-file/
 [select-badge]: https://badge-cache.kominick.com/crates/v/select.svg?label=select
@@ -276,6 +280,7 @@ Keep lines sorted.
 [ex-rest-head]: net.html#ex-rest-head
 [ex-rest-post]: net.html#ex-rest-post
 [ex-serialize-csv]: encoding.html#ex-serialize-csv
+[ex-sha-digest]: basics.html#ex-sha-digest
 [ex-std-read-lines]: basics.html#ex-std-read-lines
 [ex-tar-compress]: app.html#ex-tar-compress
 [ex-tar-decompress]: app.html#ex-tar-decompress