Struct Time 

pub struct Time<S: Scale, F: TimeFormat = J2000s> { /* private fields */ }

A point in time on scale S, tagged with external format phantom F.

The default F is J2000s, so Time<S> in code is Time<S, J2000s>: SI seconds since J2000.0 TT on the scale’s coordinate axis.

Storage is always a compensated (hi, lo) pair of seconds. The format tag does not duplicate storage; it only types the API (raw(), conversions, …).

Preconditions

NaN must never appear in encoded scalars or storage components — behavior is undefined if it does. ±∞ may be carried when callers use instants as sentinels; operations that require finite coordinates (ΔT loops, UTC civil decoding, POSIX Unix mapping, …) may still return ConversionError::NonFinite.

Implementations

impl<F> Time<TT, F>

where F: InfallibleFormatForScale<TT> + InfallibleConversionTarget<TT, Output = Time<TT, F>> + TimeFormat,

pub fn try_from_chrono(dt: DateTime<Utc>) -> Result<Self, ConversionError>

Build a TT Time in format F from a UTC chrono timestamp.

pub fn from_chrono(dt: DateTime<Utc>) -> Self

Build a TT Time in format F from a UTC chrono timestamp.

pub fn try_from_chrono_with( dt: DateTime<Utc>, ctx: &TimeContext, ) -> Result<Self, ConversionError>

Like Self::try_from_chrono, but uses an explicit TimeContext.

pub fn from_chrono_with(dt: DateTime<Utc>, ctx: &TimeContext) -> Self

Like Self::from_chrono, but uses an explicit TimeContext.

pub fn try_to_chrono(self) -> Result<DateTime<Utc>, ConversionError>

Convert to a UTC chrono timestamp (TT → UTC using a default context).

pub fn to_chrono(self) -> Option<DateTime<Utc>>

Convert to a UTC chrono timestamp (TT → UTC using a default context).

pub fn try_to_chrono_with( self, ctx: &TimeContext, ) -> Result<DateTime<Utc>, ConversionError>

Like Self::try_to_chrono, but uses an explicit TimeContext.

pub fn to_chrono_with(self, ctx: &TimeContext) -> Option<DateTime<Utc>>

Like Self::to_chrono, but uses an explicit TimeContext.

impl Time<UTC>

pub fn parse_rfc3339(s: &str) -> Result<Self, ConversionError>

Parse an RFC 3339 / ISO 8601 timestamp (UTC, Z suffix or named offset). Accepts the leap-second form 23:59:60[.x] during announced positive leap seconds.

pub fn parse_rfc3339_with( s: &str, ctx: &TimeContext, ) -> Result<Self, ConversionError>

Like parse_rfc3339, with an explicit TimeContext.

pub fn format_rfc3339(&self, opts: FormatOptions) -> String

Format this UTC instant as RFC 3339 with the given options.

Emits 23:59:60[.fraction]Z when the instant lies during an announced positive leap second according to the default TimeContext.

pub fn format_rfc3339_with( &self, opts: FormatOptions, ctx: &TimeContext, ) -> String

Like format_rfc3339, with an explicit TimeContext.

Returns "<invalid>" if the instant cannot be converted to civil UTC. Use try_format_rfc3339_with to handle that case explicitly.

pub fn try_format_rfc3339_with( &self, opts: FormatOptions, ctx: &TimeContext, ) -> Result<String, ConversionError>

Fallible variant of format_rfc3339_with.

Returns ConversionError if the underlying UTC↔chrono conversion fails (e.g. out-of-range dates).

impl<S: GnssWeekScale> Time<S>

pub fn to_gnss_week(&self) -> Result<GnssWeek, ConversionError>

Decompose this GNSS-scale instant into (week, seconds_of_week, subsecond_nanos) since the constellation’s defined epoch.

The week number is full (no rollover applied); callers wanting the modular broadcast value should compute week % S::rollover_period_weeks().

The whole-second decomposition uses integer arithmetic on the split-f64 storage pair. The subsecond_nanos field is computed from the fractional remainder; see the module doc for precision limits.

pub fn from_gnss_week(gw: GnssWeek) -> Result<Self, ConversionError>

Build a GNSS-scale instant from (week, seconds_of_week, subsecond_nanos) since the constellation’s defined epoch.

Uses add_exact to add the integer whole-second and nanosecond components to the epoch separately, preserving sub-millisecond precision within the split-f64 storage limits.

impl<F: TimeFormat> Time<UTC, F>

