From ed66893d69fb696751ba89707c4ce0091c8b8714 Mon Sep 17 00:00:00 2001
From: "Kevin R. Thornton" <krthornt@uci.edu>
Date: Thu, 10 Nov 2022 10:03:09 -0800
Subject: [PATCH] doc: advanced metadata topics in book (#407)

---
 book/src/SUMMARY.md           |  1 +
 book/src/metadata_advanced.md | 23 +++++++++++++++++++++++
 tests/book_metadata.rs        | 29 +++++++++++++++++++++++++++++
 3 files changed, 53 insertions(+)
 create mode 100644 book/src/metadata_advanced.md

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index 39b735f25..33096beb6 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -19,6 +19,7 @@
   - [Defining metadata types in rust](./metadata_derive.md)
   - [Metadata and tables](./metadata_tables.md)
   - [Metadata schema](./metadata_schema.md)
+  - [Advanced topics](./metadata_advanced.md)
 
 * [Error handling](./error_handling.md)
 
diff --git a/book/src/metadata_advanced.md b/book/src/metadata_advanced.md
new file mode 100644
index 000000000..b405599d7
--- /dev/null
+++ b/book/src/metadata_advanced.md
@@ -0,0 +1,23 @@
+## Advanced topics
+
+### Bulk decoding of metadata
+
+To populate a `Vec` with decoded metadata and accounting
+for some rows not having metadata:
+
+* Realize that the decode methods of the `MetadataRoundtrip` trait are associated functions.
+* We can use a lending iterator over rows to avoid unnecessary copying.
+
+Therefore:
+
+```rust, noplayground, ignore
+{{#include ../../tests/book_metadata.rs:metadata_bulk_decode_lending_iter}}
+```
+  
+To filter out rows without metadata:
+
+```rust, noplayground, ignore
+{{#include ../../tests/book_metadata.rs:metadata_bulk_decode_lending_iter_with_filter}}
+```
+
+The first method gives `Vec<Option<M
diff --git a/tests/book_metadata.rs b/tests/book_metadata.rs
index c88143693..ce87a53e1 100644
--- a/tests/book_metadata.rs
+++ b/tests/book_metadata.rs
@@ -1,6 +1,9 @@
 #[cfg(feature = "derive")]
 #[test]
 fn book_mutation_metadata() {
+    use streaming_iterator::StreamingIterator;
+    use tskit::metadata::MetadataRoundtrip;
+
     // ANCHOR: metadata_derive
     #[derive(serde::Serialize, serde::Deserialize, tskit::metadata::MutationMetadata)]
     #[serializer("serde_json")]
@@ -89,4 +92,30 @@ fn book_mutation_metadata() {
         .metadata::<MutationMetadata>(2.into())
         .is_none());
     // ANCHOR_END: metadata_retrieval_none
+
+    // ANCHOR: metadata_bulk_decode_lending_iter
+    let mut mutation_row_lending_iterator = tables.mutations().lending_iter();
+    let mut decoded_md = vec![];
+    while let Some(row_view) = mutation_row_lending_iterator.next() {
+        match row_view.metadata {
+            Some(slice) => decoded_md.push(Some(MutationMetadata::decode(slice).unwrap())),
+            None => decoded_md.push(None),
+        }
+    }
+    // ANCHOR_END: metadata_bulk_decode_lending_iter
+
+    // ANCHOR: metadata_bulk_decode_lending_iter_with_filter
+    let mut mutation_row_lending_iterator = tables.mutations().lending_iter();
+    let mut decoded_md = vec![];
+    while let Some(row_view) = mutation_row_lending_iterator
+        .next()
+        .filter(|rv| rv.metadata.is_some())
+    {
+        decoded_md.push((
+            row_view.id,
+            // The unwrap will never panic because of our filter
+            MutationMetadata::decode(row_view.metadata.unwrap()).unwrap(),
+        ));
+    }
+    // ANCHOR_END: metadata_bulk_decode_lending_iter_with_filter
 }