feat: add tskit::OwnedIndividualTable (#284)

Author: molpopgen

src/individual_table.rs

@@ -4,6 +4,7 @@ use crate::IndividualFlags;
 use crate::IndividualId;
 use crate::Location;
 use crate::{tsk_id_t, tsk_size_t, TskitError};
+use ll_bindings::{tsk_individual_table_free, tsk_individual_table_init};
 
 /// Row of a [`IndividualTable`]
 pub struct IndividualTableRow {
@@ -278,3 +279,59 @@ impl<'a> IndividualTable<'a> {
         table_row_access!(ri.0, self, make_individual_table_row)
     }
 }
+
+build_owned_table_type!(
+    /// A standalone individual table that owns its data.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use tskit::OwnedIndividualTable;
+    ///
+    /// let mut individuals = OwnedIndividualTable::default();
+    /// let rowid = individuals.add_row(0, None, None).unwrap();
+    /// assert_eq!(rowid, 0);
+    /// assert_eq!(individuals.num_rows(), 1);
+    /// ```
+    ///
+    /// An example with metadata.
+    /// This requires the cargo feature `"derive"` for `tskit`.
+    ///
+    /// ```
+    /// # #[cfg(any(feature="doc", feature="derive"))] {
+    /// use tskit::OwnedIndividualTable;
+    ///
+    /// #[derive(serde::Serialize,
+    ///          serde::Deserialize,
+    ///          tskit::metadata::IndividualMetadata)]
+    /// #[serializer("serde_json")]
+    /// struct IndividualMetadata {
+    ///     value: i32,
+    /// }
+    ///
+    /// let metadata = IndividualMetadata{value: 42};
+    ///
+    /// let mut individuals = OwnedIndividualTable::default();
+    ///
+    /// let rowid = individuals.add_row_with_metadata(0, None, None, &metadata).unwrap();
+    /// assert_eq!(rowid, 0);
+    ///
+    /// if let Some(decoded) = individuals.metadata::<IndividualMetadata>(rowid).unwrap() {
+    ///     assert_eq!(decoded.value, 42);
+    /// } else {
+    ///     panic!("hmm...we expected some metadata!");
+    /// }
+    ///
+    /// # }
+    /// ```
+    => OwnedIndividualTable,
+    IndividualTable,
+    tsk_individual_table_t,
+    tsk_individual_table_init,
+    tsk_individual_table_free
+);
+
+impl OwnedIndividualTable {
+    individual_table_add_row!(=> add_row, self, *self.table);
+    individual_table_add_row_with_metadata!(=> add_row_with_metadata, self, *self.table);
+}

src/lib.rs

@@ -425,7 +425,7 @@ pub(crate) const TSK_NULL: tsk_id_t = -1;
 pub use edge_table::{EdgeTable, EdgeTableRow, OwnedEdgeTable};
 pub use error::TskitError;
 pub use flags::*;
-pub use individual_table::{IndividualTable, IndividualTableRow};
+pub use individual_table::{IndividualTable, IndividualTableRow, OwnedIndividualTable};
 pub use migration_table::{MigrationTable, MigrationTableRow};
 pub use mutation_table::{MutationTable, MutationTableRow, OwnedMutationTable};
 pub use node_table::{NodeTable, NodeTableRow, OwnedNodeTable};