Crate attotime 

attotime: Accurate, flexible, and efficient time keeping

attotime is a Rust library for accurate, flexible, and efficient timekeeping, designed for applications where precision and performance are critical.

• Accurate: Supports exact arithmetic with attosecond-level precision over extensive time ranges, without sacrificing correctness or performance.
• Efficient: Represents time values as tick counts since an epoch, enabling compact storage and fast processing without conversion overhead.
• Verified: Key correctness properties have been formally proven using the Kani model checker, ensuring a high degree of reliability.
• Portable: The core functionality of the attotime library is no_std, such that it may be used even in bare metal environments.

With this fine degree of control and precision, attotime is suitable for all types of applications, from nanoseconds in embedded systems to femtoseconds in scientific computing, or picoseconds for precise orbit determination.

Getting started

attotime requires the cargo build system for the Rust programming language to be present on your system. The library may be added as dependency for your Rust project by running cargo add attotime. Afterwards, it may be used directly by importing attotime into your Rust source code.

Expressing time points

In attotime, time points are always bound to a specific timekeeping standard, indicated as TimeScale. One such example is Coordinated Universal Time (UTC). Time points may be constructed directly from some given datetime in the historic calendar:

use attotime::{UtcTime, Month};
let epoch = UtcTime::from_historic_datetime(2025, Month::August, 3, 20, 25, 42).unwrap();

Note that constructing time points from datetimes may fail, because the given arguments do not form a valid time-of-day, or because the given date did not occur in the historic calendar: attotime makes this explicit. Users must acknowledge this possibility by unwrapping the returned Result before being able to use the created UtcTime.

A wide variety of time scales may be encountered in the context of precise timekeeping. attotime provides implementations for the most prevalent time scales: UTC, TAI, terrestrial time (TT), GPS time (GPST), and most other GNSS time scales. Unix time is explicitly not included, as it is not a continuous time scale: the difference between two Unix times does not reflect the physically elapsed time, because leap seconds are not accounted for. Where possible, times can be converted between time scales using the into_time_scale() function, or the equivalent into_<scale>() functions.

use attotime::{GalileoTime, GpsTime, TaiTime, UtcTime, Month, IntoTimeScale, Second};
let epoch_utc = UtcTime::from_historic_datetime(2025, Month::August, 3, 20, 25, 42).unwrap();
let epoch_tai = TaiTime::from_historic_datetime(2025, Month::August, 3, 20, 26, 19).unwrap();
let epoch_gps = GpsTime::from_historic_datetime(2025, Month::August, 3, 20, 26, 0).unwrap();
let epoch_galileo = GalileoTime::from_historic_datetime(2025, Month::August, 3, 20, 26, 0).unwrap();
assert_eq!(epoch_utc.into_time_scale(), epoch_tai);
assert_eq!(epoch_utc.into_gpst(), epoch_gps);
assert_eq!(epoch_utc.into_gst(), epoch_galileo);

If a desired time scale is not present, users may provide their own by implementing the TimeScale trait. To support calendrical functionality, it is additionally necessary to implement the AbsoluteTimeScale trait.

There is also support for subsecond datetime values:

use attotime::{UtcTime, TtTime, Month, Duration};
let epoch_utc = UtcTime::from_historic_datetime(2025, Month::August, 3, 20, 25, 42).unwrap();
let epoch_tt = TtTime::from_fine_historic_datetime(2025, Month::August, 3, 20, 26, 51, Duration::milliseconds(184)).unwrap();
assert_eq!(epoch_utc.into_tt(), epoch_tt);

Expressing durations

Within attotime, the difference between two TimePoints is expressed as a Duration:

use attotime::{UtcTime, Month, Duration};
let epoch1 = UtcTime::from_historic_datetime(2020, Month::September, 30, 23, 59, 58).unwrap();
let epoch2 = UtcTime::from_historic_datetime(2020, Month::October, 1, 0, 2, 3).unwrap();
let duration = epoch2 - epoch1;
assert_eq!(duration, Duration::seconds(125));

Leap second boundaries are handled seamlessly:

