Struct Dt 

pub struct Dt { /* private fields */ }

Dt, and the library, is in the process of being switched from the sec and subsec fields being related to the scale, TO the sec and subsec fields always being TAI Epoch 2000-01-01 noon. Much of the documentation is outdated and should be ignored.

Implementations

impl Dt

pub const fn add(self, span: TSpan) -> Self

pub const fn sub(self, span: TSpan) -> Self

pub const fn to_sec_f(self) -> Real

Converts this Dt to a floating-point number of seconds since the reference epoch of its associated scale.

The conversion is lossy by design, as f64 (Real) provides approximately 15.95 decimal digits of precision. For full exactness, use the integer components sec and attos directly or higher-precision arithmetic when available.

pub const fn adjusted_advance( &mut self, elapsed: &TSpan, local_spacetime: &LocalSpacetime, )

Advances this Dt by the given elapsed duration while applying the relativistic proper-time correction derived from the supplied LocalSpacetime model.

This method is intended for simulation of remote clocks (e.g., Earth time as observed from a spacecraft). For the spacecraft’s own hardware proper-time clock, use the plain add method instead.

pub const fn adjusted_advance_using_drift( &mut self, elapsed: &TSpan, drift: &ClockDrift, )

Advances this Dt by the given elapsed duration while applying the relativistic proper-time correction from a pre-computed ClockDrift value.

This is an optimized variant of adjusted_advance for callers that already hold a ClockDrift instance. It is intended for simulation of remote clocks; the spacecraft’s own hardware clock should use the plain add method.

pub const fn to_tai_since(&self, earlier: Self) -> TSpan

Computes the TAI signed duration between this Dt and an earlier instant.

pub const fn to_tai_since_f(&self, other: Self) -> Real

This method is lossy by design and is provided for testing and debugging purposes only. For the exact duration, use duration_since or duration_since_ref.

pub const fn add_1sec(&mut self)

Adds exactly 1 second to this time value using saturating arithmetic.

pub const fn add_1min(&mut self)

Adds exactly 1 minute (60 seconds) to this time value using saturating arithmetic.

pub const fn add_1hr(&mut self)

Adds exactly 1 hour (3600 seconds) to this time value using saturating arithmetic.

pub const fn add_1ms(&mut self)

Adds exactly 1 millisecond to this time value.

This affects the subsecond component and may cause a carry into the seconds field.

pub const fn add_1us(&mut self)

Adds exactly 1 microsecond to this time value.

This affects the subsecond component and may cause a carry into the seconds field.

pub const fn add_1ns(&mut self)

Adds exactly 1 nanosecond to this time value.

This affects the subsecond component and may cause a carry into the seconds field.

pub const fn add_sec(&mut self, n: i64)

Adds the specified number of seconds to this time value using saturating arithmetic.

pub const fn add_min(&mut self, n: i64)

Adds the specified number of minutes to this time value using saturating arithmetic.

pub const fn add_hr(&mut self, n: i64)

Adds the specified number of hours to this time value using saturating arithmetic.

pub const fn add_ms(&mut self, n: i64)

Adds the specified number of milliseconds to this time value.

Handles carry into the seconds field using saturating logic.

pub const fn add_us(&mut self, n: i64)

Adds the specified number of microseconds to this time value.

Handles carry into the seconds field using saturating logic.

pub const fn add_ns(&mut self, n: i64)

Adds the specified number of nanoseconds to this time value.

Handles carry into the seconds field using saturating logic.

pub const fn add_ps(&mut self, n: i64)

Adds the specified number of picoseconds to this time value.

Handles carry into the seconds field using saturating logic.

pub const fn add_fs(&mut self, n: i64)

Adds the specified number of femtoseconds to this time value.

Handles carry into the seconds field using saturating logic.

pub const fn add_attos(&mut self, n: i64)

Adds the specified number of attoseconds to this time value.

Handles carry into the seconds field using saturating logic.

pub const fn sub_1hr(&mut self)

Subtracts exactly 1 hour (3600 seconds) from this time value using saturating arithmetic.

pub const fn sub_1min(&mut self)

Subtracts exactly 1 minute (60 seconds) from this time value using saturating arithmetic.

pub const fn sub_1sec(&mut self)

Subtracts exactly 1 second from this time value using saturating arithmetic.

pub const fn sub_1ms(&mut self)

Subtracts exactly 1 millisecond from this time value.

This affects the subsecond component and may cause a borrow from the seconds field.

pub const fn sub_1us(&mut self)

Subtracts exactly 1 microsecond from this time value.

This affects the subsecond component and may cause a borrow from the seconds field.

pub const fn sub_1ns(&mut self)

Subtracts exactly 1 nanosecond from this time value.

This affects the subsecond component and may cause a borrow from the seconds field.

pub const fn sub_sec(&mut self, n: i64)

