Add TableCollection and an error handling scheme.

Author: molpopgen

.gitignore

@@ -1,2 +1,3 @@
 /target
 Cargo.lock
+auto_bindings.rs

Cargo.toml

@@ -8,6 +8,7 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
+thiserror = "1.0"
 
 [build-dependencies]
 bindgen = "0.56.0"

src/_macros.rs

@@ -0,0 +1,66 @@
+#![macro_use]
+
+#[doc(hidden)]
+macro_rules! handle_tsk_return_value {
+    ($code: expr) => {{
+        if $code < 0 {
+            return Err(crate::error::TskitRustError::ErrorCode { code: $code });
+        }
+        return Ok($code);
+    }};
+}
+
+macro_rules! panic_on_tskit_error {
+    ($code: expr) => {
+        if $code < 0 {
+            let c_str = unsafe { std::ffi::CStr::from_ptr(crate::bindings::tsk_strerror($code)) };
+            let str_slice: &str = c_str.to_str().unwrap();
+            let message: String = str_slice.to_owned();
+            panic!("{}", message);
+        }
+    };
+}
+
+macro_rules! unsafe_tsk_column_access {
+    ($i: expr, $lo: expr, $hi: expr, $array: expr) => {{
+        if $i < $lo || ($i as crate::tsk_size_t) >= $hi {
+            return Err(crate::error::TskitRustError::IndexError {});
+        }
+        return Ok(unsafe { *$array.offset($i as isize) });
+    }};
+}
+
+#[cfg(test)]
+mod test {
+    use crate::error::TskitRustError;
+    use crate::TskReturnValue;
+
+    #[test]
+    #[should_panic]
+    fn test_tskit_panic() {
+        panic_on_tskit_error!(-202); // "Node out of bounds"
+    }
+
+    fn return_value_mock(rv: i32) -> TskReturnValue {
+        handle_tsk_return_value!(rv);
+    }
+
+    fn must_not_error(x: TskReturnValue) -> bool {
+        return x.map_or_else(|_: TskitRustError| false, |_| true);
+    }
+
+    fn must_error(x: TskReturnValue) -> bool {
+        return x.map_or_else(|_: TskitRustError| true, |_| false);
+    }
+
+    #[test]
+    fn test_handle_good_return_value() {
+        assert!(must_not_error(return_value_mock(0)));
+        assert!(must_not_error(return_value_mock(1)));
+    }
+
+    #[test]
+    fn test_handle_return_value_test_panic() {
+        assert!(must_error(return_value_mock(-207)));
+    }
+}

src/bindings.rs

@@ -1,8 +1,34 @@
+//! Low-level ("unsafe") bindings to the C API.
+//!
+//! This module is a 1-to-1 mapping of C types
+//! and functions for both tskit and kastore.
+//! The bindings are generate via [bindgen](https://docs.rs/bindgen).
+//!
+//! Using things from this module will be ``unsafe``.
+//! Further, as many of the types require ``init()`` methods
+//! to correctly set up the structs, one has to coerce ``rust``
+//! into allowing uninitialized variables:
+//!
+//! ```
+//! use std::mem::MaybeUninit;
+//! let mut edges: MaybeUninit<tskit_rust::bindings::tsk_edge_table_t> = MaybeUninit::uninit();
+//! unsafe {
+//!     let _ = tskit_rust::bindings::tsk_edge_table_init(edges.as_mut_ptr(), 0);
+//!     let _ = tskit_rust::bindings::tsk_edge_table_add_row(edges.as_mut_ptr(), 0., 10., 0, 1, std::ptr::null(), 0);
+//!     assert_eq!((*edges.as_ptr()).num_rows, 1);
+//!     tskit_rust::bindings::tsk_edge_table_free(edges.as_mut_ptr());
+//! }
+//! ```
+//!
+//! The best source for documentation will be the [tskit docs](https://tskit.readthedocs.io).
+//! Those docs describe the most important parts of the C API.
+//! This module contains the same types/functions with the same names.
+
 // re-export the auto-generate bindings
 pub use crate::auto_bindings::*;
 
 // tskit defines this via a type cast
 // in a macro. bindgen thus misses it.
 // See bindgen issue 316.
+/// "Null" identifier value.
 pub const TSK_NULL: tsk_id_t = -1;
-

src/edge_table.rs