use attotime::{UtcTime, Month, Duration};
let epoch1 = UtcTime::from_historic_datetime(2016, Month::December, 31, 23, 59, 59).unwrap();
let epoch2 = UtcTime::from_historic_datetime(2016, Month::December, 31, 23, 59, 60).unwrap();
let epoch3 = UtcTime::from_historic_datetime(2017, Month::January, 1, 0, 0, 0).unwrap();
assert_eq!(epoch2 - epoch1, Duration::seconds(1));
assert_eq!(epoch3 - epoch2, Duration::seconds(1));
assert_eq!(epoch3 - epoch1, Duration::seconds(2));

The same goes when a time scale does not apply leap seconds:

use attotime::{TaiTime, Month, Duration};
let epoch1 = TaiTime::from_historic_datetime(2016, Month::December, 31, 23, 59, 59).unwrap();
let _ = TaiTime::from_historic_datetime(2016, Month::December, 31, 23, 59, 60).unwrap_err();
let epoch3 = TaiTime::from_historic_datetime(2017, Month::January, 1, 0, 0, 0).unwrap();
assert_eq!(epoch3 - epoch1, Duration::seconds(1));

As with TimePoints, unit compatibility is checked at compile time, with conversions permit using the into_unit() method:

use attotime::{GpsTime, Month, Duration};
let epoch1 = GpsTime::from_historic_datetime(2024, Month::August, 13, 19, 30, 0).unwrap();
let epoch2 = epoch1 + Duration::hours(2);
let epoch3 = epoch1 + Duration::milliseconds(1);
assert_eq!(epoch2, GpsTime::from_historic_datetime(2024, Month::August, 13, 21, 30, 0).unwrap());
assert_eq!(epoch3, GpsTime::from_fine_historic_datetime(2024, Month::August, 13, 19, 30, 0, Duration::milliseconds(1)).unwrap());

Comparison with hifitime, chrono, time, jiff, and finetime.

There are a multitude of high-quality Rust timekeeping crates out there already. In particular, chrono, time, jiff, and hifitime will already cover most people’s use cases. Most users will be interested in jiff, chrono and time, which are highly suitable for day-to-day timekeeping. They handle civilian time zones (which attotime does not) and integrate much better with the operating system: however, they do not permit high-accuracy timestamps in frequently-used scientific and engineering time scales, like GPS, TAI, and TT. This makes them unsuitable for astrodynamics, physics, and engineering. For users that are not interested in such niche applications and time scales, any of jiff, chrono, and time will certainly handle your needs: attotime might as well, but is certainly not the only option.

On the other hand, hifitime does handle such specialist time scales (although, in turn, it does not cover civilian time scales beyond UTC). Additionally, hifitime supports nanosecond precision and is validated against the timekeeping part of the SPICE astrodynamics library. Yet, hifitime’s Epoch type is limited to nanosecond precision and uses a segmented time type that dynamically stores the underlying time standard used. This introduces quite some complexity in what could be a simple tick counting type. This complexity definitely does not affect its correctness at all: hifitime is well-validated. However, it does affect the efficiency of the time representation used: Epoch always consists of at least an 80-bit Duration (on most systems, resulting in a 128-bit effective size) and an at minimum 8-bit TimeScale. Additionally, this means that the Epoch type cannot easily be extended to admit subnanosecond accuracy: in some GNSS applications, such accuracy is becoming necessary.

attotime is meant to address these concerns: it efficiently stores the underlying time stamp as a simple tick count. This means that all arithmetic on time stamps reduces to simple arithmetic directly on the underlying tick count: as efficient as it would be when written by hand. Additionally, the attotime TimePoint type is generic over the time scale used. Conversion routines are written to support convenient and zero-overhead casting to other TimePoint times, where they are compatible. Consequently, attotime is suitable for subnanosecond applications as well as for scenarios where a wide time range.

Finally, attotime is a successor to the finetime library (by the same author), which addresses the same concerns. Additionally, finetime is generic over the underlying tick count representation: indeed, it is more flexible than attotime. However, this flexibility does come at an implementation and usability cost: for the general case - even in specialist applications. When attosecond accuracy over a lifetime-of-the-universe time range with a 128-bit representation is fine, attotime is useful and provides more quality-of-life functionality.

Modules

errors