Subtracts the specified number of seconds from this time value using saturating arithmetic.

pub const fn sub_min(&mut self, n: i64)

Subtracts the specified number of minutes from this time value using saturating arithmetic.

pub const fn sub_hr(&mut self, n: i64)

Subtracts the specified number of hours from this time value using saturating arithmetic.

pub const fn sub_ms(&mut self, n: i64)

Subtracts the specified number of milliseconds from this time value.

Handles borrow from the seconds field using saturating logic.

pub const fn sub_us(&mut self, n: i64)

Subtracts the specified number of microseconds from this time value.

Handles borrow from the seconds field using saturating logic.

pub const fn sub_ns(&mut self, n: i64)

Subtracts the specified number of nanoseconds from this time value.

Handles borrow from the seconds field using saturating logic.

pub const fn sub_ps(&mut self, n: i64)

Subtracts the specified number of picoseconds from this time value.

Handles borrow from the seconds field using saturating logic.

pub const fn sub_fs(&mut self, n: i64)

Subtracts the specified number of femtoseconds from this time value.

Handles borrow from the seconds field using saturating logic.

pub const fn sub_attos(&mut self, n: i64)

Subtracts the specified number of attoseconds from this time value.

Handles borrow from the seconds field using saturating logic.

pub const fn to_attos(self) -> i128

Total attoseconds (exact i128 representation within the representable range).

pub const fn to_ms(self) -> i128

Returns the total duration in milliseconds.

pub const fn to_us(self) -> i128

Returns the total duration in microseconds.

pub const fn to_ns(self) -> i128

Returns the total duration in nanoseconds.

pub const fn to_ps(self) -> i128

Returns the total duration in picoseconds.

pub const fn to_fs(self) -> i128

Returns the total duration in femtoseconds.

impl Dt

pub const ZERO: Self

The library’s reference zero instant: exactly 2000-01-01 12:00:00 TAI.

pub const J2000_TAI: Self

The TAI instant that corresponds to the conventional J2000.0 epoch (2000-01-01 12:00:00 TT, JD 2451545.0 TT).

pub const J1900_TAI: Self

The J1900.0 epoch expressed in TAI (1900-01-01 12:00:00 TAI).

pub const GPS_ZERO: Self

Library zero points (same physical instant as ZERO, different tags)

pub const GST_ZERO: Self

pub const QZSS_ZERO: Self

pub const BDT_ZERO: Self

pub const UNIX_EPOCH: Self

TAI time between 1970-01-01 midnight and 2000-01-01 noon

pub const GPS_EPOCH: Self

Traditional GNSS epochs

pub const GALEX_EPOCH: Self = Self::GPS_EPOCH

pub const GALILEO_EPOCH: Self

pub const BDT_EPOCH: Self

pub const fn new(sec: i64, attos: u64) -> Self

Creates a new Dt from whole seconds, a subsecond part in attoseconds, and a scale, automatically normalizing the representation.

pub const fn new_custom_clock(self, drift: ClockDrift) -> ClockModel

Creates a new custom clock model using this exact instant as the reference epoch.

The supplied ClockDrift defines the relativistic model for the new clock. The resulting ClockModel can be used to convert to or from the custom timescale even after the observer has left the original reference frame.

pub const fn from_attos(attos: i128, scale: Scale) -> Self

pub const fn from_sec(sec: i64, scale: Scale) -> Self

pub const fn from_ms(ms: i128, scale: Scale) -> Self

pub const fn from_us(us: i128, scale: Scale) -> Self

pub const fn from_ns(ns: i128, scale: Scale) -> Self

pub const fn from_ps(ps: i128, scale: Scale) -> Self

pub const fn from_fs(fs: i128, scale: Scale) -> Self

pub const fn from_min(m: i64, scale: Scale) -> Self

pub const fn from_hr(h: i64, scale: Scale) -> Self

pub const fn from_hms( hr: i64, min: i64, sec: i64, ms: i128, us: i128, ns: i128, scale: Scale, ) -> Self

Creates a Dt from hours, minutes, seconds, milliseconds, microseconds, and nanoseconds on the supplied scale.

impl Dt

pub const fn to_span(&self) -> TSpan

pub const fn from(sec: i64, attos: u64, scale: Scale) -> Dt

pub const fn to(&self, scale: Scale) -> TSpan

Returns a bare TSpan containing the numerical sec/attos values of this instant on its own Scale (same physical moment).

This is the recommended way for callers to obtain the representation on a particular scale after construction via Self::from.

pub const fn convert_using_drift( self, reference: Self, drift: ClockDrift, ) -> Self

Converts this instant to any other Scale while applying an exact quadratic relativistic or clock-drift correction defined by a ClockDrift model relative to a reference instant.

pub const fn convert_back_using_drift( self, reference: Self, drift: ClockDrift, ) -> Self