@@ -0,0 +1,62 @@
+use crate::bindings as ll_bindings;
+use crate::{tsk_id_t, tsk_size_t, TskitRustError};
+
+/// An immutable view of an edge table.
+///
+/// These are not created directly.
+/// Instead, use [`TableCollection::edges`](crate::TableCollection::edges)
+/// to get a reference to an existing edge table;
+pub struct EdgeTable<'a> {
+    table_: &'a ll_bindings::tsk_edge_table_t,
+}
+
+impl<'a> EdgeTable<'a> {
+    pub(crate) fn new_from_table(edges: &'a ll_bindings::tsk_edge_table_t) -> Self {
+        return EdgeTable { table_: edges };
+    }
+
+    /// Return the number of rows
+    pub fn num_rows(&'a self) -> tsk_size_t {
+        return self.table_.num_rows;
+    }
+
+    /// Return the ``parent`` value from row ``row`` of the table.
+    ///
+    /// # Errors
+    ///
+    /// Will return [``IndexError``](crate::TskitRustError::IndexError)
+    /// if ``row`` is out of range.
+    pub fn parent(&'a self, row: tsk_id_t) -> Result<tsk_id_t, TskitRustError> {
+        unsafe_tsk_column_access!(row, 0, self.num_rows(), self.table_.parent);
+    }
+
+    /// Return the ``child`` value from row ``row`` of the table.
+    ///
+    /// # Errors
+    ///
+    /// Will return [``IndexError``](crate::TskitRustError::IndexError)
+    /// if ``row`` is out of range.
+    pub fn child(&'a self, row: tsk_id_t) -> Result<tsk_id_t, TskitRustError> {
+        unsafe_tsk_column_access!(row, 0, self.num_rows(), self.table_.child);
+    }
+
+    /// Return the ``left`` value from row ``row`` of the table.
+    ///
+    /// # Errors
+    ///
+    /// Will return [``IndexError``](crate::TskitRustError::IndexError)
+    /// if ``row`` is out of range.
+    pub fn left(&'a self, row: tsk_id_t) -> Result<f64, TskitRustError> {
+        unsafe_tsk_column_access!(row, 0, self.num_rows(), self.table_.left);
+    }
+
+    /// Return the ``right`` value from row ``row`` of the table.
+    ///
+    /// # Errors
+    ///
+    /// Will return [``IndexError``](crate::TskitRustError::IndexError)
+    /// if ``row`` is out of range.
+    pub fn right(&'a self, row: tsk_id_t) -> Result<f64, TskitRustError> {
+        unsafe_tsk_column_access!(row, 0, self.num_rows(), self.table_.right);
+    }
+}

src/error.rs

@@ -0,0 +1,122 @@
+//! Error handling
+
+use crate::TskReturnValue;
+use thiserror::Error;
+
+#[derive(Error, Debug, PartialEq)]
+pub enum TskitRustError {
+    /// Used when bad input is encountered.
+    #[error("we received {} but expected {}",*got, *expected)]
+    ValueError { got: String, expected: String },
+    /// Used when array access is out of range.
+    /// Typically, this is used when accessing
+    /// arrays allocated on the C side.
+    #[error("Invalid index")]
+    IndexError,
+    /// Wrapper around tskit C API error codes.
+    #[error("{}", get_tskit_error_message(*code))]
+    ErrorCode { code: i32 },
+}
+
+/// Takes the return code from a tskit
+/// function and panics if the code indicates
+/// an error.  The error message is included
+/// in the panic statement.
+///
+/// Examples:
+///
+/// ```
+/// let rv = 0;  // All good!
+/// tskit_rust::error::panic_on_tskit_error(rv);
+/// let rv = 1;  // Probably something like a new node id.
+/// tskit_rust::error::panic_on_tskit_error(rv);
+/// ```
+///
+/// This will panic:
+///
+/// ```should_panic
+/// let rv = -202; // "Node out of bounds error"
+/// tskit_rust::error::panic_on_tskit_error(rv);
+/// ```
+pub fn panic_on_tskit_error(code: i32) -> () {
+    panic_on_tskit_error!(code);
+}
+
+/// Given a return value from low-level tskit function,
+/// obtain the corresponding error message.
+///
+/// tskit returns 0 when there's no error:
+/// ```
+/// let x = tskit_rust::error::get_tskit_error_message(0);
+/// assert_eq!(x, "Normal exit condition. This is not an error!");
+/// ```
+///
+/// Values > 0 are considered errors, but have no known type/cause.
+/// tskit never returns error codes > 0 and there should be no attempt
+/// to ever do so by client code.
+///
+/// ```
+/// let x = tskit_rust::error::get_tskit_error_message(1);
+/// assert_eq!(x, "Unknown error");
+/// ```
+///
+/// Values < 0 may have known causes:
+///
+/// ```
+/// let x = tskit_rust::error::get_tskit_error_message(-207);
+/// assert_eq!(x, "Individual out of bounds");
+/// ```
+pub fn get_tskit_error_message(code: i32) -> String {
+    let c_str = unsafe { std::ffi::CStr::from_ptr(crate::bindings::tsk_strerror(code)) };
+    let str_slice: &str = c_str.to_str().unwrap();
+    let message: String = str_slice.to_owned();
+    return message;
+}
+
+/// Given an instance of [``TskReturnValue``](crate::TskReturnValue),
+/// obtain the tskit error message if there is indeed an error.
+pub fn extract_error_message(x: TskReturnValue) -> Option<String> {
+    return x.map_or_else(|e: TskitRustError| Some(format!("{}", e)), |_| None);
+}
+
+#[cfg(test)]
+mod test {
+
+    use super::*;
+
+    #[test]
+    fn test_get_tskit_error_message() {
+        let m = get_tskit_error_message(0);
+        assert_eq!(m, "Normal exit condition. This is not an error!");
+    }
+
+    fn mock_error() -> TskReturnValue {
+        handle_tsk_return_value!(-207);
+    }
+
+    fn mock_success() -> TskReturnValue {
+        return Ok(0);
+    }
+
+    #[test]
+    fn test_error_formatting() {
+        let x = mock_error();
+        let mut s: String = "nope!".to_string();
+        x.map_or_else(|e: TskitRustError| s = format!("{}", e), |_| ());
+        assert_eq!(s, "Individual out of bounds");
+    }
+
+    #[test]
+    fn test_extract_error_message() {
+        let x = mock_error();
+        match extract_error_message(x) {
+            Some(s) => assert_eq!(s, "Individual out of bounds"),
+            None => assert!(false),
+        }
+
+        match extract_error_message(mock_success()) {
+            Some(_) => assert!(false),
+            None => assert!(true),
+        }
+    }
+}