All errors that may be returned by public functions of this library are defined in this module. This is useful in reducing the number of “unnecessary” inter-module dependencies, by ensuring that using the results/error of a function does not require importing its entire module.

Structs

Bdt

Time scale representing the BeiDou Time (BDT). BDT has no leap seconds and increases monotonically at a constant rate. It is distributed as part of the BeiDou broadcast messages, making it useful in a variety of high-accuracy situations.

Date

Generic representation of date. Identifies an exact individual date within the calendar, in terms of days before (negative) or after (positive) 1970-01-01. This makes it useful as universal type that can be converted to and from other calendrical types.

Days

Representation of a duration to an accuracy of Days. Useful whenever some duration is known or needs to be known only to an accuracy of one day - for example, in calendrical computations.

Duration

A Duration represents the difference between two time points. It has an associated Representation, which determines how the count of elapsed ticks is stored. The Period determines the integer (!) ratio of each tick to seconds. This may be used to convert between Durations of differing time units.

FractionalDigitsIterator

Wrapper struct that implements FractionalDigits for all integers.

Glonasst

The GLONASS Time (GLONASST) time scale is broadcast by GLONASS satellites. It follows UTC (or rather, UTC(SU), which is a realization of UTC) and adds three hours (Moscow time). Indeed, this means that it also incorporates leap seconds.

Gpst

Time scale representing the Global Positioning System Time (GPST). GPST has no leap seconds and increases monotonically at a constant rate. It is distributed as part of the GPS broadcast messages, making it useful in a variety of high-accuracy situations.

GregorianDate

Representation of a proleptic Gregorian date. Only represents logic down to single-day accuracy: i.e., leap days are included, but leap seconds are not. This is useful in keeping this calendar applicable to all different time scales. Can represent years from -2^31 up to 2^31 - 1.

Gst

Time scale representing the Galileo System Time (GST). GST has no leap seconds and increases monotonically at a constant rate. It is distributed as part of the Galileo broadcast messages, making it useful in a variety of high-accuracy situations.

HistoricDate

Implementation of a date in the historic calendar. After 15 October 1582, this coincides with the Gregorian calendar; until 4 October 1582, this is the Julian calendar. The days inbetween do not exist.

JulianDate

Representation of a proleptic Julian date. Only represents logic down to single-day accuracy: i.e., leap days are included, but leap seconds are not. This is useful in keeping this calendar applicable to all different time scales. Can represent years from -2^31 up to 2^31 - 1.

ModifiedJulianDate

The Modified Julian Day (MJD) representation of any given date.

Qzsst

Time scale representing the Quasi-Zenith Satellite System Time (QZSST). QZSST has no leap seconds and increases monotonically at a constant rate. It is distributed as part of the QZSST broadcast messages, making it useful in a variety of high-accuracy situations.

StaticLeapSecondProvider

Default leap second provider that uses a pre-compiled table to obtain the leap seconds. Will suffice for most non-critical applications and is useful in testing, but cannot be updated after compilation. This makes it unsuitable for long-running applications.

Tai

Time scale representing the International Atomic Time standard (TAI). TAI has no leap seconds and increases monotonically at a constant rate. This makes it highly suitable for scientific and high-accuracy timekeeping.

Tcb

Time scale representing the Barycentric Coordinate Time (TCB). This scale is equivalent to the proper time as experienced by an (idealistic) clock outside of Sun’s gravity well, but co-moving with the SSB. The resulting proper time is useful as independent variable for high-accuracy ephemerides for Solar system objects, and as intermediate variable when transforming into barycentric dynamical time.

Tcg

Time scale representing the Geocentric Coordinate Time (TCG). This scale is equivalent to the proper time as experienced by an (idealistic) clock outside of Earth’s gravity well, but co-moving with the Earth. The resulting proper time is useful as independent variable for high-accuracy ephemerides for Earth satellites, and as intermediate variable when transforming into barycentric coordinate time.

Tdb

Time scale representing the Barycentric Dynamical Time (TDB). This scale is equivalent to the proper time as experienced by an (idealistic) clock located at and co-moving with the SSB. The resulting proper time is useful as independent variable for high-accuracy ephemerides for Solar system objects.

TimePoint