Performs the inverse conversion of Self::convert_using_drift, recovering the original proper time on the source clock scale.

A fixed-point iteration (at most 16 steps) is used to solve the implicit equation. For the common case of a pure constant offset the function returns immediately without iteration.

pub const fn convert_using_model(self, model: ClockModel) -> Self

Converts this instant using a self-describing ClockModel.

This is the recommended high-level API for onboard or custom time scales (Proper, Custom, or any model with a defined base and drift).

pub const fn convert_back_using_model(self, model: ClockModel) -> Self

Performs the inverse conversion of Self::convert_using_model.

impl Dt

pub const fn to_msd_exact(self) -> (i64, u128)

Returns the exact Mars Sol Date (MSD) as a tuple of integer sols and the fractional part of a sol.

The computation follows the canonical NASA GISS / AM2000 formulation and works for any input Scale. Leap seconds are automatically accounted for when converting from UTC.

pub const fn to_mtc(self) -> TSpan

Returns Mars Coordinated Time (MTC) as a TSpan representing seconds into the current sol (range [0, one Martian sol)).

pub const fn from_msd_exact(whole_sols: i64, frac_attos: u128) -> Self

Creates a Dt (in TT) from an exact Mars Sol Date using full library precision.

pub const fn from_msd(msd: Real) -> Self

Creates a Dt (in TT) from a floating-point Mars Sol Date. Non-exact Real.

pub const fn to_msd(self) -> Real

Returns the Mars Sol Date (MSD) as a floating-point value (matches NASA Mars24 output). Non-exact Real.

impl Dt

pub const fn to_tai_attos_since(self, reference: Dt) -> i128

pub const fn from_tai_attos_since(attos: i128, reference: Dt) -> Self

pub const fn to_epoch(self, epoch: Dt, scale: Scale) -> TSpan

pub const fn from_epoch(offset: TSpan, epoch: Dt, scale: Scale) -> Self

impl Dt

pub fn from_ccsds_str(input: &str) -> Result<Self, DtErr>

Generalized CCSDS ASCII Time Code parser (A or B variant). Handles both calendar (%Y-%m-%d) and day-of-year (%Y-%j) formats. All time components after the date portion are optional.

pub fn from_ccsds_ccs(input: &[u8]) -> Result<Dt, DtErr>

Parses a CCSDS CCS (Calendar Segmented Time Code) binary time code directly into TimeParts.

Implements CCSDS 301.0-B-4 §3.4 (Level 1 only).

P-field (exactly 1 byte)

• Bit 7: Extension flag → must be 0 (we reject extensions)
• Bits 6-4: Code ID = 101
• Bit 3: Calendar type (0 = Month/Day, 1 = Day-of-Year)
• Bits 2-0: Number of subsecond BCD octets (0–6)

T-field (BCD, big-endian)

• 2 bytes: Year (0001–9999)
• 2 bytes: Month+Day (01-12,01-31) or Day-of-Year (001–366)
• 3 bytes: Hour (00-23), Minute (00-59), Second (00-60)
• 0–6 bytes: Fractional seconds (exactly 2 decimal digits per byte)

Epoch: 1958-01-01 00:00:00 UTC (identical to CDS).

pub fn from_ccsds_c(input: &[u8]) -> Result<Dt, DtErr>

Parses a CCSDS C (CUC – Unsegmented Time Code) binary time code directly into Dt.

This function implements CCSDS 301.0-B-4 §3.2 (Level 1 only) with full support for the extended P-field (second octet) as defined in the standard.

Supported formats (Level 1 only)

• 1-byte or 2-byte P-field (further extension beyond 2 bytes is rejected).
• Code ID must be 001 (1958-01-01 TAI epoch).
• Coarse time: 1–7 octets (base 1–4 from Octet 1 + up to 3 additional from Octet 2).
• Fractional time: 0–10 octets (base 0–3 from Octet 1 + up to 7 additional from Octet 2).

P-field decoding (when Bit 0 of Octet 1 = 1)

• Octet 2:
  • Bit 0: Further-extension flag (must be 0; we reject 3+-byte P-fields).
  • Bits 1-2: Additional coarse octets (0–3).
  • Bits 3-5: Additional fractional octets (0–7).
  • Bits 6-7: Reserved for mission definition (ignored).

Precision

Fractional seconds are converted to attoseconds with exact integer scaling (value / 2^(8·n_frac)). Larger n_frac gives higher resolution (down to ~2⁻⁸⁰ s with 10 fractional bytes).

Returns

A Dt with scale = TAI and tz = Utc.

Errors

• [DtErrKind::CCSDSBinEmpty] if the input is empty.
• [DtErrKind::CCSDSBinTooShort] if the input is too short for the declared P-field / T-field sizes or otherwise malformed.
• [DtErrKind::CCSDSBinInvalidCodeId] if the Code ID is not 001.
• [DtErrKind::CCSDSBinInvalidPFieldExtension] if the further-extension flag is set (3+ byte P-field, unsupported).

