Struct LeapSeconds 

pub struct LeapSeconds { /* private fields */ }

An immutable leap-second schedule.

Use LeapSeconds::known() to get the built-in table with all historical leap seconds through 2017-01-01. Works in no_std, no allocation, deterministic.

For custom tables (testing, simulation), use LeapSeconds::builder() (requires std feature).

LeapSeconds is Send + Sync — safe to share across threads. The known() table returns &'static LeapSeconds, so it can be used from any thread without cloning.

Implementations

impl LeapSeconds

pub fn known() -> &'static Self

Returns the built-in table with all historical leap seconds through 2017-01-01.

Works in no_std, requires no allocation, and is fully deterministic. Timestamps after 2017-01-01 use the last known offset (37) because no new leap seconds have been inserted since then.

For custom tables, see LeapSeconds::builder().

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();
let tai = leaps.utc_to_tai(UtcUnixSeconds(1_700_000_000)).unwrap();
assert_eq!(tai, TaiSeconds(1_700_000_037));

pub fn utc_to_tai(&self, utc: UtcUnixSeconds) -> Result<TaiSeconds, Error>

Convert a UTC Unix timestamp to TAI seconds.

Errors

Returns Error::OutOfRange if utc is before the first entry in the table.

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();
let tai = leaps.utc_to_tai(UtcUnixSeconds(1_700_000_000)).unwrap();
assert_eq!(tai, TaiSeconds(1_700_000_037));

pub fn utc_to_tai_nanos(&self, utc: UtcUnixNanos) -> Result<TaiNanos, Error>

Convert UTC Unix nanoseconds to TAI nanoseconds.

The offset is applied in whole seconds; the sub-second fraction is preserved exactly.

Errors

Returns Error::OutOfRange if the timestamp is before 1972-01-01.

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();
let tai = leaps.utc_to_tai_nanos(UtcUnixNanos(1_700_000_000_500_000_000)).unwrap();
assert_eq!(tai, TaiNanos(1_700_000_037_500_000_000));

pub fn tai_to_utc(&self, tai: TaiSeconds) -> Result<UtcUnixSeconds, Error>

Convert TAI seconds to a UTC Unix timestamp.

Errors

Returns Error::OutOfRange if tai is before the first entry in the table.

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();
let utc = leaps.tai_to_utc(TaiSeconds(1_700_000_037)).unwrap();
assert_eq!(utc, UtcUnixSeconds(1_700_000_000));

pub fn tai_to_utc_nanos(&self, tai: TaiNanos) -> Result<UtcUnixNanos, Error>

Convert TAI nanoseconds to UTC Unix nanoseconds.

Errors

Returns Error::OutOfRange if the timestamp is before the table’s TAI range.

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();
let utc = leaps.tai_to_utc_nanos(TaiNanos(1_700_000_037_500_000_000)).unwrap();
assert_eq!(utc, UtcUnixNanos(1_700_000_000_500_000_000));

pub fn utc_to_gpst(&self, utc: UtcUnixSeconds) -> Result<GpstSeconds, Error>

Convert a UTC Unix timestamp to GPS Time.

Composes utc_to_tai then tai_to_gpst (TAI − 19).

Errors

Returns Error::OutOfRange if the timestamp is before 1972-01-01.

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();
let gpst = leaps.utc_to_gpst(UtcUnixSeconds(1_700_000_000)).unwrap();
assert_eq!(gpst, GpstSeconds(1_700_000_018));

pub fn utc_to_gpst_nanos(&self, utc: UtcUnixNanos) -> Result<GpstNanos, Error>

Convert UTC Unix nanoseconds to GPST nanoseconds.

Errors

Returns Error::OutOfRange if the timestamp is before 1972-01-01.

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();
let gpst = leaps.utc_to_gpst_nanos(UtcUnixNanos(1_700_000_000_500_000_000)).unwrap();
assert_eq!(gpst, GpstNanos(1_700_000_018_500_000_000));

pub fn gpst_to_utc(&self, gpst: GpstSeconds) -> Result<UtcUnixSeconds, Error>

Convert GPS Time to a UTC Unix timestamp.

Composes gpst_to_tai (GPST + 19) then tai_to_utc.

Errors