pub fn try_from_chrono_with( dt: DateTime<Utc>, ctx: &TimeContext, ) -> Result<Time<UTC, J2000s>, ConversionError>

Build a UTC instant from a chrono::DateTime<Utc> using the context’s captured time-data bundle.

pub fn try_from_chrono( dt: DateTime<Utc>, ) -> Result<Time<UTC, J2000s>, ConversionError>

Build a UTC instant from a chrono::DateTime<Utc>.

Snapshots the active time-data bundle at call time via TimeContext::new. For reproducible pipelines, prefer try_from_chrono_with with an explicit context.

pub fn from_chrono_with( dt: DateTime<Utc>, ctx: &TimeContext, ) -> Time<UTC, J2000s>

Convenience panicking wrapper over try_from_chrono_with.

pub fn from_chrono(dt: DateTime<Utc>) -> Time<UTC, J2000s>

Convenience panicking wrapper over try_from_chrono.

Snapshots the active time-data bundle at call time via TimeContext::new. For reproducible pipelines, prefer from_chrono_with.

pub fn try_to_chrono_with( self, ctx: &TimeContext, ) -> Result<DateTime<Utc>, ConversionError>

Convert to a chrono::DateTime<Utc>, preserving leap-second labels, using the context’s captured time-data bundle.

pub fn try_to_chrono(self) -> Result<DateTime<Utc>, ConversionError>

Convert to a chrono::DateTime<Utc>, preserving leap-second labels.

Snapshots the active time-data bundle at call time via TimeContext::new. For reproducible pipelines, prefer try_to_chrono_with with an explicit context.

pub fn to_chrono_with(self, ctx: &TimeContext) -> Option<DateTime<Utc>>

Convenience non-fallible wrapper (returns None on error) using the context’s captured time-data bundle.

pub fn to_chrono(self) -> Option<DateTime<Utc>>

Convenience non-fallible wrapper (returns None on error).

Snapshots the active time-data bundle at call time via TimeContext::new. For reproducible pipelines, prefer to_chrono_with.

pub fn is_leap_second_with(self, ctx: &TimeContext) -> bool

Returns true if this instant falls inside a positive leap second in UTC (e.g. 23:59:60) using the context’s captured time-data bundle.

pub fn is_leap_second(self) -> bool

Returns true if this instant falls inside a positive leap second in UTC (e.g. 23:59:60).

Snapshots the active time-data bundle at call time via TimeContext::new. For reproducible pipelines, prefer is_leap_second_with.

impl<S: Scale, F: TimeFormat> Time<S, F>

pub fn reinterpret<G: TimeFormat>(self) -> Time<S, G>

Same instant, different format tag (zero cost).

pub fn to_j2000s(self) -> Time<S, J2000s>

SI J2000-second tagged view of the same instant.

pub fn raw_seconds_pair(self) -> (Second, Second)

Raw internal storage pair in J2000-TT seconds on the instance scale.

impl<S: CoordinateScale> Time<S, J2000s>

pub fn from_raw_j2000_seconds(seconds: Second) -> Result<Self, ConversionError>

Build from J2000 TT seconds on the scale’s coordinate axis.

pub fn try_from_raw_j2000_seconds_split( hi: Second, lo: Second, ) -> Result<Self, ConversionError>

Build from a split J2000-second pair on the scale’s coordinate axis.

pub fn shifted_by<U>(self, delta: Quantity<U>) -> Self

where U: TimeUnit,

Shift this instant forward by a typed duration.

pub fn shifted_back_by<U>(self, delta: Quantity<U>) -> Self

where U: TimeUnit,

Shift this instant backward by a typed duration.

pub fn duration_since(self, other: Self) -> Second

Duration from other to self.

pub fn duration_until(self, other: Self) -> Second

Duration from self to other.

impl<S: CoordinateScale, F: InfallibleFormatForScale<S>> Time<S, F>

pub fn raw(self) -> Quantity<F::Unit>

Encoded scalar for this format (derived from split storage).

pub fn quantity(self) -> Quantity<F::Unit>

Alias for Self::raw.

impl<S: CoordinateScale, F: TimeFormat> Time<S, F>

pub fn diff_exact(self, other: Self) -> Result<ExactDuration, DurationError>

Exact-precision duration from other to self.

Unlike the Sub implementation that returns a Quantity<F::Unit> (and therefore goes through f64), this method projects the difference into crate::ExactDuration, which has 1 ns resolution.