pub fn from_ccsds_d(input: &[u8]) -> Result<Dt, DtErr>

Parses a CCSDS D (CDS – Day Segmented Time Code) binary time code directly into Dt.

This function implements CCSDS 301.0-B-4 §3.3 (Level 1 only).

Supported formats

• 1-byte or 2-byte P-field.
• Code ID must be 100 and Epoch bit must be 0 (1958-01-01 UTC epoch).
• n_day: 2 or 3 bytes for the day count.
• Middle field is always 4 bytes of milliseconds since midnight.
• Sub-millisecond field (bits 6-7 of P-field):
  • 00: no fractional field
  • 01: 2 bytes (microseconds of the millisecond, 0–65535)
  • 10: 4 bytes (2⁻³² of the millisecond)

Precision

• The millisecond field is rounded to the nearest millisecond (in the encoder).
• With 2-byte sub-ms: maximum quantization error ≈ ±7.63 ns.
• With 4-byte sub-ms: maximum quantization error ≈ ±0.116 ps.

Returns

A Dt with timescale = Utc and tz = Utc.

Errors

• [DtErrKind::CCSDSBinEmpty] if the input is empty.
• [DtErrKind::CCSDSBinTooShort] if the input is too short for the declared field sizes.
• [DtErrKind::CCSDSBinInvalidCodeId] if the Code ID is not 100.
• [DtErrKind::CCSDSBinInvalidEpoch] if the Epoch bit is set (non-Level-1 / non-1958 epoch).
• [DtErrKind::CCSDSBinInvalidSubMillisecondCode] if bits 6-7 encode an unsupported value (0b11).

pub fn from_ccsds_bin(input: &[u8]) -> Result<Dt, DtErr>

Auto-detects and parses a CCSDS binary time code (CUC, CDS, or CCS) based on the Code ID in the first P-field byte.

Convenience wrapper around TimeParts::from_ccsds_bin.

Supported formats

• Code ID 001 → CUC (Unsegmented)
• Code ID 100 → CDS (Day Segmented)
• Code ID 101 → CCS (Calendar Segmented)

Errors

• [DtErrKind::CCSDSBinEmpty] if the input is empty.
• [DtErrKind::CCSDSBinInvalidCodeId] for any other Code ID.

impl Dt

pub const fn from_gps_wk_and_tow(wk: i64, tow: TSpan) -> Self

Creates a Dt in GPS Time (GPS) from a GPS week number and Time of Week (TOW).

This is the exact inverse of [Self::to_gps_week_and_tow].

• week: Full GPS week number (can be negative for dates before 1980).
• tow: Time of Week as a TSpan. Values ≥ 604800 seconds are automatically carried into the week number.

The resulting Dt is always in Scale::GPS.

pub const fn from_gps_wk_and_tow_f(week: i64, tow: Real) -> Self

Creates a Dt in GPS Time from a GPS week number and floating-point Time of Week.

This is the floating-point counterpart to Self::from_gps_wk_and_tow.

impl Dt

pub fn from_str( s: &str, fmt: &str, inp_can_end_before_fmt: bool, fmt_can_end_before_inp: bool, allow_partial_date: bool, ) -> Option<Dt>

impl Dt

pub const fn unix_sec_to_gregorian_ymd(unix_sec: i64) -> (i64, u8, u8)

Converts a Unix timestamp (seconds since 1970-01-01 00:00:00 UTC) to a proleptic Gregorian date (year, month, day).

pub const fn to_gregorian_time(&self) -> GregorianTime

pub const fn to_ymdhms(&self) -> YmdHms

Stripped down version of Dt::to_gregorian_time.

Returns the Gregorian date and wall time for this instant.

• For Scale::UTC: Uses a direct Unix-timestamp-based path (fast and clean).
• For all other scales: Uses the standard TT-based JD path.

pub const fn ymdhms_to_unix_sec( year: i64, month: u8, day: u8, hour: u8, minute: u8, second: u8, ) -> i64

Converts a proleptic Gregorian calendar date+time to a Unix timestamp (seconds since 1970-01-01 00:00:00 UTC).

This version is correct for the full i64 range, including negative years.

pub const fn jdn_to_ymd(jdn: i64) -> (i64, u8, u8)

Converts a Julian Day Number (JDN) to a proleptic Gregorian calendar date.

Returns (year, month, day) where month ∈ [1, 12] and day ∈ [1, 31] (standard 1-based Gregorian values).

This is the inverse of Self::ymd_to_jdn. Supports the full i64 range, including negative years and year zero.

pub const fn ymd_to_jdn(year: i64, month: u8, day: u8) -> i64

Computes the Julian Day Number (JDN) for a proleptic Gregorian calendar date at noon UT.