Returns Error::OutOfRange if the resulting TAI is before the table’s range.

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();
let utc = leaps.gpst_to_utc(GpstSeconds(1_700_000_018)).unwrap();
assert_eq!(utc, UtcUnixSeconds(1_700_000_000));

pub fn gpst_to_utc_nanos(&self, gpst: GpstNanos) -> Result<UtcUnixNanos, Error>

Convert GPST nanoseconds to UTC Unix nanoseconds.

Errors

Returns Error::OutOfRange if the resulting TAI is before the table’s range.

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();
let utc = leaps.gpst_to_utc_nanos(GpstNanos(1_700_000_018_500_000_000)).unwrap();
assert_eq!(utc, UtcUnixNanos(1_700_000_000_500_000_000));

pub fn tai_utc_offset(&self, utc: UtcUnixSeconds) -> Result<i32, Error>

Get the TAI−UTC offset at a given UTC instant.

Errors

Returns Error::OutOfRange if the timestamp is before 1972-01-01.

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();
assert_eq!(leaps.tai_utc_offset(UtcUnixSeconds(1_700_000_000)).unwrap(), 37);
assert_eq!(leaps.tai_utc_offset(UtcUnixSeconds(63_072_000)).unwrap(), 10);

pub fn tai_utc_offset_at_tai(&self, tai: TaiSeconds) -> Result<i32, Error>

Get the TAI−UTC offset at a given TAI instant.

Errors

Returns Error::OutOfRange if the TAI timestamp is before the table’s range.

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();
assert_eq!(leaps.tai_utc_offset_at_tai(TaiSeconds(1_700_000_037)).unwrap(), 37);

pub fn is_during_leap_second(&self, utc: UtcUnixSeconds) -> bool

Returns true if utc falls exactly on a positive leap-second insertion.

At such an instant the POSIX timestamp is ambiguous: the UTC wall clock reads 23:59:60 but POSIX folds it to the same value as 00:00:00.

Returns false for:

• The initial 1972-01-01 epoch (offset = 10) — not an insertion, it is the starting offset of the modern UTC system.
• Negative leap seconds (where the offset decreases) — there is no extra second, so no ambiguity. No negative leap second has ever been applied, but the table format supports them.

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();

// 2017-01-01 — the last leap second insertion (2016-12-31 23:59:60)
assert!(leaps.is_during_leap_second(UtcUnixSeconds(1_483_228_800)));

// A normal timestamp — not during a leap second
assert!(!leaps.is_during_leap_second(UtcUnixSeconds(1_700_000_000)));

pub fn valid_range(&self) -> (UtcUnixSeconds, UtcUnixSeconds)

Returns the valid range of this table as (first_entry, last_entry).

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();
let (start, end) = leaps.valid_range();
assert_eq!(start, UtcUnixSeconds(63_072_000));    // 1972-01-01
assert_eq!(end, UtcUnixSeconds(1_483_228_800));   // 2017-01-01

pub const fn is_expired(&self) -> bool

Returns false for the built-in known() table.

For tables with an expiration timestamp, this would return true if the table has expired. In v0.1 there is no clock access — this simply checks whether an expiration is set.

pub fn expires_at(&self) -> Option<UtcUnixSeconds>

Returns the expiration timestamp, if one was set.

The built-in known() table returns None (it has no expiration concept). Tables constructed via the builder may have an expiration set.

Example

use leap_sec::prelude::*;

assert_eq!(LeapSeconds::known().expires_at(), None);

pub fn latest_entry(&self) -> (UtcUnixSeconds, i32)

Returns the most recent leap-second entry: (effective_utc, tai_minus_utc).

For the built-in table this is (2017-01-01, 37).

Example

use leap_sec::prelude::*;

let leaps = LeapSeconds::known();
let (date, offset) = leaps.latest_entry();
assert_eq!(date, UtcUnixSeconds(1_483_228_800));
assert_eq!(offset, 37);

impl LeapSeconds

pub const fn builder() -> LeapSecondsBuilder

Create a builder for constructing a custom leap-second table.

Trait Implementations

impl Clone for LeapSeconds

fn clone(&self) -> LeapSeconds

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for LeapSeconds

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

Formats the value using the given formatter.