Crate deep_time 

deep-time

A fully featured, high performance, no_std and no alloc Rust date and time library with attosecond precision that provides astronomical and civil timekeeping.

Functionality: https://github.com/ragardner/deep-time#overview

Readme example: https://github.com/ragardner/deep-time#examples

Additional examples: https://github.com/ragardner/deep-time#additional-examples

The library’s central time type is Dt, a 32 byte struct that holds:

• An i128 attoseconds count
• A scale Scale field for its current time scale
• A target Scale field for the time scale the object came from, and/or which time scale it should be converted to in various output functions.

Dt can act as an instant or duration.

While Dt can hold attoseconds counts from any epoch (start time), the library’s epoch for most functionality is 2000-01-01 noon on the TAI time scale.

use deep_time::{Dt, Scale, from_ymd};

let dt = from_ymd!(2000, 1, 1; 12, on=Scale::TAI);
assert_eq!(dt, Dt::ZERO);

let dt = Dt::from_str_iso("2000-01-01 12:00 TAI").unwrap();
assert_eq!(dt, Dt::ZERO);

Dt handles massive datetimes and always with attosecond resolution:

use deep_time::{Dt, Lang, Scale, from_ymd};

let mut dt = Dt::from_str_iso("292000000000-1-1").unwrap();
dt = dt.add_days(4);
let s = dt.to_str_lite("%Y-%m-%dT%H:%M:%S %L", Lang::En).unwrap();

assert_eq!(s.as_str(), "292000000000-01-05T00:00:00 UTC");

// negatives too
let dt = from_ymd!(-5000, 1, 1; 18, on=Scale::TAI);
assert_eq!(dt, Dt::parse("-5000-01-01T18:00:00 TAI").unwrap());

assert_eq!(dt.to_jd_f(), -105151.75);
assert_eq!(dt.to_mjd_f(), -2505152.25);

Once you have a Dt you can change its time scale:

use deep_time::{Dt, Scale, from_jd_f};

let dt = from_jd_f!(2451545.0);
assert_eq!(dt.scale, Scale::TAI);

// leap seconds have been subtracted when going from TAI -> UTC
let utc = dt.to(Scale::UTC);
assert_eq!(utc.to_sec_f(), -32.0);

This crate has no default features.

The minimum Rust version is 1.90 and minimum Rust edition is 2024.

This is mainly due to some const functionality that only became stable recently.

To add deep-time to your Rust project with the parse and timezone features, go to your project folder and run this terminal command:

cargo add deep-time --features "parse,jiff-tz"

List of features you can enable: https://github.com/ragardner/deep-time#feature-flags

Modules

civil_parts

Intermediate “parts” of a civil date and time.

consts

Fundamental constants for time-scale conversions, relativistic corrections, and astronomical calculations.

eop

Earth Orientation Parameters (EOP) data parser and interpolator.

lunar

Lunar time-scale constants and conversion methods.

macros

Convenience macros

mars

Mars time-scale constants and conversion methods (MSD, MTC, Ls, LMST, LTST, Mars Year).

math

Tested, const fn versions of libm float math functions. e.g. use deep_time::math::sin;

sidereal

Sidereal rotation and time calculations for celestial bodies.

tdb_hi

TDB−TT using the full ERFA model (Fairhead & Bretagnon 1990).

tz

Time zone name helpers.

utc

UTC time-scale data and TAI−UTC conversion tables.

Macros

an_err

Ergonomic constructor and chaining macro for AnErr.

as_days

Converts total attoseconds (i128) → whole days (i128).

as_days_f

Converts total attoseconds (i128) → floating-point days (Real).

as_fs

Converts total attoseconds (i128) → whole femtoseconds (i128).

as_hrs

Converts total attoseconds (i128) → whole hours (i128).

as_mins

Converts total attoseconds (i128) → whole minutes (i128).

as_ms

Converts total attoseconds (i128) → whole milliseconds (i128).

as_ns

Converts total attoseconds (i128) → whole nanoseconds (i128).

as_ps

Converts total attoseconds (i128) → whole picoseconds (i128).

as_sec

Converts total attoseconds (i128) → whole seconds (i128).

as_sec_f

Converts total attoseconds (i128) → float seconds (Real).

as_us