A TimePoint identifies a specific instant in time. It is templated on a Representation and Period, which the define the characteristics of the Duration type used to represent the time elapsed since the epoch of the underlying time scale Scale.

Tt

Time scale representing the Terrestrial Time (TT) scale. This scale is a constant 32.184 seconds ahead of TAI, but otherwise completely synchronized. It is used primarily as independent variable in the context of planetary ephemerides.

Utc

Time scale representing Coordinated Universal Time (UTC). This scale is adjusted using leap seconds to closely match the rotation of the Earth. This makes it useful as civil time scale, but also means that external, discontinuous synchronization is required.

Enums

DurationDesignator

The set of duration symbols that are supported when expressing durations as strings.

LiteralRatio

Unit that is described as an exact ratio with respect to unity.

Month

Representation of a month in a Roman calendar.

WeekDay

Indication of a specific day-of-the-week. While explicit values are assigned to each day (to make implementation easier), no ordering is implied.

Constants

STATIC_LEAP_SECOND_PROVIDER

Convenience constant that may be used to directly obtain a StaticLeapSecondProvider object.

Traits

AbsoluteTimeScale

TimeScale that is fixed in calendrical time by an absolute epoch. Note that this does not yet unambiguously define the scale: for that, it must be linked to a well-defined scale like TAI or UTC (for example, by implementing the TerrestrialTime trait).

FromDateTime

This trait may be implemented for time points that can be constructed based on a date-time pair: they can connect a date and time-of-day to a specific time instant within their internal scale and vice versa.

FromFineDateTime

This trait may be implemented for time points that can be created based on “fine” date-time pairs, which have subsecond accuracy.

FromLeapSecondDateTime

This trait is the leap second equivalent of FromDateTime. It permits the creation of time points from date-times when a non-standard leap second provider must be used.

FromTimeScale

Trait representing the ability to convert from one scale into another. Note that this conversion must always succeed: barring arithmetic overflows (on which panics are advised), it must always be possible to relate the time of two scales.

IntoDateTime

This trait represents the fact that some time instant may be mapped back to the date-time pair that it corresponds with, at an accuracy of seconds.

IntoFineDateTime

IntoLeapSecondDateTime

This trait is the leap second equivalent of IntoDateTime. It permits the retrieval of date-times from time points when a non-standard leap second provider must be used.

IntoTimeScale

Trait representing the ability to convert from one scale into another. Note that this conversion must always succeed: barring arithmetic overflows (on which panics are advised), it must always be possible to relate the time of two scales.

LeapSecondProvider

Since leap seconds are hard to predict in advance (due to irregular variations in the Earth’s rotation), their insertion and deletion is based on short-term predictions. This means that it is not possible to develop a leap second table that holds “for all eternity” without external influence. Different applications may have different manners of obtaining these updates from external sources - if at all possible. To accommodate all such applications, we support a generic manner of introducing leap seconds, via the LeapSecondProvider interface.

TerrestrialTime

In general, “terrestrial time” refers not just to the specific realization TT, but to an idealized clock on the Earth geoid. It turns out that a lot of time scales are simply a variant on terrestrial time (or, equivalently, TAI). All these time scales may easily be converted into one another through a simple epoch offset: their internal clock rates are identical.

TimeScale

A TimeScale identifies the relativistic time scale in which some TimePoint is expressed.

UniformDateTimeScale

Some time scales are uniform with respect to date-times: they do not apply leap seconds. In such cases, their implementation of the DateTime mapping reduces to a simple add-and-multiply of days, hours, minutes, and seconds with respect to the “arbitrary” measurement epoch in which their resulting time points are measured.

UnitRatio

Trait representing the fact that something is a unit ratio.

Type Aliases

Atto

BeiDouTime

Femto

GalileoTime

GlonassTime

GlonassTime is a time point that is expressed according to the GLONASS Time time scale.

GpsTime

Micro

Milli

Nano

Pico

QzssTime

Second

SecondsPerDay

SecondsPerHour

SecondsPerMinute

SecondsPerMonth

The number of seconds in 1/12 the average Gregorian year.

SecondsPerWeek

SecondsPerYear

The number of seconds in an average Gregorian year.

TaiTime

TcbTime

TcgTime

TdbTime

TtTime

UtcTime