Add newtypes for Time, Position, and for Location. (#199)

Closes #191

Author: molpopgen

examples/forward_simulation.rs

@@ -228,7 +228,7 @@ fn crossover_and_record_edges_details(
             Err(e) => panic!("{}", e),
         }
     } else {
-        let exp = match Exp::new(params.xovers / tables.sequence_length()) {
+        let exp = match Exp::new(params.xovers / f64::from(tables.sequence_length())) {
             Ok(e) => e,
             Err(e) => panic!("{}", e),
         };

src/_macros.rs

@@ -365,6 +365,140 @@ macro_rules! impl_size_type_comparisons_for_row_ids {
     };
 }
 
+macro_rules! impl_f64_newtypes {
+    ($type: ty) => {
+        impl std::fmt::Display for $type {
+            fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+                write!(f, "{}({})", stringify!($idtype), self.0)
+            }
+        }
+
+        impl PartialEq<f64> for $type {
+            fn eq(&self, other: &f64) -> bool {
+                self.0.eq(other)
+            }
+        }
+
+        impl PartialEq<$type> for f64 {
+            fn eq(&self, other: &$type) -> bool {
+                self.eq(&other.0)
+            }
+        }
+
+        impl PartialOrd<f64> for $type {
+            fn partial_cmp(&self, other: &f64) -> Option<std::cmp::Ordering> {
+                self.0.partial_cmp(other)
+            }
+        }
+
+        impl PartialOrd<$type> for f64 {
+            fn partial_cmp(&self, other: &$type) -> Option<std::cmp::Ordering> {
+                self.partial_cmp(&other.0)
+            }
+        }
+
+        impl From<f64> for $type {
+            fn from(value: f64) -> Self {
+                Self(value)
+            }
+        }
+
+        impl From<$type> for f64 {
+            fn from(value: $type) -> Self {
+                value.0
+            }
+        }
+
+        impl std::ops::Sub for $type {
+            type Output = Self;
+
+            fn sub(self, rhs: Self) -> Self::Output {
+                Self(self.0 - rhs.0)
+            }
+        }
+
+        impl std::ops::SubAssign for $type {
+            fn sub_assign(&mut self, rhs: Self) {
+                self.0 -= rhs.0
+            }
+        }
+
+        impl std::ops::Add for $type {
+            type Output = Self;
+
+            fn add(self, rhs: Self) -> Self::Output {
+                Self(self.0 + rhs.0)
+            }
+        }
+
+        impl std::ops::AddAssign for $type {
+            fn add_assign(&mut self, rhs: Self) {
+                self.0 += rhs.0
+            }
+        }
+
+        impl std::ops::Mul for $type {
+            type Output = Self;
+
+            fn mul(self, rhs: Self) -> Self::Output {
+                Self(self.0 * rhs.0)
+            }
+        }
+
+        impl std::ops::MulAssign for $type {
+            fn mul_assign(&mut self, rhs: Self) {
+                self.0.mul_assign(&rhs.0)
+            }
+        }
+
+        impl std::ops::Div for $type {
+            type Output = Self;
+
+            fn div(self, rhs: Self) -> Self::Output {
+                Self(self.0 / rhs.0)
+            }
+        }
+
+        impl std::ops::DivAssign for $type {
+            fn div_assign(&mut self, rhs: Self) {
+                self.0.div_assign(&rhs.0)
+            }
+        }
+    };
+}
+
+macro_rules! impl_time_position_arithmetic {
+    ($lhs: ty, $rhs:ty) => {
+        impl std::ops::Mul<$rhs> for $lhs {
+            type Output = $lhs;
+
+            fn mul(self, other: $rhs) -> Self {
+                Self(self.0.mul(&other.0))
+            }
+        }
+
+        impl std::ops::MulAssign<$rhs> for $lhs {
+            fn mul_assign(&mut self, other: $rhs) {
+                self.0.mul_assign(&other.0)
+            }
+        }
+
+        impl std::ops::Div<$rhs> for $lhs {
+            type Output = $lhs;
+
+            fn div(self, other: $rhs) -> Self {
+                Self(self.0.div(&other.0))
+            }
+        }
+
+        impl std::ops::DivAssign<$rhs> for $lhs {
+            fn div_assign(&mut self, other: $rhs) {
+                self.0.div_assign(&other.0)
+            }
+        }
+    };
+}
+
 /// Convenience macro to handle implementing
 /// [`crate::metadata::MetadataRoundtrip`]
 #[macro_export]