Precision note: Time<S> stores instants as a compensated split-f64 pair. Near typical astronomy epochs (e.g. J2000 ± 50 years) the ULP of the high word is roughly 120–150 ns, so differences smaller than that may not round-trip exactly. For sub-microsecond precision on two instants that were originally constructed from the same ExactDuration arithmetic, the compensation pair reduces the error significantly, but this is not a guarantee of nanosecond parity for arbitrary instants.

Returns crate::DurationError::Overflow only if the difference is outside the i128-nanosecond range (≈ ±5.4 × 10²¹ yr), which is unreachable for any physical astronomy use case.

pub fn try_add_exact(self, delta: ExactDuration) -> Result<Self, DurationError>

Shift this instant by an crate::ExactDuration, returning Err if the duration’s seconds component exceeds the i64 range (≈ ±292 billion years).

Precision note: The duration is split into a whole-second component and a sub-second nanosecond remainder, each added to the compensated split-f64 storage separately. The whole-second part is an integer f64 (exact for |seconds| < 2^53). The nanosecond remainder crosses the split-f64 storage boundary and is therefore bounded by the documented split-f64 precision limits (ULP ≈ 120–150 ns near J2000 ± 50 years), so shifts smaller than that threshold may not alter the stored instant.

pub fn try_sub_exact(self, delta: ExactDuration) -> Result<Self, DurationError>

Shift this instant backward by an crate::ExactDuration, returning Err if the duration’s seconds component exceeds the i64 range.

See Self::try_add_exact for precision notes.

pub fn add_exact(self, delta: ExactDuration) -> Self

Shift this instant by an crate::ExactDuration.

Panics if the duration’s seconds component exceeds the i64 range (≈ ±292 billion years). Use try_add_exact for the fallible variant that returns Err instead.

See try_add_exact for precision notes.

pub fn sub_exact(self, delta: ExactDuration) -> Self

Shift this instant backward by an crate::ExactDuration.

Panics if the duration’s seconds component exceeds the i64 range. Use try_sub_exact for the fallible variant.

See try_add_exact for precision notes.

pub fn round_to_epoch(self, epoch: Self, quantum: ExactDuration) -> Self

Round this instant to the nearest multiple of quantum measured from epoch. Banker’s rounding (half-to-even) at the quantum boundary. Returns self unchanged on overflow.

pub fn floor_to_epoch(self, epoch: Self, quantum: ExactDuration) -> Self

Floor this instant toward epoch − ∞ at quantum.

pub fn ceil_to_epoch(self, epoch: Self, quantum: ExactDuration) -> Self

Ceil this instant toward epoch + ∞ at quantum.

impl<S: CoordinateScale, F> Time<S, F>

where F: FormatForScale<S>,

pub fn try_raw_with( self, ctx: &TimeContext, ) -> Result<Quantity<F::Unit>, ConversionError>

impl<S: Scale, F: TimeFormat> Time<S, F>

pub fn to<T>(self) -> T::Output

where T: InfallibleConversionTarget<S, F>,

Unified infallible conversion to a scale/view target.

pub fn try_to<T>(self) -> Result<T::Output, ConversionError>

where T: ConversionTarget<S, F>,

Unified fallible conversion to a scale/view target.

pub fn to_with<T>(self, ctx: &TimeContext) -> Result<T::Output, ConversionError>

where T: ContextConversionTarget<S, F>,

Unified context-backed conversion to a scale/view target.

pub fn to_scale<S2: Scale>(self) -> Time<S2, F>

where S: InfallibleScaleConvert<S2>,

Infallible scale conversion; preserves format tag F.

pub fn to_scale_with<S2: Scale>( self, ctx: &TimeContext, ) -> Result<Time<S2, F>, ConversionError>

where S: ContextScaleConvert<S2>,

Context-required scale conversion (UT1 routes); preserves F.

impl<S: Scale, F: FormatForScale<S>> Time<S, F>

pub fn try_new(raw: Quantity<F::Unit>) -> Result<Self, ConversionError>

Fallible constructor from an encoded scalar.

Only surfaces domain failures from format decoding (UTC policy, leap seconds, ranges, …). Scalar hygiene is a caller precondition: NaN must not be passed; ±∞ is accepted only where the format decoder tolerates it.

pub fn try_new_with( raw: Quantity<F::Unit>, ctx: &TimeContext, ) -> Result<Self, ConversionError>

Like Self::try_new, but uses ctx for UTC / POSIX decoding policy.

impl<S: Scale, F: InfallibleFormatForScale<S>> Time<S, F>

pub fn new(value: f64) -> Self

Infallible constructor from the raw scalar value for format F.

Panics

If value is NaN. ±∞ is allowed as storage when callers use sentinel instants.

