Struct tai_time::TaiTime

pub struct TaiTime<const EPOCH_REF: i64> { /* private fields */ }

Nanosecond-precision monotonic clock timestamp parametrized by its epoch.

A timestamp specifies a TAI point in time. It is represented as a 64-bit signed number of seconds and a positive number of nanoseconds, counted with reference to the epoch specified by the generic parameter.

EPOCH_REF defines the epoch via its signed distance in seconds from 1970-01-01 00:00:00 TAI.

See also: MonotonicTime, GpsTime, GstTime, BdtTime, Tai1958Time and Tai1972Time.

Examples

use std::time::Duration;
use tai_time::TaiTime;

// A timestamp type with an epoch at 1970:01:01 00:02:03 TAI.
type MyCustomTime = TaiTime<123>;

// A timestamp set to 2009-02-13 23:33:33.333333333 TAI.
let mut timestamp = MyCustomTime::new(1_234_567_890, 333_333_333);

// Increment the timestamp by 123.456s.
timestamp += Duration::new(123, 456_000_000);

assert_eq!(timestamp, MyCustomTime::new(1_234_568_013, 789_333_333));
assert_eq!(timestamp.as_secs(), 1_234_568_013);
assert_eq!(timestamp.subsec_nanos(), 789_333_333);

Implementations

impl<const EPOCH_REF: i64> TaiTime<EPOCH_REF>

pub const EPOCH: Self = _

The reference epoch, which by definition is always a null timestamp.

pub const MIN: Self = _

The minimum possible TaiTime timestamp.

pub const MAX: Self = _

The maximum possible TaiTime timestamp.

pub const fn new(secs: i64, subsec_nanos: u32) -> Self

Creates a timestamp from its parts.

The number of seconds is relative to the epoch. The number of nanoseconds is always positive and always points towards the future.

Panics

This constructor will panic if the number of nanoseconds is greater than or equal to 1 second.

Example

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use std::time::Duration;
use tai_time::MonotonicTime;

// A timestamp set to 2009-02-13 23:31:30.987654321 TAI.
let timestamp = MonotonicTime::new(1_234_567_890, 987_654_321);

// A timestamp set 0.5s in the past of the epoch.
let timestamp = MonotonicTime::new(-1, 500_000_000);
assert_eq!(timestamp, MonotonicTime::EPOCH - Duration::from_millis(500));

pub fn now() -> Self

Available on crate feature tai_clock and Linux only.

Creates a timestamp from the TAI system clock.

This is currently only supported on Linux and relies on the clock_gettime system call with a CLOCK_TAI clock ID.

The use of the Linux TAI clock is subject to several caveats, most importantly:

1. on many default-configured Linux systems, the offset between TAI and UTC is arbitrarily set to 0 at boot time, in which case the TAI system clock will actually only differ from UTC time by the number of leap seconds introduced after the system was booted (most likely, 0),
2. some systems are configured to perform leap second smearing by altering the rate of the system clock over a 24h period so as to avoid the leap second discontinuity; this entirely defeats the purpose of the TAI clock which becomes effectively synchronized to the (leap-smeared) UTC system clock.

The first issue can be easily remedied, however, by using chrony and, if necessary, making sure that the leapsectz parameter in chrony.conf is set to right/UTC. Alternatively, one can specify the leapfile path in ntp.conf or set the TAI offset directly with a call to adjtimex or ntp_adjtime.

Panics

While highly improbable, this method will panic on arithmetic overflow. This would require the system clock time or EPOCH_REF to approach i64::MIN or i64::MAX, which corresponds to approximately ±292 billion years.

pub fn now_from_utc(leap_secs: i64) -> Self

Available on crate feature std only.

Creates a timestamp from the UTC system clock.

This is a shorthand for from_system_time(&SystemTime::now(), leap_secs).

The argument is the difference between TAI and UTC time in seconds (a.k.a. leap seconds) applicable at the date represented by the timestamp. For reference, this offset has been +37s since 2017-01-01, a value which is to remain valid until at least 2024-12-28. See the official IERS bulletin C for leap second announcements or the IERS table for current and historical values.

Beware that the behavior of the system clock near a leap second shouldn’t be relied upon, where near might actually stand for the whole 24h period preceding a leap second due to the possible use of the so-called leap second smearing strategy.

See also: from_system_time.

Panics