src/edge_table.rs

@@ -1,13 +1,14 @@
 use crate::bindings as ll_bindings;
 use crate::metadata;
+use crate::Position;
 use crate::{tsk_id_t, TskitError};
 use crate::{EdgeId, NodeId};
 
 /// Row of an [`EdgeTable`]
 pub struct EdgeTableRow {
     pub id: EdgeId,
-    pub left: f64,
-    pub right: f64,
+    pub left: Position,
+    pub right: Position,
     pub parent: NodeId,
     pub child: NodeId,
     pub metadata: Option<Vec<u8>>,
@@ -18,8 +19,8 @@ impl PartialEq for EdgeTableRow {
         self.id == other.id
             && self.parent == other.parent
             && self.child == other.child
-            && crate::util::f64_partial_cmp_equal(&self.left, &other.left)
-            && crate::util::f64_partial_cmp_equal(&self.right, &other.right)
+            && crate::util::partial_cmp_equal(&self.left, &other.left)
+            && crate::util::partial_cmp_equal(&self.right, &other.right)
             && self.metadata == other.metadata
     }
 }
@@ -112,8 +113,11 @@ impl<'a> EdgeTable<'a> {
     ///
     /// Will return [``IndexError``](crate::TskitError::IndexError)
     /// if ``row`` is out of range.
-    pub fn left<E: Into<EdgeId> + Copy>(&'a self, row: E) -> Result<f64, TskitError> {
-        unsafe_tsk_column_access!(row.into().0, 0, self.num_rows(), self.table_.left)
+    pub fn left<E: Into<EdgeId> + Copy>(&'a self, row: E) -> Result<Position, TskitError> {
+        match unsafe_tsk_column_access!(row.into().0, 0, self.num_rows(), self.table_.left) {
+            Ok(p) => Ok(p.into()),
+            Err(e) => Err(e),
+        }
     }
 
     /// Return the ``right`` value from row ``row`` of the table.
@@ -122,8 +126,11 @@ impl<'a> EdgeTable<'a> {
     ///
     /// Will return [``IndexError``](crate::TskitError::IndexError)
     /// if ``row`` is out of range.
-    pub fn right<E: Into<EdgeId> + Copy>(&'a self, row: E) -> Result<f64, TskitError> {
-        unsafe_tsk_column_access!(row.into().0, 0, self.num_rows(), self.table_.right)
+    pub fn right<E: Into<EdgeId> + Copy>(&'a self, row: E) -> Result<Position, TskitError> {
+        match unsafe_tsk_column_access!(row.into().0, 0, self.num_rows(), self.table_.right) {
+            Ok(p) => Ok(p.into()),
+            Err(e) => Err(e),
+        }
     }
 
     pub fn metadata<T: metadata::MetadataRoundtrip>(

src/individual_table.rs

@@ -1,13 +1,14 @@
 use crate::bindings as ll_bindings;
 use crate::metadata;
 use crate::IndividualId;
+use crate::Location;
 use crate::{tsk_flags_t, tsk_id_t, tsk_size_t, TskitError};
 
 /// Row of a [`IndividualTable`]
 pub struct IndividualTableRow {
     pub id: IndividualId,
     pub flags: tsk_flags_t,
-    pub location: Option<Vec<f64>>,
+    pub location: Option<Vec<Location>>,
     pub parents: Option<Vec<IndividualId>>,
     pub metadata: Option<Vec<u8>>,
 }
@@ -27,7 +28,7 @@ impl PartialEq for IndividualTableRow {
                             false
                         } else {
                             for (i, j) in a.iter().enumerate() {
-                                if !crate::util::f64_partial_cmp_equal(j, &b[i]) {
+                                if !crate::util::partial_cmp_equal(&b[i], j) {
                                     return false;
                                 }
                             }
@@ -121,14 +122,15 @@ impl<'a> IndividualTable<'a> {
     pub fn location<I: Into<IndividualId> + Copy>(
         &self,
         row: I,
-    ) -> Result<Option<Vec<f64>>, TskitError> {
+    ) -> Result<Option<Vec<Location>>, TskitError> {
         unsafe_tsk_ragged_column_access!(
             row.into().0,
             0,
             self.num_rows(),
             self.table_.location,
             self.table_.location_offset,
-            self.table_.location_length
+            self.table_.location_length,
+            Location
         )
     }
 

src/lib.rs

@@ -333,6 +333,77 @@ impl PartialOrd<SizeType> for tsk_size_t {
     }
 }
 
+/// A newtype for the concept of time.
+/// A `Time` value can represent either a point in time
+/// or the output of arithmetic involving time.
+///
+/// Wraps [`f64`].
+///
+/// # Examples
+///
+/// ```
+/// let t0 = tskit::Time::from(2.0);
+/// let t1 = tskit::Time::from(10.0);
+///
+/// let mut sum = t0 + t1;
+///
+/// match sum.partial_cmp(&12.0) {
+///    Some(std::cmp::Ordering::Equal) => (),
+///    _ => assert!(false),
+/// };
+///
+/// sum /= tskit::Time::from(2.0);
+///
+/// match sum.partial_cmp(&6.0) {
+///    Some(std::cmp::Ordering::Equal) => (),
+///    _ => assert!(false),
+/// };
+/// ```
+///
+/// # Notes
+///
+/// The current implementation of [`PartialOrd`] is based on
+/// the underlying implementation for [`f64`].
+///
+/// A `Time` can be multiplied and divided by a [`Position`]
+///
+#[repr(transparent)]
+#[derive(Copy, Clone, Debug, PartialEq, PartialOrd)]
+pub struct Time(f64);
+
+/// A newtype for the concept of "genomic position".
+/// A `Position` can represent either a locus or a
+/// distance between loci.
+///
+/// Wraps [`f64`].
+///
+/// For examples, see [`Time`].
+///
+/// This type can be multiplied and divided by [`Time`].
+#[repr(transparent)]
+#[derive(Copy, Clone, Debug, PartialEq, PartialOrd)]
+pub struct Position(f64);
+
+/// A newtype for the concept of location.
+/// A `Location` may represent a location or the
+/// output of arithmetic involving locations.
+///
+/// Wraps [`f64`].
+///
+/// For examples, see [`Time`].
+///
+#[repr(transparent)]
+#[derive(Copy, Clone, Debug, PartialEq, PartialOrd)]
+pub struct Location(f64);
+
+impl_f64_newtypes!(Time);
+impl_f64_newtypes!(Position);
+impl_f64_newtypes!(Location);
+
+// It is natural to be able to * and / times and positions
+impl_time_position_arithmetic!(Time, Position);
+impl_time_position_arithmetic!(Position, Time);
+
 // tskit defines this via a type cast
 // in a macro. bindgen thus misses it.
 // See bindgen issue 316.

src/metadata.rs

@@ -88,7 +88,7 @@
 //! let individual = IndividualMetadata {
 //!     genetic_value: GeneticValue(0.0),
 //! };
-//! let id = tables.add_individual_with_metadata(0, &[], &[tskit::IndividualId::NULL], &individual).unwrap();
+//! let id = tables.add_individual_with_metadata(0, &[] as &[tskit::Location], &[tskit::IndividualId::NULL], &individual).unwrap();
 //! let decoded = tables.individuals().metadata::<IndividualMetadata>(id).unwrap().unwrap();
 //! assert_eq!(decoded.genetic_value.partial_cmp(&individual.genetic_value).unwrap(), std::cmp::Ordering::Equal);
 //! # }