impl<S: CoordinateScale, F: InfallibleFormatForScale<S>> Time<S, F>

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

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

pub fn mean(self, other: Self) -> Self

impl Time<TT, JD>

TT Julian date at J2000.0 (JD 2 451 545.0); matches Self::jd_epoch_tt, usable in const.

pub const JD_EPOCH_J2000_0: Self

impl<S: Scale> Time<S, JD>

pub fn jd_epoch_tt() -> Self

where S: CoordinateScale,

TT J2000.0 as a Julian Date on scale S (JD 2 451 545.0).

pub fn value(self) -> f64

where S: CoordinateScale,

pub fn julian_centuries(self) -> f64

where S: CoordinateScale,

impl<S: Scale> Time<S, MJD>

pub fn value(self) -> f64

where S: CoordinateScale,

Trait Implementations

impl<S: CoordinateScale, F, U> Add<Quantity<U>> for Time<S, F>

where F: InfallibleFormatForScale<S>, U: TimeUnit,

type Output = Time<S, F>

The resulting type after applying the + operator.

fn add(self, rhs: Quantity<U>) -> Self::Output

Performs the + operation.

impl<S: CoordinateScale, F, U> AddAssign<Quantity<U>> for Time<S, F>

where F: InfallibleFormatForScale<S>, U: TimeUnit,

fn add_assign(&mut self, rhs: Quantity<U>)

Performs the += operation.

impl<S: Scale, F: TimeFormat> Clone for Time<S, F>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<S: Scale, F: TimeFormat> Debug for Time<S, F>

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

Formats the value using the given formatter.

impl<S: CoordinateScale, F> Display for Time<S, F>

where F: InfallibleFormatForScale<S>, Quantity<F::Unit>: Display,

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

Formats the value using the given formatter.

impl Display for Time<UTC, Unix>

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

Formats the value using the given formatter.

impl<F> From<DateTime<Utc>> for Time<TT, F>

where F: InfallibleFormatForScale<TT> + InfallibleConversionTarget<TT, Output = Time<TT, F>> + TimeFormat,

fn from(value: DateTime<Utc>) -> Self

Converts to this type from the input type.

impl<S: Scale> From<Time<S, JD>> for Time<S>

fn from(value: JulianDate<S>) -> Self

Converts to this type from the input type.

impl<S: Scale> From<Time<S, MJD>> for Time<S>

fn from(value: ModifiedJulianDate<S>) -> Self

Converts to this type from the input type.

impl From<Time<TAI, GPS>> for Time<TAI>

fn from(value: GpsTime) -> Self

Converts to this type from the input type.

impl From<Time<UTC, Unix>> for Time<UTC>

fn from(value: UnixTime) -> Self

Converts to this type from the input type.

impl<S: CoordinateScale, F> LowerExp for Time<S, F>

where F: InfallibleFormatForScale<S>, Quantity<F::Unit>: LowerExp,

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

Formats the value using the given formatter.

impl<S: Scale, F: TimeFormat> PartialEq for Time<S, F>

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<S: Scale, F: TimeFormat> PartialOrd for Time<S, F>

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<S: CoordinateScale, F, U> Sub<Quantity<U>> for Time<S, F>

where F: InfallibleFormatForScale<S>, U: TimeUnit,

type Output = Time<S, F>

The resulting type after applying the - operator.

fn sub(self, rhs: Quantity<U>) -> Self::Output

Performs the - operation.

impl<S: CoordinateScale, F> Sub for Time<S, F>

where F: InfallibleFormatForScale<S>, F::Unit: TimeUnit,

type Output = Quantity<<F as TimeFormat>::Unit>

The resulting type after applying the - operator.

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

Performs the - operation.

impl<S: CoordinateScale, F, U> SubAssign<Quantity<U>> for Time<S, F>

where F: InfallibleFormatForScale<S>, U: TimeUnit,

fn sub_assign(&mut self, rhs: Quantity<U>)

Performs the -= operation.

impl TimeInstant for Time<TT>

type Duration = Quantity<Second>

Duration type produced by subtracting two instants.

fn difference(&self, other: &Self) -> Second

Signed duration from other to self (self − other).

fn add_duration(&self, dur: Second) -> Self

Shift this instant forward by duration.

impl<S: CoordinateScale, F> UpperExp for Time<S, F>

where F: InfallibleFormatForScale<S>, Quantity<F::Unit>: UpperExp,

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

Formats the value using the given formatter.

impl<S: Scale, F: TimeFormat> Copy for Time<S, F>