Struct Instant 

#[non_exhaustive]
pub struct Instant(/* private fields */);

The native Rust implementation of Temporal.Instant.

Represents a precise moment in time measured as nanoseconds since the Unix epoch (1970-01-01T00:00:00[UTC]). An Instant provides a universal timestamp that represents the same moment regardless of timezone or calendar system.

Use Instant when you need to record exact moments in time, measure elapsed time, or work with high-precision timestamps. Unlike PlainDateTime, an Instant represents an absolute point on the timeline.

Examples

Creating instants

use temporal_rs::Instant;

// From epoch nanoseconds (high-precision timestamps)
let precise_moment = Instant::try_new(1609459200000000000).unwrap();
assert_eq!(precise_moment.epoch_milliseconds(), 1609459200000);

// From epoch milliseconds (common in web applications)
let web_timestamp = Instant::from_epoch_milliseconds(1609459200000).unwrap();
assert_eq!(web_timestamp.epoch_nanoseconds().as_i128(), 1609459200000000000);

Parsing ISO 8601 instant strings

use temporal_rs::Instant;
use core::str::FromStr;

// Parse ISO 8601 instant strings (must include timezone info)
let instant = Instant::from_str("2024-03-15T14:30:45.123Z").unwrap();
assert_eq!(instant.epoch_milliseconds(), 1710513045123);

// Parse instants with different timezone notations
let instant2 = Instant::from_str("2024-03-15T14:30:45.123+00:00").unwrap();
let instant3 = Instant::from_str("2024-03-15T14:30:45.123-00:00").unwrap();
assert_eq!(instant, instant2);
assert_eq!(instant2, instant3);

Instant arithmetic

use temporal_rs::{Instant, Duration};
use core::str::FromStr;

let instant = Instant::try_new(1609459200000000000).unwrap(); // 2021-01-01T00:00:00Z

// Add time duration (only time durations, not date durations)
let later = instant.add(&Duration::from_str("PT1H30M").unwrap()).unwrap();
let expected_ns = 1609459200000000000 + (1 * 3600 + 30 * 60) * 1_000_000_000;
assert_eq!(later.epoch_nanoseconds().as_i128(), expected_ns);

// Calculate difference between instants
let earlier = Instant::try_new(1609459200000000000 - 3600_000_000_000).unwrap();
let duration = earlier.until(&instant, Default::default()).unwrap();
assert_eq!(duration.seconds(), 3600);

Instant precision and limits

use temporal_rs::Instant;

// Instants have well-defined limits based on approximately 100 million days before/after Unix epoch
let max_ns = 8_640_000_000_000_000_000_000i128;  // ~100M days * 24 * 60 * 60 * 1e9
let min_ns = -max_ns;

let max_instant = Instant::try_new(max_ns).unwrap();
let min_instant = Instant::try_new(min_ns).unwrap();

// Values outside the range will fail
assert!(Instant::try_new(max_ns + 1).is_err());
assert!(Instant::try_new(min_ns - 1).is_err());

Converting to ZonedDateTime (requires provider)

use temporal_rs::{Instant, TimeZone, Calendar};

let instant = Instant::try_new(1609459200000000000).unwrap();
let timezone = TimeZone::try_from_str("America/New_York").unwrap();

// Convert to a zoned date-time for display in local time
let zdt = instant.to_zoned_date_time_iso(timezone);
assert_eq!(zdt.timezone().identifier(), "America/New_York");
assert_eq!(zdt.calendar().identifier(), "iso8601");

Rounding instants

use temporal_rs::{Instant, options::{RoundingOptions, Unit}};

let instant = Instant::try_new(1609459245123456789).unwrap(); // some precise moment

let mut opts = RoundingOptions::default();
opts.smallest_unit = Some(Unit::Second);
let rounded = instant.round(opts).unwrap();

// Rounded to the nearest second
assert_eq!(rounded.epoch_nanoseconds().as_i128() % 1_000_000_000, 0);

Reference

For more information, see the MDN documentation.

Implementations

impl Instant

pub fn to_ixdtf_string( &self, timezone: Option<TimeZone>, options: ToStringRoundingOptions, ) -> TemporalResult<String>

Returns the RFC9557 (IXDTF) string for this Instant with the provided options

Enable with the compiled_data feature flag.

pub fn to_ixdtf_writeable( &self, timezone: Option<TimeZone>, options: ToStringRoundingOptions, ) -> TemporalResult<impl Writeable + '_>

Returns the RFC9557 (IXDTF) string for this Instant with the provided options as a Writeable

Enable with the compiled_data feature flag.

pub fn to_zoned_date_time_iso( &self, time_zone: TimeZone, ) -> TemporalResult<ZonedDateTime>

impl Instant

pub fn as_i128(&self) -> i128

impl Instant

pub fn try_new(nanoseconds: i128) -> TemporalResult<Self>

Create a new validated Instant.

pub fn from_epoch_milliseconds(epoch_milliseconds: i64) -> TemporalResult<Self>

Creates a new Instant from the provided Epoch millisecond value.

pub fn from_utf8(s: &[u8]) -> TemporalResult<Self>

pub fn add(&self, duration: &Duration) -> TemporalResult<Self>

Adds a Duration to the current Instant, returning an error if the Duration contains a DateDuration.

pub fn subtract(&self, duration: &Duration) -> TemporalResult<Self>

Subtract a Duration to the current Instant, returning an error if the Duration contains a DateDuration.

pub fn since( &self, other: &Self, settings: DifferenceSettings, ) -> TemporalResult<Duration>

Returns a Duration representing the duration since provided Instant

pub fn until( &self, other: &Self, settings: DifferenceSettings, ) -> TemporalResult<Duration>

Returns a Duration representing the duration until provided Instant

pub fn round(&self, options: RoundingOptions) -> TemporalResult<Self>

Returns an Instant by rounding the current Instant according to the provided settings.

pub fn epoch_milliseconds(&self) -> i64

Returns the epochMilliseconds value for this Instant.

pub fn epoch_nanoseconds(&self) -> &EpochNanoseconds

Returns the EpochNanoseconds value for this Instant.

pub fn to_zoned_date_time_iso_with_provider( &self, time_zone: TimeZone, provider: &(impl TimeZoneProvider + ?Sized), ) -> TemporalResult<ZonedDateTime>

Returns a ZonedDateTime for the current Instant.

impl Instant

pub fn to_ixdtf_string_with_provider( &self, timezone: Option<TimeZone>, options: ToStringRoundingOptions, provider: &(impl TimeZoneProvider + ?Sized), ) -> TemporalResult<String>

Returns an RFC9557 IXDTF string representing the current Instant.

pub fn to_ixdtf_writeable_with_provider( &self, timezone: Option<TimeZone>, options: ToStringRoundingOptions, provider: &(impl TimeZoneProvider + ?Sized), ) -> TemporalResult<impl Writeable + '_>

Returns a Writeable for formatting the current Instant in RFC9557’s IXDTF.

Trait Implementations

impl Clone for Instant

fn clone(&self) -> Instant

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Instant

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

Formats the value using the given formatter.

impl From<EpochNanoseconds> for Instant

fn from(value: EpochNanoseconds) -> Self

Converts to this type from the input type.

impl FromStr for Instant

type Err = TemporalError

The associated error which can be returned from parsing.

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

Parses a string s to return a value of this type.

impl Ord for Instant

fn cmp(&self, other: &Instant) -> 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,

Restrict a value to a certain interval.

impl PartialEq for Instant

fn eq(&self, other: &Instant) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl PartialOrd for Instant

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl Copy for Instant

impl Eq for Instant

impl StructuralPartialEq for Instant