add in the example snippets

Author: molpopgen

book/src/table_collection_column_access.md

@@ -1,3 +1,14 @@
 ## Accessing table columns
 
-Not done yet.
+We can access table rows using either the relevant newtype or `i32` (which is identical to the `tskit-c` typedef `tsk_id_t`).
+The following snippet adds and edge and then validates the data for that row of the table:
+
+```rust, noplaygound, ignore
+{{#include ../../tests/book_table_collection.rs:get_edge_table_columns}}
+```
+
+The return type of the getters is the [`Option`](https://doc.rust-lang.org/std/option/enum.Option.html) enum. The `None` variant is returned when row indexes are out of range:
+
+```rust, noplaygound, ignore
+{{#include ../../tests/book_table_collection.rs:get_edge_table_columns_out_of_range}}
+```

book/src/table_collection_row_access.md

@@ -1,3 +1,15 @@
 ## Accessing table rows
 
-To be written!
+We may also access entire table rows by a row id:
+
+```rust, noplaygound, ignore
+{{#include ../../tests/book_table_collection.rs:get_edge_table_row_by_id}}
+```
+
+The row types are rust structures. The table data are *copied* into these structures, making them relatively more expensive to work with. We are looking into removing the copies and returning slices, but doing so currently impacts the design of table row iterators such as:
+
+```rust, noplaygound, ignore
+{{#include ../../tests/book_table_collection.rs:get_edge_table_rows_by_iterator}}
+```
+
+These iterators are rust iterator types--they `impl Iterator<Item=X>`, where `X` is a table row type.

tests/book_table_collection.rs

@@ -82,6 +82,7 @@ fn get_data_from_edge_table() {
         std::mem::swap(&mut left, &mut right);
     }
 
+    // ANCHOR: get_edge_table_columns
     if let Ok(edge_id) = tables.add_edge(left, right, parent, child) {
         // Take a reference to an edge table (& tskit::EdgeTable)
         let edges = tables.edges();
@@ -100,8 +101,15 @@ fn get_data_from_edge_table() {
     } else {
         panic!("that should have worked...");
     }
+    // ANCHOR_END: get_edge_table_columns
 
-    if let Some(row) = tables.edges().row(0) {
+    // ANCHOR: get_edge_table_columns_out_of_range
+    assert!(tables.edges().parent(tskit::EdgeId::NULL).is_none());
+    // ANCHOR_END: get_edge_table_columns_out_of_range
+
+    let edge_id = tskit::EdgeId::from(0);
+    // ANCHOR: get_edge_table_row_by_id
+    if let Some(row) = tables.edges().row(edge_id) {
         assert_eq!(row.id, 0);
         assert_eq!(row.left, left);
         assert_eq!(row.right, right);
@@ -110,7 +118,9 @@ fn get_data_from_edge_table() {
     } else {
         panic!("that should have worked...");
     }
+    // ANCHOR_END: get_edge_table_row_by_id
 
+    // ANCHOR: get_edge_table_rows_by_iterator
     for row in tables.edges_iter() {
         // there is only one row!
         assert_eq!(row.id, 0);
@@ -119,6 +129,7 @@ fn get_data_from_edge_table() {
         assert_eq!(row.parent, parent);
         assert_eq!(row.child, child);
     }
+    // ANCHOR_END: get_edge_table_rows_by_iterator
 
     assert!(tables
         .check_integrity(tskit::TableIntegrityCheckFlags::default())