From 779688ccec75c5d0dd914075752739927dcb4e46 Mon Sep 17 00:00:00 2001 From: Kevin Ness <46825870+nekevss@users.noreply.github.com> Date: Fri, 9 May 2025 23:25:47 -0500 Subject: [PATCH 1/2] Some docs cleanup and update --- CONTRIBUTING.md | 16 ++++++++-------- README.md | 34 +++++++++++++++++++++++++++++----- docs/testing.md | 6 ++++-- provider/README.md | 9 +++++++++ src/lib.rs | 40 +++++++++++++++++++++++++++++++++++----- 5 files changed, 85 insertions(+), 20 deletions(-) create mode 100644 provider/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b1cb28f9..16d81cb44 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,10 @@ # Contributing to Temporal in Rust -This project is currently highly experimental and fairly volatile. As -such, while we do welcome contributions, we prefer that you open up an -issue first beforehand to ensure the feature is not being actively -worked on by a maintainer. +We welcome contributions, feel free to checkout our open issues. If you +find an issue you're interested in, please feel free to ask to be assigned. If you're interested in helping out but don't see an issue that's for -you, please feel free to contact us on `Boa` Matrix server. +you, please feel free to contact us on `Boa`'s Matrix server. ## Contributor Information @@ -14,9 +12,11 @@ The Temporal proposal is a new date/time API that is being developed and propose for the ECMAScript specification. This library aims to be a Rust implementation of that specification. -Due to the current experimental nature of the material and this library, -we would advise potential contributors to familiarize themselves with -the Temporal specification. +Due to the nature of the material and this library, we would advise anyone +interested in contributing to familiarize themselves with the Temporal +specification. + +Also, always feel free to reach out for any advice or feedback as needed. ## Testing and debugging diff --git a/README.md b/README.md index 2175b4a93..dcf835d7d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Temporal in Rust Temporal is a calendar and timezone aware date/time builtin currently -proposed for edition to the ECMAScript specification. +proposed for addition to the ECMAScript specification. `temporal_rs` is an implementation of Temporal in Rust that aims to be 100% test compliant. While initially developed for [Boa][boa-repo], the @@ -10,14 +10,15 @@ and general usage implementation of Temporal and its algorithms. ## Example usage +Creating an ISO 8601 [`PlainDate`] and convert it into a [`PlainDate`] +with the Japanese calendar. + ```rust 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(2025, 3, 3, Calendar::default()).unwrap(); - +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"))); @@ -25,10 +26,26 @@ assert_eq!(japanese_date.era_year(), Some(7)); assert_eq!(japanese_date.month(), 3) ``` +Create a [`PlainDateTime`] from a [RFC9557](https://www.rfc-editor.org/rfc/rfc9557.txt) IXDTF string. + +```rust +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); +``` + ## Temporal proposal -Relevent links regarding Temporal can be found below. +Relevant links and information regarding Temporal can be found below. +- [Temporal MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal) - [Temporal Documentation](https://tc39.es/proposal-temporal/docs/) - [Temporal Proposal Specification](https://tc39.es/proposal-temporal/) - [Temporal Proposal Repository](https://github.com/tc39/proposal-temporal) @@ -48,6 +65,13 @@ This project is open source and welcomes anyone interested to participate. Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for more information. +## Test262 Conformance + + + +The `temporal_rs`'s current conformance results can be viewed on +Boa's [test262 conformance page](https://boajs.dev/conformance). + ## Communication Feel free to contact us on diff --git a/docs/testing.md b/docs/testing.md index 75235dec1..bd04e1ec0 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,8 +1,10 @@ ## Testing `temporal_rs` Temporal's primary test suite is the [Temporal `test262` test -suite][test262-temporal]. There is an outstanding issue / PR to extract -the tests from test262 into a format that `temporal_rs` can run against. +suite][test262-temporal]. There is an open issue / PR to extract +the tests from test262 into a format that `temporal_rs` can run +against in native Rust. + In the meantime, there are two primary ways to test: 1. Map the test into a Rust version in the `test` module in diff --git a/provider/README.md b/provider/README.md new file mode 100644 index 000000000..873dbcdf6 --- /dev/null +++ b/provider/README.md @@ -0,0 +1,9 @@ + + + +Data providers for time zone data + +This crate aims to provide a variety of data providers +for time zone data. + + diff --git a/src/lib.rs b/src/lib.rs index 25b73f585..110f62177 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,5 +1,15 @@ -//! The `temporal_rs` crate is an implementation of ECMAScript's Temporal -//! built-in objects in Rust. +//! 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 +//! +//! Creating an ISO 8601 [`PlainDate`] and convert it into a [`PlainDate`] +//! with the Japanese calendar. //! //! ```rust //! use temporal_rs::{PlainDate, Calendar}; @@ -7,7 +17,7 @@ //! use core::str::FromStr; //! //! // Create a date with an ISO calendar -//! let iso8601_date = PlainDate::try_new(2025, 3, 3, Calendar::default()).unwrap(); +//! 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(); @@ -16,13 +26,33 @@ //! assert_eq!(japanese_date.month(), 3) //! ``` //! +//! Create a [`PlainDateTime`] from a [RFC9557][ixdtf] IXDTF string. +//! +//! ```rust +//! 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); +//! +//! ``` +//! //! [`Temporal`][proposal] 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 source is the Temporal Proposal -//! [specification][spec]. +//! ## More information +//! +//! This library's primary development source is the Temporal +//! Proposal [specification][spec]. //! +//! [ixdtf]: https://www.rfc-editor.org/rfc/rfc9557.txt //! [proposal]: https://github.com/tc39/proposal-temporal //! [spec]: https://tc39.es/proposal-temporal/ #![doc( From 0ed4edfc98781d85a7f47d8e9c817520bd22871d Mon Sep 17 00:00:00 2001 From: Kevin Ness <46825870+nekevss@users.noreply.github.com> Date: Fri, 9 May 2025 23:54:34 -0500 Subject: [PATCH 2/2] Add a feature flagged zdt example --- README.md | 29 +++++++++++++++++++++++++++++ src/lib.rs | 30 ++++++++++++++++++++++++++++++ 2 files changed, 59 insertions(+) diff --git a/README.md b/README.md index dcf835d7d..4e14b3964 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,7 @@ Create a [`PlainDateTime`] from a [RFC9557](https://www.rfc-editor.org/rfc/rfc95 ```rust 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); @@ -41,6 +42,34 @@ assert_eq!(pdt.minute(), 16); assert_eq!(pdt.second(), 10); ``` +Create a [`ZonedDateTime`] for a RFC 9557 IXDTF string. + +**Important Note:** The below API is enabled with the `compiled_data` feature flag. + +```rust +# #[cfg(feature = "compiled_data")] { +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); +# } +``` + ## Temporal proposal Relevant links and information regarding Temporal can be found below. diff --git a/src/lib.rs b/src/lib.rs index 110f62177..f2488da47 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -43,6 +43,36 @@ //! //! ``` //! +//! Create a [`ZonedDateTime`] for a RFC 9557 IXDTF string. +//! +//! **Important Note:** The below API is enabled with the +//! `compiled_data` feature flag. +//! +//! ```rust +//! # #[cfg(feature = "compiled_data")] { +//! 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); +//! +//! # } +//! ``` +//! //! [`Temporal`][proposal] 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.