While highly improbable, this method will panic on arithmetic overflow. This would require the system clock time, the leap_secs argument, or EPOCH_REF to approach i64::MIN or i64::MAX, which corresponds to approximately ±292 billion years.

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use tai_time::MonotonicTime;

// Compute the current timestamp assuming that the current difference
// between TAI and UTC time is 37s.
let timestamp = MonotonicTime::now_from_utc(37);

pub const fn from_date_time( year: i32, month: u8, day: u8, hour: u8, min: u8, sec: u8, nano: u32 ) -> Result<Self, DateTimeError>

Creates a timestamp from a date-time representation.

The first argument is the proleptic Gregorian year. It follows the ISO 8601 interpretation of year 0 as year 1 BC.

Other arguments follow the usual calendar convention, with month and day numerals starting at 1.

Note that the proleptic Gregorian calendar extrapolates dates before 1582 using the conventional leap year rules, and considers year 0 as a leap year. Proleptic Gregorian dates may therefore differ from those of the Julian calendar.

Returns an error if any of the arguments is invalid, or if the calculated timestamp is outside the representable range.

While highly improbable, this method will also return a DateTimeError::OutOfRange error on arithmetic overflow. This would require EPOCH_REF to approach i64::MIN or i64::MAX, which corresponds to approximately ±292 billion years. This cannot happen with any of the pre-defined TaiTime aliases.

Example

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use std::time::Duration;
use tai_time::MonotonicTime;

// A timestamp set to 2009-02-13 23:31:30.987654321 TAI.
let timestamp = MonotonicTime::from_date_time(2009, 2, 13, 23, 31, 30, 987_654_321);
assert_eq!(timestamp, Ok(MonotonicTime::new(1_234_567_890, 987_654_321)));

pub const fn from_unix_timestamp( secs: i64, subsec_nanos: u32, leap_secs: i64 ) -> Self

Creates a TAI timestamp from a Unix timestamp.

The last argument is the difference between TAI and UTC time in seconds (a.k.a. leap seconds) applicable at the date represented by the timestamp. For reference, this offset has been +37s since 2017-01-01, a value which is to remain valid until at least 2024-12-28. See the official IERS bulletin C for leap second announcements or the IERS table for current and historical values.

Note that there is no unanimous consensus regarding the conversion between TAI and Unix timestamps prior to 1972.

Panics

Panics if the number of nanoseconds is greater than or equal to 1 second.

While highly improbable, this method will panic on arithmetic overflow. This would require the unix timestamp, the leap_secs argument or EPOCH_REF to approach i64::MIN or i64::MAX, which corresponds to approximately ±292 billion years.

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use tai_time::MonotonicTime;

// Creates a timestamp corresponding to 2001-09-15 05:05:00.005 UTC,
// accounting for the +32s difference between UAI and UTC on 2001-09-15.
assert_eq!(
    MonotonicTime::from_unix_timestamp(1_000_530_300, 5_000_000, 32),
    MonotonicTime::new(1_000_530_332, 5_000_000)
);

pub fn from_system_time(system_time: &SystemTime, leap_secs: i64) -> Self

Available on crate feature std only.

Creates a TAI timestamp from a SystemTime timestamp.

The last argument is the difference between TAI and UTC time in seconds (a.k.a. leap seconds) applicable at the date represented by the timestamp. For reference, this offset has been +37s since 2017-01-01, a value which is to remain valid until at least 2024-12-28. See the official IERS bulletin C for leap second announcements or the IERS table for current and historical values.

Panics

While highly improbable, this method will panic on arithmetic overflow. This would require the system_time argument, the leap_secs argument, or EPOCH_REF to approach i64::MIN or i64::MAX, which corresponds to approximately ±292 billion years.

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use std::time::{Duration, SystemTime};
use tai_time::MonotonicTime;

// Creates a timestamp corresponding to 2001-09-15 05:05:00.005 UTC,
// accounting for the +32s difference between UAI and UTC on 2001-09-15.
let system_time = SystemTime::UNIX_EPOCH + Duration::new(1_000_530_300, 5_000_000);
assert_eq!(
    MonotonicTime::from_system_time(&system_time, 32),
    MonotonicTime::new(1_000_530_332, 5_000_000)
);

pub const fn from_chrono_date_time<Tz: TimeZone>( date_time: &DateTime<Tz>, leap_secs: i64 ) -> Self

