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`] 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
64pub(crate) use siderust_archive as archive;
65
66// Compiled ΔT tables live in `siderust-archive`; these are crate-local shims.
67use crate::archive::time::bundled::snapshot;
68use qtty::Day;
69
70#[allow(unused_imports)]
71pub(crate) use snapshot as time_data;
72pub(crate) const MODERN_DELTA_T_START_MJD: Day = Day::new(snapshot::MODERN_DELTA_T_START_MJD);
73pub(crate) const MODERN_DELTA_T_END_MJD: Day = Day::new(snapshot::MODERN_DELTA_T_END_MJD);
74
75pub use earth::eop;
76pub use foundation::{constats, error};
77
78#[cfg(feature = "runtime-data-fetch")]
79pub use data::runtime_data::{
80    fetch_latest_time_data, refresh_runtime_time_data, update_runtime_time_data,
81};
82pub use data::status::{
83    assert_fresh as assert_time_data_fresh, time_data_status, ActiveTimeDataSource, DataHorizons,
84    FreshnessError, TimeDataStatus,
85};
86pub use earth::context::TimeContext;
87pub use earth::delta_t::{
88    delta_t_seconds, delta_t_seconds_extrapolated, DELTA_T_PREDICTION_HORIZON_MJD,
89};
90pub use earth::eop::{eop_end, eop_observed_end, eop_start};
91pub use features::TimeInstant;
92pub use format::{
93    FormatForScale, FormatOptions, FormatPrecision, GnssWeek, GnssWeekScale, GpsTime,
94    InfallibleFormatForScale, J2000Seconds, J2000s, JulianDate, ModifiedJulianDate, TimeFormat,
95    Unix, UnixTime, GPS, JD, MJD,
96};
97pub use foundation::constats::{
98    gps_epoch_jd_tai, gps_epoch_jd_utc, gps_epoch_tai, iau_time_epoch_t0_jd, j2000_jd_tt,
99    tdb_tt_model_high_accuracy_end_jd, tdb_tt_model_high_accuracy_start_jd, unix_epoch_jd,
100    unix_epoch_mjd, utc_defined_from_mjd, GPS_EPOCH_JD_UTC_DAY, GPS_EPOCH_TAI_MINUS_UTC,
101    IAU_TIME_EPOCH_T0_JD_DAY, J2000_JD_TT_DAY, TDB_TT_MODEL_HIGH_ACCURACY_END_JD_DAY,
102    TDB_TT_MODEL_HIGH_ACCURACY_START_JD_DAY, TT_MINUS_TAI, UNIX_EPOCH_JD_DAY,
103    UTC_DEFINED_FROM_MJD_DAY,
104};
105pub use foundation::duration::{DurationError, ExactDuration, NANOS_PER_SECOND};
106pub use foundation::error::{ConversionError, TimeDataError};
107pub use model::scale::{
108    ContinuousScale, CoordinateScale, Scale, BDT, ET, GPST, GST, QZSST, TAI, TCB, TCG, TDB, TT,
109    UT1, UTC,
110};
111pub use model::target::{ContextConversionTarget, ConversionTarget, InfallibleConversionTarget};
112pub use model::time::Time;
113pub use period::{
114    complement_within, series::TimeSeries, series::TimeSeriesError, Interval, InvalidIntervalError,
115    Period, PeriodListError,
116};
117pub const MODERN_DELTA_T_OBSERVED_END_MJD: Day =
118    Day::new(snapshot::MODERN_DELTA_T_OBSERVED_END_MJD);
119
120#[cfg(feature = "serde")]
121pub use features::tagged;
122
123#[cfg(test)]
124mod size_tests {
125    use super::*;
126    #[test]
127    fn time_uses_compensated_pair_storage() {
128        assert_eq!(core::mem::size_of::<Time<TT>>(), 16);
129        assert_eq!(core::mem::size_of::<Time<TAI>>(), 16);
130        assert_eq!(core::mem::size_of::<Time<TDB>>(), 16);
131        assert_eq!(core::mem::size_of::<Time<TCG>>(), 16);
132        assert_eq!(core::mem::size_of::<Time<TCB>>(), 16);
133        assert_eq!(core::mem::size_of::<Time<UT1>>(), 16);
134        assert_eq!(core::mem::size_of::<Time<UTC>>(), 16);
135    }
136}
tempoch_core/lib.rs

tempoch_core/
lib.rs