Converts total attoseconds (i128) → whole microseconds (i128).

as_wks

Converts total attoseconds (i128) → whole weeks (i128).

days

Converts whole days (i128) to total attoseconds (i128).

days_f

Converts a floating-point day count (Real) to total attoseconds (i128).

dt

Builds a Dt from total attoseconds with optional scale labels.

f

Convert a number to the crates Real type (f64).

from_days_f

Builds a Dt from a floating-point day count with optional scale labels.

from_fs

Builds a Dt from whole femtoseconds and an optional signed fractional remainder in attoseconds.

from_jd

Builds a TAI Dt from a Julian Date (whole days plus optional attosecond remainder).

from_jd_f

Builds a TAI Dt from a floating-point Julian Date.

from_mjd

Builds a TAI Dt from a Modified Julian Date (whole days plus optional attosecond remainder).

from_mjd_f

Builds a TAI Dt from a floating-point Modified Julian Date.

from_ms

Builds a Dt from whole milliseconds and an optional signed fractional remainder in attoseconds.

from_ns

Builds a Dt from whole nanoseconds and an optional signed fractional remainder in attoseconds.

from_ps

Builds a Dt from whole picoseconds and an optional signed fractional remainder in attoseconds.

from_sec

Builds a Dt from whole seconds and an optional signed sub-second remainder (attoseconds).

from_sec_f

Builds a Dt from a floating-point seconds count with optional scale labels.

from_us

Builds a Dt from whole microseconds and an optional signed fractional remainder in attoseconds.

from_ymd

Builds a Dt from a Gregorian calendar date and optional time.

fs

Converts whole femtoseconds (i128) to total attoseconds (i128).

hrs

Converts whole hours (i128) to total attoseconds (i128).

mins

Converts whole minutes (i128) to total attoseconds (i128).

ms

Converts whole milliseconds (i128) to total attoseconds (i128).

ns

Converts whole nanoseconds (i128) to total attoseconds (i128).

ps

Converts whole picoseconds (i128) to total attoseconds (i128).

sec

Converts whole seconds (i128) to total attoseconds (i128).

sec_f

Converts a floating-point second count (Real) to total attoseconds (i128).

us

Converts whole microseconds (i128) to total attoseconds (i128).

wks

Converts whole weeks (i128) to total attoseconds (i128).

Structs

AnErr

A compact, zero-allocation error type consisting of a single error kind and a human-readable reason string.

Drift

Quadratic polynomial that describes the accumulated difference between an observer’s proper time (the time measured by a real clock moving through spacetime) and a chosen coordinate time such as TT, TAI, or any other Scale.

Dt

The library’s central time type. A high-precision instant/duration with attosecond resolution.

Every

Builder type that enables the ergonomic start.every(step) syntax.

LiteStr

A fixed-capacity, stack-allocated buffer that can hold a UTF-8 string.

Observer

Snapshot of one observer’s state at a single instant: time, position, velocity, and local gravity.

ParseCfg

Configuration options for Dt::from_str_parse.

Position

A 3-dimensional position vector expressed in Cartesian coordinates (x, y, z) with units of meters (SI).

Spacetime

Snapshot of the local quantities that set a clock’s rate (d\tau/dt).

StrPTimeFmt

A pre-validated, reusable date/time format string.

TimeRange

An iterator over evenly spaced Dt values.

Velocity

A 3-dimensional velocity vector expressed in Cartesian coordinates (vx, vy, vz) with units of meters per second (SI).

YmdHms

Combined date + time object.

Enums

DtErrKind

Failure category inside DtErr — parse errors, out-of-range values, missing features, and similar cases.

Lang

Language codes following ISO 639-1 standard (two-letter codes). Default is En (English)

Mode

Used by ParseCfg in Dt::from_str_parse. Controls how purely numeric dates are parsed.

Order

Used by ParseCfg in Dt::from_str_parse. Controls how ambiguous dates (e.g. 01/02/03) are parsed.

Scale

Time scales supported by the library.

Traits

TraitsAttos

Trait that adds ergonomic attosecond conversions on integer values.

TraitsTime

Trait that adds ergonomic time-unit methods to integers and floats.

Type Aliases

DtErr

Wrapper around AnErr.

Real

Alias for f64, maybe upgrade one day