Available on crate feature chrono only.

Creates a timestamp from a chrono::DateTime.

The argument is the difference between TAI and UTC time in seconds (a.k.a. leap seconds) applicable at the date represented by the timestamp. For reference, this offset has been +37s since 2017-01-01, a value which is to remain valid until at least 2024-12-28. See the official IERS bulletin C for leap second announcements or the IERS table for current and historical values.

While no error will be reported, this method should not be considered appropriate for timestamps in the past of 1972.

Panics

While highly improbable, this method will panic on arithmetic overflow. This would require the leap_secs argument or EPOCH_REF to approach i64::MIN or i64::MAX, which corresponds to approximately ±292 billion years.

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use tai_time::MonotonicTime;
use chrono::DateTime;

let tai_date_time: MonotonicTime = "2001-09-15 05:05:32.005".parse().unwrap();
let chrono_date_time = DateTime::parse_from_rfc3339("2001-09-15T05:05:00.005Z").unwrap();

assert_eq!(
    MonotonicTime::from_chrono_date_time(&chrono_date_time, 32),
    tai_date_time
);

pub const fn as_secs(&self) -> i64

Returns the signed value of the closest second boundary that is equal to or lower than the timestamp, relative to the EPOCH.

This value is the same as the one that would be provided to construct the timestamp with new().

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use std::time::Duration;
use tai_time::MonotonicTime;

let timestamp = MonotonicTime::new(1_234_567_890, 987_654_321);
assert_eq!(timestamp.as_secs(), 1_234_567_890);

let timestamp = MonotonicTime::EPOCH - Duration::new(3, 500_000_000);
assert_eq!(timestamp.as_secs(), -4);

pub const fn subsec_nanos(&self) -> u32

Returns the sub-second fractional part in nanoseconds.

Note that nanoseconds always point towards the future even if the date is in the past of the EPOCH.

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use tai_time::MonotonicTime;

let timestamp = MonotonicTime::new(1_234_567_890, 987_654_321);
assert_eq!(timestamp.subsec_nanos(), 987_654_321);

pub const fn to_unix_secs(&self, leap_secs: i64) -> i64

Returns the number of seconds of the corresponding Unix timestamp.

The argument is the difference between TAI and UTC time in seconds (a.k.a. leap seconds) applicable at the date represented by the timestamp. For reference, this offset has been +37s since 2017-01-01, a value which is to remain valid until at least 2024-12-28. See the official IERS bulletin C for leap second announcements or the IERS table for current and historical values.

This method merely subtracts the offset from the value returned by as_secs(); its main purpose is to prevent mistakes regarding the direction in which the offset should be applied.

The nanosecond part of a Unix timestamp can be simply retrieved with subsec_nanos() since UTC and TAI differ by a whole number of seconds since 1972.

Note that there is no unanimous consensus regarding the conversion between TAI and Unix timestamps prior to 1972.

Panics

While highly improbable, this method will panic on arithmetic overflow. This would require the leap_secs argument or EPOCH_REF to approach i64::MIN or i64::MAX, which corresponds to approximately ±292 billion years.

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use tai_time::MonotonicTime;

// Set the date to 2000-01-01 00:00:00 TAI.
let timestamp = MonotonicTime::new(946_684_800, 0);

// Convert to a Unix timestamp, accounting for the +32s difference between
// TAI and UTC on 2000-01-01.
assert_eq!(
    timestamp.to_unix_secs(32),
    946_684_768
);

pub const fn to_tai_time<const OTHER_EPOCH_REF: i64>( &self ) -> TaiTime<OTHER_EPOCH_REF>

Returns a timestamp with a different reference epoch.

Panics

While highly improbable, this method will panic on arithmetic overflow. This would require the original timestamp or EPOCH_REF to approach i64::MIN or i64::MAX, which corresponds to approximately ±292 billion years.

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use tai_time::{GpsTime, MonotonicTime};

// Set the date to 2000-01-01 00:00:00 TAI.
let timestamp = MonotonicTime::new(946_684_800, 0);

// Convert to a GPS timestamp.
let gps_timestamp: GpsTime = timestamp.to_tai_time();
assert_eq!(
    gps_timestamp,
    GpsTime::new(630_719_981, 0)
);

pub fn to_system_time( &self, leap_secs: i64 ) -> Result<SystemTime, OutOfRangeError>