The algorithm matches the standard astronomical convention used throughout the library (ymd_to_jdn(2000, 1, 1) == 2451545).

pub const fn is_leap_year(year: i64) -> bool

Returns true if the given year is a Gregorian leap year under proleptic rules.

pub const fn from_ymdhms( yr: i64, mo: u8, day: u8, hr: u8, min: u8, sec: u8, attos: u64, ) -> Self

Creates a Dt at the specified civil UTC instant with full attosecond precision on the proleptic Gregorian calendar, then converts it to the requested Scale.

All input components are clamped to their valid ranges:

• mo → 0..=12
• day → 0..=31
• hr → 0..=23
• min → 0..=59
• sec → 0..=60 (permits leap seconds)
• attos → values ≥ 10¹⁸ are carried into the seconds field

pub const fn from_ymdhms_on( yr: i64, mo: u8, day: u8, hr: u8, min: u8, sec: u8, attos: u64, scale: Scale, ) -> Self

pub const fn from_ymd(yr: i64, mo: u8, day: u8) -> Self

Creates a Dt representing 00:00:00 UTC on the given proleptic Gregorian date, converted to the requested Scale.

The date components are interpreted according to POSIX civil time (leap seconds are not inserted into the day count).

pub const fn from_ymd_on(yr: i64, mo: u8, day: u8, scale: Scale) -> Self

pub const fn ydoy_to_jdn(year: i64, day_of_year: u16) -> i64

Computes the Julian Day Number from a Gregorian year and ordinal day-of-year.

pub const fn jdn_to_weekday(jdn: i64) -> u8

Converts a Julian Day Number to the corresponding weekday number (0 = Sunday … 6 = Saturday).

pub const fn ymd_to_jdn_from_iso_week( iso_year: i64, iso_week: u8, weekday: Weekday, ) -> i64

Computes the Julian Day Number from an ISO week date (Monday-based week).

pub const fn ymd_to_jdn_from_week_sun( year: i64, week: u8, weekday: Weekday, ) -> i64

Computes the Julian Day Number from a Sunday-based week-of-year (%U).

pub const fn ymd_to_jdn_from_week_mon( year: i64, week: u8, weekday: Weekday, ) -> i64

Computes the Julian Day Number from a Monday-based week-of-year (%W).

pub const fn is_valid_ymd(year: i64, month: u8, day: u8) -> bool

Returns true if the supplied values form a valid proleptic Gregorian calendar date.

pub const fn has_iso_week_53(year: i64) -> bool

Returns true if the given Gregorian year contains an ISO week 53.

pub const fn day_of_year(&self, ymd: Option<(i64, u8, u8)>) -> u16

Returns the ordinal day of the year (1-based).

January 1 is day 1; December 31 is day 365 or 366 (in leap years). Uses the proleptic Gregorian calendar.

pub const fn wk_sun(&self, ymd: Option<(i64, u8, u8)>, doy: Option<u16>) -> u8

Sunday-based week number (%U in strftime).

Range: 0..=53.

• Week 0 contains the days before the first Sunday of the year.
• Week 1 begins on the first Sunday of the year.

The optional ymd and doy arguments are performance optimisations (same pattern used throughout the file for day_of_year, to_iso_week_date, etc.). Pass whichever you already have; the function will use the fastest path.

pub const fn wk_mon(&self, ymd: Option<(i64, u8, u8)>, doy: Option<u16>) -> u8

Monday-based week number (%W in strftime).

Range: 0..=53.

• Week 0 contains the days before the first Monday of the year.
• Week 1 begins on the first Monday of the year.

The optional ymd and doy arguments are performance optimisations (same pattern as wk_sun, day_of_year, to_iso_week_date, etc.).

pub const fn to_iso_week_date( &self, ymd: Option<(i64, u8, u8)>, ) -> (i64, u8, Weekday)

Returns the ISO 8601 week date for this Dt.

Returns (iso_year, iso_week, weekday) where:

• iso_year is the ISO week year (may differ from the Gregorian year near year boundaries),
• iso_week is the week number in the range 1..=53,
• weekday is a Weekday value (Monday-based week).

Follows the ISO 8601 standard: weeks start on Monday and week 1 is the week containing January 4.

The optional ymd argument is a performance optimization. If provided, it is used directly; otherwise to_gregorian_ymd is called internally.

impl Dt

pub const fn to_jd_exact(self, target: Scale) -> (i64, u128)

Returns the exact Julian Date of this instant as (integer_days, fractional_attoseconds).

The fractional part is always in [0, ATTOS_PER_DAY).

Behavior by scale

• UTC, UTCSofa, UTCSpice: Computes JD(UTC) using the Unix epoch (1970-01-01 00:00:00 UTC) as reference. This produces the Julian Date that corresponds to the civil UTC clock reading (the value used by IERS C04 tables, most astronomy software, and online JD calculators).

