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, macros::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

Macros for easy unit conversion and Dt construction.

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.

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_sec_f

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

from_ymd

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

ms

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

ns

Converts whole nanoseconds (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

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