Available on crate feature std only.

Returns a SystemTime based on the timestamp.

The argument is the difference between TAI and UTC time in seconds (a.k.a. leap seconds) applicable at the date represented by the timestamp. For reference, this offset has been +37s since 2017-01-01, a value which is to remain valid until at least 2024-12-28. See the official IERS bulletin C for leap second announcements or the IERS table for current and historical values.

While no error will be reported, this method should not be considered appropriate for timestamps in the past of 1972.

Returns an error if the resulting timestamp predates the Unix epoch (1970-01-01 00:00:00 UTC).

While highly improbable, this method will also return an error on arithmetic overflow. This would require the original timestamp, the leap_secs argument or EPOCH_REF to approach i64::MIN or i64::MAX, which corresponds to approximately ±292 billion years.

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use std::time::{Duration, SystemTime};
use tai_time::MonotonicTime;

// Set the date to 2000-01-01 00:00:00.123 TAI.
let timestamp = MonotonicTime::new(946_684_800, 123_000_000);

// Obtain a `SystemTime`, accounting for the +32s difference between
// TAI and UTC on 2000-01-01.
assert_eq!(
    timestamp.to_system_time(32),
    Ok(SystemTime::UNIX_EPOCH + Duration::new(946_684_768, 123_000_000))
);

pub fn to_chrono_date_time( &self, leap_secs: i64 ) -> Result<DateTime<Utc>, OutOfRangeError>

Available on crate feature chrono only.

Returns a chrono::DateTime based on the timestamp.

The argument is the difference between TAI and UTC time in seconds (a.k.a. leap seconds) applicable at the date represented by the timestamp. For reference, this offset has been +37s since 2017-01-01, a value which is to remain valid until at least 2024-12-28. See the official IERS bulletin C for leap second announcements or the IERS table for current and historical values.

While no error will be reported, this method should not be considered appropriate for timestamps in the past of 1972.

Returns an error if the resulting timestamp cannot be represented by a chrono::DateTime, which may occur if the date predates chrono::NaiveDate::MIN or postdates chrono::NaiveDate::MAX.

While highly improbable, this method will also return an error on arithmetic overflow. This would require the original timestamp, the leap_secs argument or EPOCH_REF to approach i64::MIN or i64::MAX, which corresponds to approximately ±292 billion years.

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use tai_time::MonotonicTime;

// Set the date to 2000-01-01 00:00:00.123 TAI (1999-12-31 23:59:28.123 UTC).
let timestamp = MonotonicTime::new(946_684_800, 123_000_000);

// Obtain a `chrono::DateTime`, accounting for the +32s difference between
// TAI and UTC on 2000-01-01.
let date_time = timestamp.to_chrono_date_time(32).unwrap();
assert_eq!(
    date_time.to_string(),
    "1999-12-31 23:59:28.123 UTC"
);

pub const fn checked_add(self, rhs: Duration) -> Option<Self>

Adds a duration to a timestamp, checking for overflow.

Returns None if overflow occurred.

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use std::time::Duration;
use tai_time::MonotonicTime;

let timestamp = MonotonicTime::new(1_234_567_890, 987_654_321);
assert!(timestamp.checked_add(Duration::new(10, 123_456_789)).is_some());
assert!(timestamp.checked_add(Duration::MAX).is_none());

pub const fn checked_sub(self, rhs: Duration) -> Option<Self>

Subtracts a duration from a timestamp, checking for overflow.

Returns None if overflow occurred.

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use std::time::Duration;
use tai_time::MonotonicTime;

let timestamp = MonotonicTime::new(1_234_567_890, 987_654_321);
assert!(timestamp.checked_sub(Duration::new(10, 123_456_789)).is_some());
assert!(timestamp.checked_sub(Duration::MAX).is_none());

pub const fn duration_since(self, earlier: Self) -> Duration

Subtracts a timestamp from another timestamp.

Consider using checked_duration_since if the relative ordering of the timestamps is not known with certainty.

Panics

Panics if the argument lies in the future of self.

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use std::time::Duration;
use tai_time::MonotonicTime;

let timestamp_earlier = MonotonicTime::new(1_234_567_879, 987_654_321);
let timestamp_later = MonotonicTime::new(1_234_567_900, 123_456_789);
assert_eq!(
    timestamp_later.duration_since(timestamp_earlier),
    Duration::new(20, 135_802_468)
);