src/lib.rs

@@ -4,35 +4,42 @@
 #![allow(non_camel_case_types)]
 #![allow(non_snake_case)]
 
-/// Low-level ("unsafe") bindings to the C API.
-///
-/// This module is a 1-to-1 mapping of C types
-/// and functions for both tskit and kastore.
-/// The bindings are generate via [bindgen](https://docs.rs/bindgen).
-///
-/// Using things from this module will be ``unsafe``.
-/// Further, as many of the types require ``init()`` methods
-/// to correctly set up the structs, one has to coerce ``rust``
-/// into allowing uninitialized variables:
-///
-/// ```
-/// use std::mem::MaybeUninit;
-/// let mut edges: MaybeUninit<tskit_rust::bindings::tsk_edge_table_t> = MaybeUninit::uninit();
-/// unsafe {
-///     let _ = tskit_rust::bindings::tsk_edge_table_init(edges.as_mut_ptr(), 0);
-///     let _ = tskit_rust::bindings::tsk_edge_table_add_row(edges.as_mut_ptr(), 0., 10., 0, 1, std::ptr::null(), 0);
-///     assert_eq!((*edges.as_ptr()).num_rows, 1);
-///     tskit_rust::bindings::tsk_edge_table_free(edges.as_mut_ptr());
-/// }
-/// ```
-///
-/// The best source for documentation will be the [tskit docs](https://tskit.readthedocs.io).
-/// Those docs describe the most important parts of the C API.
-/// This module contains the same types/functions with the same names.
 pub mod bindings;
 
 mod auto_bindings;
 
+mod _macros; // Starts w/_ to be sorted at front by rustfmt!
+mod edge_table;
+pub mod error;
+mod mutation_table;
+mod node_table;
+mod site_table;
+mod table_collection;
+pub mod types;
+
+// re-export fundamental constants that
+// we can't live without
+pub use bindings::TSK_NODE_IS_SAMPLE;
+pub use bindings::TSK_NO_BUILD_INDEXES;
+pub use bindings::TSK_NULL;
+pub use bindings::TSK_SAMPLE_LISTS;
+
+// re-export types, too
+pub use bindings::tsk_flags_t;
+pub use bindings::tsk_id_t;
+pub use bindings::tsk_size_t;
+
+pub use edge_table::EdgeTable;
+pub use error::TskitRustError;
+pub use mutation_table::MutationTable;
+pub use node_table::NodeTable;
+pub use site_table::SiteTable;
+pub use table_collection::TableCollection;
+/// Handles return codes from low-level tskit functions.
+///
+/// When an error from the tskit C API is detected,
+/// the error message is stored for diplay.
+pub type TskReturnValue = Result<i32, TskitRustError>;
+
 // Testing modules
-mod test_table_collection;
 mod test_tsk_variables;