• All other types (TAI, TT, TDB, GPS, TCG, etc.): Computes JD(TT) (or equivalent uniform scale) using the J2000.0 TT epoch (J2000_JD_TT = 2451545). This is the continuous, leap-second-free value used for ephemerides and dynamical calculations.

The returned value therefore depends on both the physical instant and the declared time scale of self.

Precision

Exact (attosecond resolution). Use to_jd for the floating-point version.

pub const fn to_jd(self, target: Scale) -> Real

Returns the Julian Date of this instant as a floating-point Real (f64).

This is the lossy counterpart to to_jd_exact. See that method for the exact scale-dependent behavior (JD(UTC) vs JD(TT)).

pub const fn to_mjd_exact(self, target: Scale) -> (i64, u128)

Returns the exact Modified Julian Date of this instant as (integer_days, fractional_attoseconds).

The fractional part is always in [0, ATTOS_PER_DAY).

Behavior by scale

• UTC, UTCSofa, UTCSpice: Computes MJD(UTC) using the Unix epoch (1970-01-01 00:00:00 UTC). This matches the MJD column in IERS C04 / Bulletin A tables (0h UTC epochs) and most civil/UTC-labeled data products.

• All other types: Computes the MJD equivalent of the uniform-scale JD (normally JD(TT) – 2_400_000.5) with proper half-day adjustment.

Precision

Exact (attosecond resolution). Use to_mjd for the floating-point version.

pub const fn to_mjd(self, target: Scale) -> Real

Returns the Modified Julian Date of this instant as a floating-point Real (f64).

This is the lossy counterpart to to_mjd_exact. See that method for the exact scale-dependent behavior (MJD(UTC) vs uniform MJD).

pub const fn from_jd_exact( jd_days: i64, frac_attos: u128, orig_type: Scale, ) -> Self

Creates a Dt from an exact Julian Date, interpreting the JD in the scale indicated by orig_type.

• If orig_type is UTC / UTCSofa / UTCSpice, the input JD is treated as JD(UTC) and the resulting Dt will have the corresponding UTC civil time (leap-second aware).
• For all other types the input JD is treated as the uniform-scale JD (normally JD(TT)) and the resulting Dt is constructed on that scale.

The returned Dt represents the physical instant whose JD (in the requested scale) matches the input.

Precision

Exact (attosecond resolution).

pub const fn from_mjd_exact( mjd_days: i64, frac_attos: u128, orig_type: Scale, ) -> Self

Creates a Dt from an exact Modified Julian Date, interpreting the MJD in the scale indicated by orig_type.

This is the inverse of to_mjd_exact. See that method and from_jd_exact for scale-specific behavior.

Precision

Exact (attosecond resolution).

impl Dt

pub const fn cmp(self, other: Self) -> Ordering

Compares this Dt with another by converting both to the TAI timescale (the library’s canonical physical-time reference) and then comparing their (sec, attos) pairs.

This is a const fn so it can be used in const contexts and is allocation-free. It provides the total order used by <, >, <=, >=, cmp, etc.

Two Dts that represent the exact same physical instant (after all leap-second, relativistic, and scale conversions) compare as Equal, even if they were constructed with different [Scale]s.

pub const fn min(self, other: Self) -> Self

Returns the smaller of two Dts according to the total physical-time order defined by Self::cmp.

Both instants are converted to TAI internally, so the result is the physically earlier instant even when the two Dts belong to different [Scale]s (leap seconds, relativistic offsets, etc. are all taken into account).

This is a const fn and can be used in const contexts.

pub const fn max(self, other: Self) -> Self

Returns the larger of two Dts according to the total physical-time order defined by Self::cmp.

See Self::min for more details.

pub const fn eq(&self, other: &Self) -> bool

impl Dt

pub const CCSDS_C_AND_D_MAX_SIZE: usize = 32

Maximum size needed for a CCSDS C & D (CUC) binary packet (with extended P-field).

pub const CCSDS_CCS_MAX_SIZE: usize = 14

Maximum size needed for a CCSDS CCS binary packet (P-field + T-field).

pub fn to_ccsds_c( &self, n_coarse: u8, n_frac: u8, extension: bool, ) -> Result<([u8; 32], usize), DtErr>

Formats this Dt as a CCSDS C (CUC) binary time code.

Fully configurable for round-tripping with [from_ccsds_c]. Conforms to CCSDS 301.0-B-4 §3.2 (Level 1), including full support for the extended P-field (second octet) when n_coarse > 4 or n_frac > 3.

Parameters

• n_coarse: 1–7 (number of coarse-time octets)
• n_frac: 0–10 (number of fractional octets)
• extension: advisory flag (ignored when larger sizes force the second octet)

