tempoch_core/
lib.rs

1// SPDX-License-Identifier: AGPL-3.0-only
2// Copyright (C) 2026 Vallés Puig, Ramon
3
4//! Typed astronomical time primitives.
5//!
6//! The central type is [`Time<S, F>`] (default `F` = [`J2000s`]), where `S` is a [`Scale`]
7//! marker (`TT`, `TAI`, `UTC`, `UT1`, `TDB`, `TCG`, `TCB`) and `F` is a [`TimeFormat`]
8//! tag (`JD`, `MJD`, [`J2000s`], [`Unix`], [`GPS`]).
9//!
10//! `tempoch` makes a few explicit modeling decisions:
11//!
12//! - [`Time<S, F>`] is an instant on a scale-specific axis; `F` only types external
13//!   views (`raw()`, conversion targets), not a second storage layout.
14//! - Time arithmetic follows affine rules: instant minus instant yields a
15//!   duration; shifting an instant by a duration yields another instant.
16//! - Internal storage is always a compensated `(hi, lo)` pair of J2000-based seconds
17//!   so large epoch values can retain small corrections and sub-second detail.
18//! - `JD`, `MJD`, `J2000s`, `Unix`, and `GPS` are conversion targets, not alternate
19//!   stored encodings.
20//! - `UTC` keeps special civil semantics: it is stored as a continuous instant
21//!   and interpreted through the active UTC-TAI table when civil labels are
22//!   needed.
23//!
24//! - [`Time::new`] builds from a raw scalar when `F` is [`InfallibleFormatForScale`](crate::InfallibleFormatForScale) for `S` (**NaN panics**; ±∞ allowed at rest). POSIX [`Unix`] instants still use [`Time::try_new`] / [`Time::try_new_with`] because decoding depends on leap-second tables.
25//! - [`Time::try_new`] / [`Time::try_new_with`] surface **domain** decode failures only (UTC policy, leap seconds, …); callers must not pass **NaN**.
26//! - `UTC`: civil (`chrono`) and POSIX ([`Unix`]); `TAI`: GPS ([`GPS`])
27//! - Unified targets: [`Time::to`], [`Time::try_to`], [`Time::to_with`]. Prefer
28//!   [`try_to`](Time::try_to) or [`to_with`](Time::to_with) for [`Unix`] so positive
29//!   leap-second instants are rejected when they are not representable as POSIX.
30//! - [`Time::to_j2000s`], [`Time::reinterpret`], and aliases
31//!   such as [`crate::JulianDate`].
32//! - [`JulianDate`], [`ModifiedJulianDate`], [`UnixTime`], and [`GpsTime`] implement [`Into`] into default-tagged
33//!   [`Time<S>`] / [`Time<UTC>`] / [`Time<TAI>`], so APIs such as [`Period::try_new`](crate::Period) accept encoded
34//!   endpoints without spelling [`Time::to_j2000s`]. [`J2000Seconds<S>`] is already [`Time<S>`]; no conversion needed.
35//!
36//! See [`constats`] for epoch [`Time`] helpers, day/second scratch constants, and offsets.
37//!
38//! # Module map
39//!
40//! - [`foundation`]: shared sealed traits, typed constants, and error types.
41//! - [`model`]: [`Time`], scale markers, and conversion targets.
42//! - [`format`]: external format markers and format conversion traits.
43//! - `encoding`: crate-local JD/MJD/J2000/Unix arithmetic helpers.
44//! - [`earth`]: ΔT, EOP, and [`TimeContext`] Earth-rotation policy.
45//! - [`data`]: runtime access to bundled and optionally refreshed time-data tables.
46//! - [`period`]: interval and period-list algebra.
47//! - [`features`]: optional serde/tagged/time-instant integration helpers.
48//!
49//! Reference modules:
50//!
51//! - [`earth::delta_t`]: piecewise ΔT (`TT - UT1`) model and modern tabular segment.
52//! - [`earth::eop`]: public EOP sampling API over bundled IERS series.
53//! - [`earth::context`]: immutable time-data snapshot plus conversion policy.
54
55pub mod data;
56pub mod earth;
57pub(crate) mod encoding;
58pub mod features;
59pub mod format;
60pub mod foundation;
61pub mod model;
62pub mod period;
63
64// Compiled tables live in `tempoch-time-data`; these are crate-local shims for tests and helpers.
65#[allow(unused_imports)]
66pub(crate) use tempoch_time_data::generated::{eop_data, time_data};
67#[allow(unused_imports)]
68pub(crate) use tempoch_time_data::generated::{MODERN_DELTA_T_END_MJD, MODERN_DELTA_T_START_MJD};
69
70pub use earth::eop;
71pub use foundation::{constats, error};
72
73#[cfg(feature = "runtime-data-fetch")]
74pub use data::runtime_data::{
75    fetch_latest_time_data, refresh_runtime_time_data, update_runtime_time_data,
76};
77pub use earth::context::TimeContext;
78pub use earth::delta_t::{
79    delta_t_seconds, delta_t_seconds_extrapolated, DELTA_T_PREDICTION_HORIZON_MJD,
80};
81pub use features::TimeInstant;
82pub use format::{
83    FormatForScale, GpsTime, InfallibleFormatForScale, J2000Seconds, J2000s, JulianDate,
84    ModifiedJulianDate, TimeFormat, Unix, UnixTime, GPS, JD, MJD,
85};
86pub use foundation::constats::{
87    gps_epoch_jd_tai, gps_epoch_jd_utc, gps_epoch_tai, iau_time_epoch_t0_jd, j2000_jd_tt,
88    tdb_tt_model_high_accuracy_end_jd, tdb_tt_model_high_accuracy_start_jd, unix_epoch_jd,
89    unix_epoch_mjd, utc_defined_from_mjd, GPS_EPOCH_JD_TAI_DAY, GPS_EPOCH_JD_UTC_DAY,
90    GPS_EPOCH_TAI_MINUS_UTC, GPS_EPOCH_TAI_SECONDS, IAU_TIME_EPOCH_T0_JD_DAY, J2000_JD_TT_DAY,
91    JULIAN_YEAR_DAYS, TDB_TT_MODEL_HIGH_ACCURACY_END_JD_DAY,
92    TDB_TT_MODEL_HIGH_ACCURACY_START_JD_DAY, TT_MINUS_TAI, UNIX_EPOCH_JD_DAY, UNIX_EPOCH_MJD_DAY,
93    UTC_DEFINED_FROM_MJD_DAY,
94};
95pub use foundation::error::{ConversionError, TimeDataError};
96pub use model::scale::{ContinuousScale, CoordinateScale, Scale, TAI, TCB, TCG, TDB, TT, UT1, UTC};
97pub use model::target::{ContextConversionTarget, ConversionTarget, InfallibleConversionTarget};
98pub use model::time::Time;
99pub use period::{complement_within, Interval, InvalidIntervalError, Period, PeriodListError};
100pub use tempoch_time_data::generated::{
101    EOP_END_MJD, EOP_OBSERVED_END_MJD, EOP_START_MJD, MODERN_DELTA_T_OBSERVED_END_MJD,
102};
103
104#[cfg(feature = "serde")]
105pub use features::tagged;
106
107#[cfg(test)]
108mod size_tests {
109    use super::*;
110    #[test]
111    fn time_uses_compensated_pair_storage() {
112        assert_eq!(core::mem::size_of::<Time<TT>>(), 16);
113        assert_eq!(core::mem::size_of::<Time<TAI>>(), 16);
114        assert_eq!(core::mem::size_of::<Time<TDB>>(), 16);
115        assert_eq!(core::mem::size_of::<Time<TCG>>(), 16);
116        assert_eq!(core::mem::size_of::<Time<TCB>>(), 16);
117        assert_eq!(core::mem::size_of::<Time<UT1>>(), 16);
118        assert_eq!(core::mem::size_of::<Time<UTC>>(), 16);
119    }
120}
tempoch_core/lib.rs

tempoch_core/
lib.rs
