timeofweek: introduce time of week construction and conversion

* (wk, tow) is usually how an epoch is expressed
by a GNSS receiver, usually in a GNSS timescale.
Wk is a rolling counter, and tow is the amount of seconds since Sunday midnight
of that week.

`tow` is usually expressed in [s] or [ms] by receivers,
we use [ns] here, to maintain crate consistency and never be limited.

Signed-off-by: Guillaume W. Bres <guillaume.bressaix@gmail.com>

src/epoch.rs

@@ -13,7 +13,7 @@ use crate::parser::Token;
 use crate::{
     Errors, TimeScale, BDT_REF_EPOCH, DAYS_PER_YEAR_NLD, ET_EPOCH_S, GPST_REF_EPOCH, GST_REF_EPOCH,
     J1900_OFFSET, J2000_TO_J1900_DURATION, MJD_OFFSET, NANOSECONDS_PER_MICROSECOND,
-    NANOSECONDS_PER_MILLISECOND, NANOSECONDS_PER_SECOND_U32, UNIX_REF_EPOCH,
+    SECONDS_PER_DAY, NANOSECONDS_PER_MILLISECOND, NANOSECONDS_PER_SECOND_U32, UNIX_REF_EPOCH,
 };
 use core::cmp::{Eq, Ord, Ordering, PartialEq, PartialOrd};
 use core::fmt;
@@ -2225,6 +2225,43 @@ impl Epoch {
         me.time_scale = new_time_scale;
         me
     }
+
+    /// Builds an Epoch from given `wk` week counter into the desired Time scale. 
+    /// `ns` is the amount of nanoseconds into that week, starting on Sunday midnight of that week.
+    #[cfg(feature = "python")]
+    #[staticmethod]
+    pub fn from_timeofweek(wk: u32, ns: u64, ts: TimeScale) -> Self  {
+        let week = Duration::from_seconds(wk as f64 * SECONDS_PER_DAY * 7.0);
+        Self::from_duration(week + (ns as f64) * Unit::Nanosecond, ts)
+    }
+
+    /// Converts to "time of week" (`wk, `tow`),
+    /// which is usually how GNSS receivers describe a timestamp.
+    /// `wk` is a rolling week conter into that time scale,
+    /// `tow` is the number of seconds since closest Sunday midnight into that week.
+    pub fn to_timeofweek(&self) -> (u32, u64) {
+        // fractionnal days in this time scale
+        let days = match self.time_scale {
+            TimeScale::GPST => self.to_gpst_days(),
+            TimeScale::GST => self.to_gst_days(),
+            TimeScale::BDT => self.to_bdt_days(),
+            TimeScale::TT => self.to_tt_days(),
+            TimeScale::TAI => self.to_tai_days(),
+            TimeScale::UTC => self.to_utc_days(),
+            TimeScale::TDB => self.to_tdb_seconds() / SECONDS_PER_DAY,
+            TimeScale::ET => self.to_et_seconds() / SECONDS_PER_DAY,
+        };
+        let wk = (days / 7.0) as u32;
+        let residuals = (Duration::from_f64(days + 7.0, Unit::Day) -  Duration::from_f64(days, Unit::Day))
+            .truncated_nanoseconds();
+        (wk, residuals as u64)// express residuals in ns 
+    }
+
+    /// Returns "weekday" in TAI timescale, starting 0: Monday, ranging 6: Sunday
+    pub fn weekday_tai(&self) -> u8 {
+        // we're helped here, because J1900 was a monday :) 
+        (self.to_tai_days() as u64).rem_euclid(7) as u8 
+    }
 
     // Python helpers
 

src/timescale.rs

@@ -19,6 +19,15 @@ use core::str::FromStr;
 
 use crate::{Duration, Epoch, Errors, ParsingErrors, SECONDS_PER_DAY};
 
+/*
+/// TAI reference Monday: first Monday encountered in the TAI timescale,
+/// from our reference point (or Epoch), which is defined as J1900 in TAI.
+/// This is used as a reference point for weekday determination
+pub const TAI_REF_MONDAY: Epoch = Epoch {
+    centuries: 0, // funny enough, Day 1 in 1900 tai was a monday
+    nanoseconds: 0,
+}; */
+
 /// GPS reference epoch is UTC midnight between 05 January and 06 January 1980; cf. <https://gssc.esa.int/navipedia/index.php/Time_References_in_GNSS#GPS_Time_.28GPST.29>.
 pub const GPST_REF_EPOCH: Epoch = Epoch::from_tai_duration(Duration {
     centuries: 0,

tests/epoch.rs

@@ -1337,3 +1337,33 @@ fn test_minmax() {
     assert_eq!(e1, e1.max(e0));
     assert_eq!(e1, e0.max(e1));
 }
+
+#[test]
+fn test_weekday() {
+    // J1900 was a monday
+    let j1900 = Epoch::from_gregorian_tai_at_midnight(1900, 01, 01);
+    assert_eq!(j1900.weekday_tai(), 0);
+    // 1 nanosec into TAI: still a monday
+    let j1900_fractionnal = Epoch::from_gregorian_tai(1900, 01, 01, 0, 0, 0, 1);
+    assert_eq!(j1900.weekday_tai(), 0);
+    // some portion of that day: still a mon day
+    let j1900_fractionnal = Epoch::from_gregorian_tai(1900, 01, 01, 10, 00, 00, 123);
+    assert_eq!(j1900.weekday_tai(), 0);
+    // Day +1: tuesday
+    let j1901 = j1900 + Duration::from_days(1.0);
+    assert_eq!(j1901.weekday_tai(), 1);
+    // 1 ns into tuesday, still a tuesday
+    let j1901 = j1901 + Duration::from_nanoseconds(1.0);
+    assert_eq!(j1901.weekday_tai(), 1);
+}
+
+#[test]
+fn test_gnss_timeofweek() {
+    // GPST
+    // https://www.labsat.co.uk/index.php/en/gps-time-calculator
+    // 01/12/2022 00:00:00 => (2238, 345_618_000_000_000)
+    let epoch = Epoch::from_timeofweek(2238, 345_618_000_000_000, TimeScale::GPST);
+    assert_eq!(epoch.to_gregorian_utc(), (2022, 12, 01, 00, 00, 00, 00));
+    // test reserve op
+    assert_eq!(epoch.to_timeofweek(), (2238, 345_618_000_000_000));
+}