pub fn to_ccsds_d( &self, n_day: u8, sub_ms_code: u8, extension: bool, ) -> Result<([u8; 32], usize), DtErr>

Formats this Dt as a CCSDS D (CDS) binary time code.

Fully configurable for round-tripping with [from_ccsds_d]. Conforms to CCSDS 301.0-B-4 §3.3 (Level 1): UTC day count + ms-of-day since 1958-01-01 UTC.

pub fn to_ccsds_ccs( &self, use_doy: bool, n_subsec: u8, ) -> Result<([u8; 14], usize), DtErr>

Formats this Dt as a CCSDS CCS (Calendar Segmented Time Code).

Implements CCSDS 301.0-B-4 §3.4 (Level 1 only).

Parameters

• use_doy: false = Month/Day variant (most common), true = Day-of-Year variant
• n_subsec: Number of subsecond BCD octets (0–6). Each octet holds 2 decimal digits.

Returns

(buffer, written_len) — the P-field + T-field (big-endian BCD).

Precision & Rounding

Fractional seconds are rounded to the nearest representable value at the chosen precision (exactly as to_ccsds_d does for milliseconds).

pub fn to_ccsds_bin(&self, scale: Scale) -> Result<([u8; 32], usize), DtErr>

Convenience method that automatically selects the most appropriate CCSDS binary time code based on scale.

• Scale::TAI → CUC (4 coarse + 4 fractional bytes)
• Any other Scale (UTC, TT, GPS, TCG, …) → uses CDS (2 day bytes + 4 ms bytes + 2-byte sub-ms)

impl Dt

pub const fn to_gps_wk_and_tow(&self) -> (i64, TSpan)

Returns the GPS week number and exact Time of Week (TOW) for this instant when expressed in GPS Time (GPS).

This is the format used by virtually all GNSS receivers, RINEX observation files, NMEA sentences, and raw satellite navigation messages.

• GPS week number: Full (untruncated) count of 7-day weeks since the traditional GPS reference epoch 1980-01-06 00:00:00 GPS. Returned as i64 (effectively unlimited range).
• Time of Week (TOW): Exact elapsed time since the start of that GPS week, returned as a TSpan in the range [0, 604800) seconds.

GPS weeks always begin on Sunday 00:00:00 GPS.

Correctness notes

• The calculation is performed entirely on the GPS scale.
• GPS has no leap seconds (it is a continuous time scale).
• Leap seconds are automatically handled when converting from UTC or other scales via to_type(Scale::GPS).
• The result is exact (attosecond precision) and independent of any calendar or timezone rules.

pub const fn to_gps_day_of_wk(&self) -> u8

Returns the day of the GPS week (0 = Sunday, 1 = Monday, …, 6 = Saturday).

This is computed directly from GPS Time and is independent of the Gregorian calendar.

pub const fn to_gps_tow_f(&self) -> Real

Returns the Time of Week (TOW) as a floating-point value in seconds.

This is a convenience method for code that prefers f64 / Real. For full attosecond precision use Self::to_gps_wk_and_tow.

pub const fn to_gps_week_number(&self) -> i64

Returns only the GPS week number (full, untruncated).

impl Dt

pub fn to_str_bin(&self, fmt: &str) -> Result<AsciiStr<STRFTIME_SIZE>, DtErr>

No-alloc label-only formatting.

pub fn to_str_bin_with_offset( &self, fmt: &str, secs: i32, ) -> Result<AsciiStr<STRFTIME_SIZE>, DtErr>

No-alloc label-only formatting.

pub fn to_str_bin_with_tz( &self, fmt: &str, tz_name: &str, ) -> Result<AsciiStr<STRFTIME_SIZE>, DtErr>

No-alloc full IANA adjusted formatting (civil time is adjusted to local wall time).

pub const fn sec_as_hhmm(seconds: i32) -> (bool, u8, u8)

Returns (is_negative, hours, minutes).

pub fn to_u8_with_offset( &self, fmt: &str, dest: &mut [u8], secs: i32, ) -> Result<usize, DtErr>

Helper for to_str.

pub fn to_u8_with_tz( &self, fmt: &str, dest: &mut [u8], tz_name: &str, ) -> Result<usize, DtErr>

Helper for to_str.

impl Dt

pub const fn proper_time_interval_samples( self, end: Dt, samples: &[LocalSpacetime], ) -> TSpan

Computes the accumulated proper time (Δτ) experienced by a clock moving along a coordinate-time path from self to end.

Proper time is the actual time measured by a real physical clock (onboard spacecraft clock, probe, etc.). This function evaluates the exact relativistic rate dτ/dt = √K_eff from the library’s unified master Lagrangian at each sample point and integrates using composite Simpson’s rule.

Use this whenever velocity, gravitational potential, or spacetime curvature changes along the trajectory (e.g. planetary flybys, cislunar transfers, deep-space maneuvers, or strong-field regions). It automatically includes special-relativistic velocity effects, general-relativistic gravitational time dilation, and the built-in Planck-scale saturation term.

