deep-time

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

Overview

• Auto-parsers for datetimes and durations that handle thousands of formats, relative dates and multiple languages, requires the parse feature
• No std, no alloc, and wide-spread const fn
• Extensively validated against outputs from Astropy, Jiff, and other libraries and sources
• Fast ISO parser
• Time scales e.g. UTC with leap seconds support, including historical, TT, TAI, TDB, NAIF ET, LTC, GPS, etc. An optional feature tdb-hi can be enabled which provides the ERFA TDB model
• Strptime
• Strftime (multi-language day and month names available)
• First class timezone support provided by the Rust library jiff enabled with the jiff-tz feature
• To and from all kinds of inputs and outputs, functions mostly prefixed with to and from, available on the library's types, see the main time types functions: Dt. Including JD, MJD, Unix, NTP, etc.
• Calendar aware and, with the jiff-tz feature, timezone aware math
• To and from jiff, chrono, hifitime, time, and ICU4X types
• No-alloc string return type
• Const fn libm math functions
• Safe, saturating arithmetic throughout
• No unsafe in the library - #![forbid(unsafe_code)]
• Lunar and Mars modules
• Sidereal time with a const fn implementation of ERFA Equation of the Origins / Equinoxes
• UT1 and EOP
• Proper time along trajectories — usage guide docs/trajectory.md. Requires the physics feature
• Relativity types: Drift, Spacetime, Position, Velocity — rate-model theory docs/relativity.md. Import via deep_time::physics. Requires the physics feature.
• CCSDS CUC, CDS, and CCS
• Binary size is mainly controlled through feature gating

Examples

use deep_time::macros::{from_ns, from_ymd};
use deep_time::{BufStr, Dt, DtErr, Lang, ParseCfg, Scale, YmdHms};

fn main() -> Result<(), DtErr> {
    // ============================================
    // Parsing
    // ============================================

    // Smart auto-parsing (multi-language + timezone)
    let cfg = ParseCfg {
        lang: Lang::Fr,
        ..Default::default()
    };
    let dt = Dt::from_str_parse("15 août 2024 à 14:30 [Europe/Paris]", &cfg)?;
    let s = dt.to_str_rfc9557("Europe/Paris")?;
    assert_eq!("2024-08-15T14:30:00+02:00[Europe/Paris]", s);

    // or with .parse
    let dt: Dt = "1 jan 2000 07:00 [America/New_York] TAI".parse()?; // noon
    assert_eq!(Dt::ZERO, dt);

    // Relative dates are also supported
    let ref_time = from_ymd!(2026, 6, 16; 12, on=Scale::UTC);
    let en_cfg = ParseCfg {
        ref_time: Some(ref_time),
        ..Default::default()
    };

    // from_ymd! macro defaults to Scale::UTC
    let dt = Dt::from_str_parse("2 days from now at 9am", &en_cfg)?;
    assert_eq!(dt, from_ymd!(2026, 6, 18; 9));

    let dt = Dt::from_str_parse("next Monday at 14:00", &en_cfg)?;
    assert_eq!(dt, from_ymd!(2026, 6, 22; 14));

    // Relative dates use Dt::now if the `std` feature is enabled and no
    // ref_time is provided in the ParseCfg
    let _ = Dt::from_str_parse("next Monday at 14:00", &ParseCfg::DEFAULT)?;

    // Fast ISO parsing with time scale and no alloc output
    let dt = Dt::from_str_iso("2000-01-01T12:00:00 TAI")?;
    let buf_str: BufStr<512> = dt.to_str_b_iso8601();
    assert_eq!("2000-01-01T12:00:00+00:00", buf_str.as_str());

    // ============================================
    // Formatting
    // ============================================

    let s = dt.to_str_in_tz("%A, %d %B %Y %I:%M%P", "America/New_York", Lang::En)?;
    assert_eq!("Saturday, 01 January 2000 07:00am", s);

    let s = dt.to_str_in_tz("%A, %-d de %B de %Y %H:%M", "America/New_York", Lang::Es)?;
    assert_eq!("Sábado, 1 de enero de 2000 07:00", s);

    // ============================================
    // Duration parsing
    // ============================================

    let span: Dt = Dt::from_str_duration("3 days 12 hours", Lang::En)?;
    let dur = span.to_str_b_media_duration();
    assert_eq!("3:12:00:00", dur.to_string());

    // ============================================
    // Time scale conversions + round-tripping
    // ============================================

    let dt = Dt::from_ymd(2000, 1, 1, Scale::TAI, 0, 0, 0, 123456789);
    let tt = dt.to(Scale::TT);
    let tdb = tt.to(Scale::TDB);
    let ltc = tdb.to(Scale::LTC);
    let utc = ltc.to(Scale::UTC);
    let tcl = utc.to(Scale::TCL);
    let tcg = tcl.to(Scale::TCG);
    let tai = tcg.to_tai();

    // round trips work for pretty much everything except UTCHist
    assert_eq!(dt, tai);
    let ymd: YmdHms = tai.to_ymd();
    assert_eq!(ymd.attos(), 123456789);

    // ============================================
    // Other conversions
    // ============================================

    // unix
    let dt = from_ymd!(1970);
    let unix = dt.to_unix().to_sec_f();
    assert_eq!(unix, 0.0);

    let dt = Dt::from_unix(from_ns!(0, on = Scale::UTC));
    assert_eq!(dt, Dt::UNIX_EPOCH);

    // or to milliseconds
    let unix: i128 = dt.add_ms(1000).to_unix().to_ms().0;
    assert_eq!(unix, 1000);

    // to and from jd
    let jd = Dt::ZERO.to_jd_f_raw();
    assert_eq!(2451545.0, jd);
    let dt = Dt::from_jd_f(jd, Scale::TAI);
    assert_eq!(0, dt.attos);

    // ============================================
    // Calendar math
    // ============================================

    // calendar math and negative year
    let dt = from_ymd!(-2000, 1, 31; 12, on=Scale::TAI);
    let ymd = dt.add_months(1).to_ymd();
    assert_eq!(ymd.day(), 29);

    // Timezone-aware calendar math (respects DST transitions, requires jiff-tz feature)
    let dt = Dt::from_str_iso("2025-03-30T00:30:00Z")?; // Just before London DST start

    // Normal (naive) addition — ignores DST rules
    let normal = dt.add_hours(1);

    // Timezone-aware addition — correctly handles the transition
    let aware = dt.add_hours_tz(1, "Europe/London")?;

    assert_eq!(
        normal.to_str_rfc9557("Europe/London")?,
        "2025-03-30T02:30:00+01:00[Europe/London]"
    );
    assert_eq!(
        aware.to_str_rfc9557("Europe/London")?,
        "2025-03-30T03:30:00+01:00[Europe/London]"
    );

    // ============================================
    // Leap seconds
    // ============================================

    // genuine leap second input round trips
    let dt: Dt = "2015-06-30T23:59:60".parse()?;
    let s = dt.to_str_iso8601();
    assert_eq!("2015-06-30T23:59:60+00:00", s);

    Ok(())
}