pub const fn checked_duration_since(self, earlier: Self) -> Option<Duration>

Computes the duration elapsed between a timestamp and an earlier timestamp, checking that the timestamps are appropriately ordered.

Returns None if the argument lies in the future of self.

Examples

(Shown here for MonotonicTime, an alias for TaiTime<0>)

use std::time::Duration;
use tai_time::MonotonicTime;

let timestamp_earlier = MonotonicTime::new(1_234_567_879, 987_654_321);
let timestamp_later = MonotonicTime::new(1_234_567_900, 123_456_789);
assert!(timestamp_later.checked_duration_since(timestamp_earlier).is_some());
assert!(timestamp_earlier.checked_duration_since(timestamp_later).is_none());

Trait Implementations

impl<const EPOCH_REF: i64> Add<Duration> for TaiTime<EPOCH_REF>

fn add(self, other: Duration) -> Self

Adds a duration to a timestamp.

Panics

This function panics if the resulting timestamp cannot be represented. See TaiTime::checked_add for a panic-free version.

type Output = TaiTime<EPOCH_REF>

The resulting type after applying the + operator.

impl<const EPOCH_REF: i64> AddAssign<Duration> for TaiTime<EPOCH_REF>

fn add_assign(&mut self, other: Duration)

Increments the timestamp by a duration.

Panics

This function panics if the resulting timestamp cannot be represented.

impl<const EPOCH_REF: i64> Clone for TaiTime<EPOCH_REF>

fn clone(&self) -> TaiTime<EPOCH_REF>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<const EPOCH_REF: i64> Debug for TaiTime<EPOCH_REF>

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

Formats the value using the given formatter.

impl<const EPOCH_REF: i64> Default for TaiTime<EPOCH_REF>

fn default() -> TaiTime<EPOCH_REF>

Returns the “default value” for a type.

impl<'de, const EPOCH_REF: i64> Deserialize<'de> for TaiTime<EPOCH_REF>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<const EPOCH_REF: i64> Display for TaiTime<EPOCH_REF>

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

Displays the TAI timestamp as an RFC3339-like date-time.

impl<const EPOCH_REF: i64> FromStr for TaiTime<EPOCH_REF>

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses an RFC3339-like TAI date-time with signed years. Since TAI is timezone-independent, time zones and offsets suffixes are invalid.

Expected format:

[±][Y]...[Y]YYYY-MM-DD hh:mm:ss[.d[d]...[d]]

or:

[±][Y]...[Y]YYYY-MM-DD'T'hh:mm:ss[.d[d]...[d]]

where delimiter T between date and time may also be a lowercase t.

The year may take any value within ±i32::MAX.

type Err = ParseDateTimeError

The associated error which can be returned from parsing.

impl<const EPOCH_REF: i64> Hash for TaiTime<EPOCH_REF>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<const EPOCH_REF: i64> Ord for TaiTime<EPOCH_REF>

fn cmp(&self, other: &TaiTime<EPOCH_REF>) -> Ordering

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<const EPOCH_REF: i64> PartialEq for TaiTime<EPOCH_REF>

fn eq(&self, other: &TaiTime<EPOCH_REF>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<const EPOCH_REF: i64> PartialOrd for TaiTime<EPOCH_REF>

fn partial_cmp(&self, other: &TaiTime<EPOCH_REF>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<const EPOCH_REF: i64> Serialize for TaiTime<EPOCH_REF>

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<const EPOCH_REF: i64> Sub<Duration> for TaiTime<EPOCH_REF>

fn sub(self, other: Duration) -> Self

Subtracts a duration from a timestamp.

Panics

This function panics if the resulting timestamp cannot be represented. See TaiTime::checked_sub for a panic-free version.

type Output = TaiTime<EPOCH_REF>

The resulting type after applying the - operator.

impl<const EPOCH_REF: i64> SubAssign<Duration> for TaiTime<EPOCH_REF>

fn sub_assign(&mut self, other: Duration)

Decrements the timestamp by a duration.

Panics

This function panics if the resulting timestamp cannot be represented.

impl<const EPOCH_REF: i64> Copy for TaiTime<EPOCH_REF>

impl<const EPOCH_REF: i64> Eq for TaiTime<EPOCH_REF>

impl<const EPOCH_REF: i64> StructuralPartialEq for TaiTime<EPOCH_REF>