Parameters

• end — the ending coordinate time of the interval.
• samples — slice of LocalSpacetime snapshots evaluated at uniformly spaced points along the path (must contain at least two entries). These samples can be freely reused elsewhere (e.g. for light-time calculations in ObserverState).

Returns

The accumulated proper-time interval Δτ (exact 36-digit precision).

Example

use deep_time::{Scale, TSpan, LocalSpacetime, Dt};

let start = Dt::from_sec(0, Scale::TAI);
let end   = Dt::from_sec(1000, Scale::TAI);

// Constant metric example (α = 0.9 → dτ/dt = 0.9)
let slow = LocalSpacetime::new(0.9, 0.0, 0.0);
let samples = [slow; 2];

let delta_tau = start.proper_time_interval_samples(end, &samples);
assert_eq!(delta_tau, TSpan::from_sec(900));

// Update onboard proper time clock
let onboard_tau = start.to(Scale::Custom).add(delta_tau);

pub const fn relativistic_correction_with_samples( self, end: Dt, samples: &[LocalSpacetime], ) -> TSpan

Computes the relativistic correction (Δτ − Δt) using pre-computed samples.

Returns how much the onboard clock has gained or lost relative to coordinate time. Positive values mean the clock ran fast; negative values mean it ran slow.

Parameters

• end — ending coordinate time.
• samples — uniformly spaced LocalSpacetime snapshots (see [proper_time_interval_samples] for details and example).

Returns

The relativistic correction as a TSpan.

impl Dt

pub const fn sec(&self) -> i64

Seconds field getter.

pub const fn attos(&self) -> u64

Subseconds field getter (attoseconds).

pub const fn carry_over(&mut self) -> &mut Self

Normalizes the representation so that the attosecond part lies in the range [0, ATTOS_PER_SEC).

impl Dt

pub const fn every(self, step: TSpan) -> Every

Starts building an evenly-spaced time range.

This method returns an Every builder that can be chained with .until(end) or .up_to(end) to create a TimeRange iterator.

Example

let start = Dt::from_gregorian(2025, 1, 1, 0, 0, 0, 0, Scale::TAI);
let step = TSpan::from_hours(1);

// Inclusive range: yields 25 points (including both start and end)
for t in start.every(step).until(end) { ... }

// Exclusive range: yields 24 points
for t in start.every(step).up_to(end) { ... }

pub const fn range_to(self, end: Dt, step: TSpan) -> TimeRange

Creates an inclusive evenly-spaced range from self to end.

Equivalent to self.every(step).until(end).

pub const fn range_until(self, end: Dt, step: TSpan) -> TimeRange

Creates an exclusive evenly-spaced range from self to end.

Equivalent to self.every(step).up_to(end).

pub const fn every_second(self) -> Every

Creates a range stepping by whole seconds.

pub const fn every_minute(self) -> Every

Creates a range stepping by whole minutes.

pub const fn every_hour(self) -> Every

Creates a range stepping by whole hours.

pub const fn every_day(self) -> Every

Creates a range stepping by whole days.

pub fn next_n(self, n: usize, step: TSpan) -> impl Iterator<Item = Dt>

Returns the next n points after self (exclusive of self) at the given step.

This is a convenient way to get future points without including the start.

pub fn for_n_steps(self, n: usize, step: TSpan) -> impl Iterator<Item = Dt>

Returns an iterator yielding exactly n evenly spaced points starting from self.

This is a convenient one-liner for the common “next N steps” pattern.

Trait Implementations

impl Add<TSpan> for Dt

type Output = Dt

The resulting type after applying the + operator.

fn add(self, rhs: TSpan) -> Self

Performs the + operation.

impl AddAssign<TSpan> for Dt

fn add_assign(&mut self, rhs: TSpan)

Performs the += operation.

impl Clone for Dt

fn clone(&self) -> Dt

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Dt

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Dt

fn default() -> Self

Returns the “default value” for a type.

impl Display for Dt

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for Dt

fn hash<H: Hasher>(&self, state: &mut H)

Hashes the canonical TAI representation so that two Dts that are physically equal (after conversion) produce the same hash, regardless of the original [Scale].

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Dt

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Dt

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Dt

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Sub<TSpan> for Dt

type Output = Dt

The resulting type after applying the - operator.

fn sub(self, rhs: TSpan) -> Self

Performs the - operation.

impl Sub for Dt

type Output = TSpan

The resulting type after applying the - operator.

fn sub(self, rhs: Dt) -> TSpan

Performs the - operation.

impl SubAssign<TSpan> for Dt

fn sub_assign(&mut self, rhs: TSpan)

Performs the -= operation.

impl Copy for Dt

impl Eq for Dt