Documentation

• Library's main documentation page
• Changelog
• The main time type
• Time scales

Installation

• 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"

Feature Flags

Optional No-Alloc Panic Handler

deep-time supports no_std + no_alloc environments. When targeting bare-metal or embedded systems, you can enable a minimal panic handler:

[dependencies]
deep-time = { version = "0.1", features = ["panic-handler"] }

This provides a simple #[panic_handler] that uses core::hint::spin_loop() (more power-efficient than a plain loop {}).

You only need this if you are building a binary crate in a no_std environment without your own panic handler.

Notes

• The fast ISO 8601 parser (from_str_iso) works without the parse feature.
• Multi-language parsing requires the parse feature, but multi-language formatting works without it.
• The .parse() implementation on Dt automatically chooses between the full parser and the ISO parser depending on enabled features.

Additional Examples

Performance

Benchmarks were measured on an AMD Ryzen 7 7800X3D using:

cargo bench --bench perf --features "parse hifitime std jiff-tz"

Parsing and Formatting

Time Scale Conversions

Bundled Files

This library bundles some data relevant to, for example, time scale conversions. While every effort will be made to keep the library up to date, perhaps some users will want to know how to re-generate or update certain files and then re-compile.

Leap Seconds

The latest leap seconds table is bundled as a .rs file. A runtime file can be parsed and loaded for time scale conversions, e.g.

• Dt::leap_sec_list_from_file
• Dt::to_utc_from_tai_using_list
• Dt::to_tai_from_utc_using_list

If for whatever reason you need to update the library's bundled leap seconds file and re-compile, follow these steps:

1. Download the desired leap seconds file, for example from https://data.iana.org/time-zones/data/leap-seconds.list
2. Place the downloaded file in the library, with the following location and filename: deep-time/tests/assets/leap-seconds.list.txt
3. Then with a terminal open in the library run the command: cargo gen-leap-seconds
4. This should overwrite the file src/utc/leap_seconds_list.rs using the data
5. Re-compile the library

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.