Crate temporal_rs

A native Rust implementation of ECMAScript’s Temporal built-ins.

Temporal is a library for working with date and time in a calendar and time zone aware manner.

This crate is designed with ECMAScript implementations and general purpose in mind.

Examples

Below are a few examples to give an overview of temporal_rs’s current API.

Convert from an ISO8601 PlainDate into a Japanese PlainDate

use temporal_rs::{PlainDate, Calendar};
use tinystr::tinystr;
use core::str::FromStr;

// Create a date with an ISO calendar
let iso8601_date = PlainDate::try_new_iso(2025, 3, 3).unwrap();

// Create a new date with the japanese calendar
let japanese_date = iso8601_date.with_calendar(Calendar::from_str("japanese").unwrap()).unwrap();
assert_eq!(japanese_date.era(), Some(tinystr!(16, "reiwa")));
assert_eq!(japanese_date.era_year(), Some(7));
assert_eq!(japanese_date.month(), 3)

Create a PlainDateTime from a RFC9557 IXDTF string.

For more information on the Internet Extended DateTime Format (IXDTF), see RFC9557.

use temporal_rs::PlainDateTime;
use core::str::FromStr;

let pdt = PlainDateTime::from_str("2025-03-01T11:16:10[u-ca=gregory]").unwrap();
assert_eq!(pdt.calendar().identifier(), "gregory");
assert_eq!(pdt.year(), 2025);
assert_eq!(pdt.month(), 3);
assert_eq!(pdt.day(), 1);
assert_eq!(pdt.hour(), 11);
assert_eq!(pdt.minute(), 16);
assert_eq!(pdt.second(), 10);

Create a ZonedDateTime for a RFC9557 IXDTF string.

Important Note: The below API is enabled with the compiled_data feature flag.

use temporal_rs::{ZonedDateTime, TimeZone};
use temporal_rs::options::{Disambiguation, OffsetDisambiguation};

let zdt = ZonedDateTime::from_str("2025-03-01T11:16:10Z[America/Chicago][u-ca=iso8601]", Disambiguation::Compatible, OffsetDisambiguation::Reject).unwrap();
assert_eq!(zdt.year().unwrap(), 2025);
assert_eq!(zdt.month().unwrap(), 3);
assert_eq!(zdt.day().unwrap(), 1);
assert_eq!(zdt.hour().unwrap(), 11);
assert_eq!(zdt.minute().unwrap(), 16);
assert_eq!(zdt.second().unwrap(), 10);

let zurich_zone = TimeZone::try_from_str("Europe/Zurich").unwrap();
let zdt_zurich = zdt.with_timezone(zurich_zone).unwrap();
assert_eq!(zdt_zurich.year().unwrap(), 2025);
assert_eq!(zdt_zurich.month().unwrap(), 3);
assert_eq!(zdt_zurich.day().unwrap(), 1);
assert_eq!(zdt_zurich.hour().unwrap(), 18);
assert_eq!(zdt_zurich.minute().unwrap(), 16);
assert_eq!(zdt_zurich.second().unwrap(), 10);

More information

Temporal is the Stage 3 proposal for ECMAScript that provides new JS objects and functions for working with dates and times that fully supports time zones and non-gregorian calendars.

This library’s primary development source is the Temporal Proposal specification.

Modules

error

This module implements TemporalError.

iso

This module implements the internal ISO field records.

now

The Now module includes type for building a Now.

options

Native implementation of the Temporal options.

parsers

This module implements Temporal Date/Time parsing functionality.

partial

Partial Date/Time component records.

primitive

Implementation of the FiniteF64 primitive

provider

The TimeZoneProvider trait.

tzdb

unix_time

Structs

Calendar

The core Calendar type for temporal_rs

DateDuration

DateDuration represents the date duration record of the Duration.

Duration

The native Rust implementation of Temporal.Duration.

Instant

The native Rust implementation of Temporal.Instant

MonthCode

MonthCode struct v2

PlainDate

The native Rust implementation of Temporal.PlainDate.

PlainDateTime

The native Rust implementation of a Temporal PlainDateTime.

PlainMonthDay

The native Rust implementation of Temporal.PlainMonthDay

PlainTime

The native Rust implementation of Temporal.PlainTime.

PlainYearMonth

The native Rust implementation of Temporal.YearMonth.

Temporal

TemporalError

The error type for boa_temporal.

TimeDuration

TimeDuration represents the Time Duration record of the Duration.

TinyAsciiStr

Re-export of TinyAsciiStr from tinystr.

UtcOffset

A UTC time zone offset stored in minutes

ZonedDateTime

The native Rust implementation of a Temporal ZonedDateTime.

Enums

Sign

A general Sign type.

TimeZone

Constants

MS_PER_DAY

Milliseconds per day constant: 8.64e+7

NS_PER_DAY

Nanoseconds per day constant: 8.64e+13

Type Aliases

TemporalResult

The Temporal result type