From 4700436ad0d2b48118aa4ddab407395b94a52a60 Mon Sep 17 00:00:00 2001 From: Kevin <46825870+nekevss@users.noreply.github.com> Date: Wed, 6 Dec 2023 05:16:19 -0500 Subject: [PATCH] `boa_temporal` structure changes and docs update (#3504) * API changes and docs update * cargo fmt all --- .../src/builtins/temporal/calendar/mod.rs | 2 +- .../src/builtins/temporal/calendar/object.rs | 24 +++------- .../src/builtins/temporal/duration/mod.rs | 2 +- .../src/builtins/temporal/instant/mod.rs | 2 +- .../src/builtins/temporal/plain_date/mod.rs | 5 +- .../builtins/temporal/plain_date_time/mod.rs | 2 +- .../builtins/temporal/plain_month_day/mod.rs | 2 +- .../builtins/temporal/plain_year_month/mod.rs | 2 +- .../src/builtins/temporal/time_zone/mod.rs | 2 +- .../builtins/temporal/zoned_date_time/mod.rs | 4 +- boa_temporal/src/{ => components}/calendar.rs | 11 ++--- .../src/{ => components}/calendar/iso.rs | 8 +--- boa_temporal/src/{ => components}/date.rs | 12 +++-- boa_temporal/src/{ => components}/datetime.rs | 7 ++- boa_temporal/src/{ => components}/duration.rs | 17 +++---- boa_temporal/src/{ => components}/instant.rs | 4 +- boa_temporal/src/components/mod.rs | 46 +++++++++++++++++++ .../src/{ => components}/month_day.rs | 6 +-- boa_temporal/src/{ => components}/time.rs | 4 +- boa_temporal/src/{ => components}/tz.rs | 3 +- .../src/{ => components}/year_month.rs | 6 +-- .../src/{ => components}/zoneddatetime.rs | 25 ++++++---- boa_temporal/src/error.rs | 2 +- boa_temporal/src/fields.rs | 8 ++-- boa_temporal/src/iso.rs | 13 +++--- boa_temporal/src/lib.rs | 34 +++++++++----- boa_temporal/src/options.rs | 5 +- boa_temporal/src/parser/duration.rs | 2 +- boa_temporal/src/parser/mod.rs | 2 +- boa_temporal/src/parser/tests.rs | 3 +- boa_temporal/src/utils.rs | 2 +- 31 files changed, 155 insertions(+), 112 deletions(-) rename boa_temporal/src/{ => components}/calendar.rs (98%) rename boa_temporal/src/{ => components}/calendar/iso.rs (98%) rename boa_temporal/src/{ => components}/date.rs (96%) rename boa_temporal/src/{ => components}/datetime.rs (95%) rename boa_temporal/src/{ => components}/duration.rs (99%) rename boa_temporal/src/{ => components}/instant.rs (95%) create mode 100644 boa_temporal/src/components/mod.rs rename boa_temporal/src/{ => components}/month_day.rs (85%) rename boa_temporal/src/{ => components}/time.rs (88%) rename boa_temporal/src/{ => components}/tz.rs (97%) rename boa_temporal/src/{ => components}/year_month.rs (86%) rename boa_temporal/src/{ => components}/zoneddatetime.rs (92%) diff --git a/boa_engine/src/builtins/temporal/calendar/mod.rs b/boa_engine/src/builtins/temporal/calendar/mod.rs index 44daafc980..1afc88edb6 100644 --- a/boa_engine/src/builtins/temporal/calendar/mod.rs +++ b/boa_engine/src/builtins/temporal/calendar/mod.rs @@ -24,7 +24,7 @@ use crate::{ use boa_gc::{Finalize, Trace}; use boa_profiler::Profiler; use boa_temporal::{ - calendar::{ + components::calendar::{ AvailableCalendars, CalendarDateLike, CalendarFieldsType, CalendarSlot, CALENDAR_PROTOCOL_METHODS, }, diff --git a/boa_engine/src/builtins/temporal/calendar/object.rs b/boa_engine/src/builtins/temporal/calendar/object.rs index 2805ce37cc..76d7fcad54 100644 --- a/boa_engine/src/builtins/temporal/calendar/object.rs +++ b/boa_engine/src/builtins/temporal/calendar/object.rs @@ -9,15 +9,12 @@ use std::any::Any; use boa_macros::utf16; use boa_temporal::{ - calendar::{CalendarDateLike, CalendarProtocol}, - date::Date, - duration::Duration, - error::TemporalError, - fields::TemporalFields, - month_day::MonthDay, + components::{ + calendar::{CalendarDateLike, CalendarFieldsType, CalendarProtocol}, + Date, Duration, MonthDay, YearMonth, + }, options::ArithmeticOverflow, - year_month::YearMonth, - TemporalResult, TinyAsciiStr, + TemporalError, TemporalFields, TemporalResult, TinyAsciiStr, }; use num_traits::ToPrimitive; use plain_date::PlainDate; @@ -821,10 +818,7 @@ impl CalendarProtocol for CustomRuntimeCalendar { // TODO: Determine fate of fn fields() - fn field_descriptors( - &self, - _: boa_temporal::calendar::CalendarFieldsType, - ) -> Vec<(String, bool)> { + fn field_descriptors(&self, _: CalendarFieldsType) -> Vec<(String, bool)> { Vec::default() } @@ -832,11 +826,7 @@ impl CalendarProtocol for CustomRuntimeCalendar { Vec::default() } - fn resolve_fields( - &self, - _: &mut TemporalFields, - _: boa_temporal::calendar::CalendarFieldsType, - ) -> TemporalResult<()> { + fn resolve_fields(&self, _: &mut TemporalFields, _: CalendarFieldsType) -> TemporalResult<()> { Ok(()) } diff --git a/boa_engine/src/builtins/temporal/duration/mod.rs b/boa_engine/src/builtins/temporal/duration/mod.rs index f30437cca8..f03a7d914b 100644 --- a/boa_engine/src/builtins/temporal/duration/mod.rs +++ b/boa_engine/src/builtins/temporal/duration/mod.rs @@ -16,7 +16,7 @@ use crate::{ }; use boa_gc::{Finalize, Trace}; use boa_profiler::Profiler; -use boa_temporal::{duration::Duration as InnerDuration, options::TemporalUnit}; +use boa_temporal::{components::Duration as InnerDuration, options::TemporalUnit}; use super::{ options::{get_temporal_rounding_increment, get_temporal_unit, TemporalUnitGroup}, diff --git a/boa_engine/src/builtins/temporal/instant/mod.rs b/boa_engine/src/builtins/temporal/instant/mod.rs index 31d368fbcd..1717547917 100644 --- a/boa_engine/src/builtins/temporal/instant/mod.rs +++ b/boa_engine/src/builtins/temporal/instant/mod.rs @@ -20,7 +20,7 @@ use crate::{ }; use boa_gc::{Finalize, Trace}; use boa_profiler::Profiler; -use boa_temporal::{duration::Duration, options::TemporalUnit}; +use boa_temporal::{components::Duration, options::TemporalUnit}; use super::{ns_max_instant, ns_min_instant, MIS_PER_DAY, MS_PER_DAY, NS_PER_DAY}; diff --git a/boa_engine/src/builtins/temporal/plain_date/mod.rs b/boa_engine/src/builtins/temporal/plain_date/mod.rs index e3cfdce051..138273cd22 100644 --- a/boa_engine/src/builtins/temporal/plain_date/mod.rs +++ b/boa_engine/src/builtins/temporal/plain_date/mod.rs @@ -16,7 +16,10 @@ use crate::{ }; use boa_gc::{Finalize, Trace}; use boa_profiler::Profiler; -use boa_temporal::{date::Date as InnerDate, datetime::DateTime, options::ArithmeticOverflow}; +use boa_temporal::{ + components::{Date as InnerDate, DateTime}, + options::ArithmeticOverflow, +}; use super::{calendar, PlainDateTime, ZonedDateTime}; diff --git a/boa_engine/src/builtins/temporal/plain_date_time/mod.rs b/boa_engine/src/builtins/temporal/plain_date_time/mod.rs index a5b9c6bce9..a8c3a8e793 100644 --- a/boa_engine/src/builtins/temporal/plain_date_time/mod.rs +++ b/boa_engine/src/builtins/temporal/plain_date_time/mod.rs @@ -12,7 +12,7 @@ use crate::{ use boa_gc::{Finalize, Trace}; use boa_profiler::Profiler; -use boa_temporal::datetime::DateTime as InnerDateTime; +use boa_temporal::components::DateTime as InnerDateTime; /// The `Temporal.PlainDateTime` object. #[derive(Debug, Clone, Trace, Finalize, JsData)] diff --git a/boa_engine/src/builtins/temporal/plain_month_day/mod.rs b/boa_engine/src/builtins/temporal/plain_month_day/mod.rs index 7e3c9a75ac..0caf7f895a 100644 --- a/boa_engine/src/builtins/temporal/plain_month_day/mod.rs +++ b/boa_engine/src/builtins/temporal/plain_month_day/mod.rs @@ -12,7 +12,7 @@ use crate::{ use boa_gc::{Finalize, Trace}; use boa_profiler::Profiler; -use boa_temporal::{datetime::DateTime, month_day::MonthDay as InnerMonthDay}; +use boa_temporal::components::{DateTime, MonthDay as InnerMonthDay}; /// The `Temporal.PlainMonthDay` object. #[derive(Debug, Clone, Trace, Finalize, JsData)] diff --git a/boa_engine/src/builtins/temporal/plain_year_month/mod.rs b/boa_engine/src/builtins/temporal/plain_year_month/mod.rs index 55ff12ceab..5d3f4b7929 100644 --- a/boa_engine/src/builtins/temporal/plain_year_month/mod.rs +++ b/boa_engine/src/builtins/temporal/plain_year_month/mod.rs @@ -14,7 +14,7 @@ use boa_gc::{Finalize, Trace}; use boa_profiler::Profiler; use super::calendar::to_temporal_calendar_slot_value; -use boa_temporal::{options::ArithmeticOverflow, year_month::YearMonth as InnerYearMonth}; +use boa_temporal::{components::YearMonth as InnerYearMonth, options::ArithmeticOverflow}; /// The `Temporal.PlainYearMonth` object. #[derive(Debug, Clone, Trace, Finalize, JsData)] diff --git a/boa_engine/src/builtins/temporal/time_zone/mod.rs b/boa_engine/src/builtins/temporal/time_zone/mod.rs index 09a841b3d1..facf2d7008 100644 --- a/boa_engine/src/builtins/temporal/time_zone/mod.rs +++ b/boa_engine/src/builtins/temporal/time_zone/mod.rs @@ -15,7 +15,7 @@ use crate::{ }; use boa_gc::{Finalize, Trace}; use boa_profiler::Profiler; -use boa_temporal::tz::{TimeZoneSlot, TzProtocol}; +use boa_temporal::components::tz::{TimeZoneSlot, TzProtocol}; /// The `Temporal.TimeZone` object. #[derive(Debug, Clone, Trace, Finalize, JsData)] diff --git a/boa_engine/src/builtins/temporal/zoned_date_time/mod.rs b/boa_engine/src/builtins/temporal/zoned_date_time/mod.rs index ad097fbb79..64295e547d 100644 --- a/boa_engine/src/builtins/temporal/zoned_date_time/mod.rs +++ b/boa_engine/src/builtins/temporal/zoned_date_time/mod.rs @@ -9,9 +9,7 @@ use crate::{ }; use boa_gc::{Finalize, Trace}; use boa_profiler::Profiler; -use boa_temporal::{ - duration::Duration as TemporalDuration, zoneddatetime::ZonedDateTime as InnerZdt, -}; +use boa_temporal::components::{Duration as TemporalDuration, ZonedDateTime as InnerZdt}; /// The `Temporal.ZonedDateTime` object. #[derive(Debug, Clone, Finalize, Trace, JsData)] diff --git a/boa_temporal/src/calendar.rs b/boa_temporal/src/components/calendar.rs similarity index 98% rename from boa_temporal/src/calendar.rs rename to boa_temporal/src/components/calendar.rs index 5d9e112f83..ff34b6e8e0 100644 --- a/boa_temporal/src/calendar.rs +++ b/boa_temporal/src/components/calendar.rs @@ -1,4 +1,4 @@ -//! Temporal calendar traits and implementations. +//! This module implements the calendar traits and related components. //! //! The goal of the calendar module of `boa_temporal` is to provide //! Temporal compatible calendar implementations. @@ -11,15 +11,10 @@ use std::{any::Any, str::FromStr}; use crate::{ - date::Date, - datetime::DateTime, - duration::Duration, - fields::TemporalFields, + components::{Date, DateTime, Duration, MonthDay, YearMonth}, iso::{IsoDate, IsoDateSlots}, - month_day::MonthDay, options::{ArithmeticOverflow, TemporalUnit}, - year_month::YearMonth, - TemporalError, TemporalResult, + TemporalError, TemporalFields, TemporalResult, }; use tinystr::TinyAsciiStr; diff --git a/boa_temporal/src/calendar/iso.rs b/boa_temporal/src/components/calendar/iso.rs similarity index 98% rename from boa_temporal/src/calendar/iso.rs rename to boa_temporal/src/components/calendar/iso.rs index 1ac7283fb2..51e232d940 100644 --- a/boa_temporal/src/calendar/iso.rs +++ b/boa_temporal/src/components/calendar/iso.rs @@ -1,15 +1,11 @@ //! Implementation of the "iso8601" calendar. use crate::{ - date::Date, - duration::Duration, + components::{Date, Duration, MonthDay, YearMonth}, error::TemporalError, fields::TemporalFields, - month_day::MonthDay, options::{ArithmeticOverflow, TemporalUnit}, - utils, - year_month::YearMonth, - TemporalResult, + utils, TemporalResult, }; use std::any::Any; diff --git a/boa_temporal/src/date.rs b/boa_temporal/src/components/date.rs similarity index 96% rename from boa_temporal/src/date.rs rename to boa_temporal/src/components/date.rs index 026e654d20..e31eac331b 100644 --- a/boa_temporal/src/date.rs +++ b/boa_temporal/src/components/date.rs @@ -1,9 +1,11 @@ -//! The `PlainDate` representation. +//! This module implements `Date` and any directly related algorithms. use crate::{ - calendar::{AvailableCalendars, CalendarSlot}, - datetime::DateTime, - duration::{DateDuration, Duration}, + components::{ + calendar::{AvailableCalendars, CalendarSlot}, + duration::DateDuration, + DateTime, Duration, + }, iso::{IsoDate, IsoDateSlots}, options::{ArithmeticOverflow, TemporalUnit}, parser::parse_date_time, @@ -11,7 +13,7 @@ use crate::{ }; use std::{any::Any, str::FromStr}; -/// The `Temporal.PlainDate` equivalent +/// The native Rust implementation of `Temporal.PlainDate`. #[derive(Debug, Default, Clone)] pub struct Date { iso: IsoDate, diff --git a/boa_temporal/src/datetime.rs b/boa_temporal/src/components/datetime.rs similarity index 95% rename from boa_temporal/src/datetime.rs rename to boa_temporal/src/components/datetime.rs index 8aab3e84ed..59703d2ff8 100644 --- a/boa_temporal/src/datetime.rs +++ b/boa_temporal/src/components/datetime.rs @@ -1,17 +1,16 @@ -//! Temporal implementation of `DateTime` +//! This module implements `DateTime` any directly related algorithms. use std::str::FromStr; use crate::{ - calendar::CalendarSlot, - instant::Instant, + components::{calendar::CalendarSlot, Instant}, iso::{IsoDate, IsoDateSlots, IsoDateTime, IsoTime}, options::ArithmeticOverflow, parser::parse_date_time, TemporalError, TemporalResult, }; -/// The `DateTime` struct. +/// The native Rust implementation of `Temporal.PlainDateTime` #[derive(Debug, Default, Clone)] pub struct DateTime { iso: IsoDateTime, diff --git a/boa_temporal/src/duration.rs b/boa_temporal/src/components/duration.rs similarity index 99% rename from boa_temporal/src/duration.rs rename to boa_temporal/src/components/duration.rs index a324af4f82..abdaf17cde 100644 --- a/boa_temporal/src/duration.rs +++ b/boa_temporal/src/components/duration.rs @@ -1,15 +1,10 @@ -//! The Temporal Duration. -//! -//! TODO: Docs +//! This module implements `Duration` along with it's methods and components. use crate::{ - date::Date, - datetime::DateTime, + components::{Date, DateTime, ZonedDateTime}, options::{ArithmeticOverflow, TemporalRoundingMode, TemporalUnit}, parser::{duration::parse_duration, Cursor}, - utils, - zoneddatetime::ZonedDateTime, - TemporalError, TemporalResult, NS_PER_DAY, + utils, TemporalError, TemporalResult, NS_PER_DAY, }; use std::{any::Any, str::FromStr}; @@ -252,8 +247,10 @@ impl Iterator for TimeIter<'_> { // ==== `Duration` ==== -/// The `Duration` is a native Rust implementation of the `Duration` builtin -/// object internal fields and is primarily defined by Abtract Operation 7.5.1-5. +/// The native Rust implementation of `Temporal.Duration`. +/// +/// `Duration` is made up of a `DateDuration` and `TimeDuration` as primarily +/// defined by Abtract Operation 7.5.1-5. #[derive(Debug, Clone, Copy, Default)] pub struct Duration { date: DateDuration, diff --git a/boa_temporal/src/instant.rs b/boa_temporal/src/components/instant.rs similarity index 95% rename from boa_temporal/src/instant.rs rename to boa_temporal/src/components/instant.rs index 82f645aa18..22fd69b3ad 100644 --- a/boa_temporal/src/instant.rs +++ b/boa_temporal/src/components/instant.rs @@ -5,7 +5,7 @@ use crate::{TemporalError, TemporalResult}; use num_bigint::BigInt; use num_traits::ToPrimitive; -/// A Temporal Instant +/// The native Rust implementation of `Temporal.Instant` #[derive(Debug, Clone)] pub struct Instant { pub(crate) nanos: BigInt, @@ -69,7 +69,7 @@ pub(crate) fn is_valid_epoch_nanos(nanos: &BigInt) -> bool { #[cfg(test)] mod tests { - use crate::{instant::Instant, NS_MAX_INSTANT, NS_MIN_INSTANT}; + use crate::{components::Instant, NS_MAX_INSTANT, NS_MIN_INSTANT}; use num_bigint::BigInt; use num_traits::ToPrimitive; diff --git a/boa_temporal/src/components/mod.rs b/boa_temporal/src/components/mod.rs new file mode 100644 index 0000000000..c3175e33f1 --- /dev/null +++ b/boa_temporal/src/components/mod.rs @@ -0,0 +1,46 @@ +//! The primary date-time components provided by Temporal. +//! +//! The below components are the main primitives of the `Temporal` specification: +//! - `Date` -> `PlainDate` +//! - `DateTime` -> `PlainDateTime` +//! - `Time` -> `PlainTime` +//! - `Duration` -> `Duration` +//! - `Instant` -> `Instant` +//! - `MonthDay` -> `PlainMonthDay` +//! - `YearMonth` -> `PlainYearMonth` +//! - `ZonedDateTime` -> `ZonedDateTime` +//! +//! The Temporal specification, along with this implementation aims to provide +//! full support for time zones and non-gregorian calendars that are compliant +//! with standards like ISO 8601, RFC 3339, and RFC 5545. + +// TODO: Expand upon above introduction. + +pub mod calendar; +pub mod tz; + +mod date; +mod datetime; +pub(crate) mod duration; +mod instant; +mod month_day; +mod time; +mod year_month; +mod zoneddatetime; + +#[doc(inline)] +pub use date::Date; +#[doc(inline)] +pub use datetime::DateTime; +#[doc(inline)] +pub use duration::Duration; +#[doc(inline)] +pub use instant::Instant; +#[doc(inline)] +pub use month_day::MonthDay; +#[doc(inline)] +pub use time::Time; +#[doc(inline)] +pub use year_month::YearMonth; +#[doc(inline)] +pub use zoneddatetime::ZonedDateTime; diff --git a/boa_temporal/src/month_day.rs b/boa_temporal/src/components/month_day.rs similarity index 85% rename from boa_temporal/src/month_day.rs rename to boa_temporal/src/components/month_day.rs index 0d9b7875c3..1b06eb17c1 100644 --- a/boa_temporal/src/month_day.rs +++ b/boa_temporal/src/components/month_day.rs @@ -1,13 +1,13 @@ -//! `MonthDay` +//! This module implements `MonthDay` and any directly related algorithms. use crate::{ - calendar::CalendarSlot, + components::calendar::CalendarSlot, iso::{IsoDate, IsoDateSlots}, options::ArithmeticOverflow, TemporalResult, }; -/// The `MonthDay` struct +/// The native Rust implementation of `Temporal.PlainMonthDay` #[derive(Debug, Default, Clone)] pub struct MonthDay { iso: IsoDate, diff --git a/boa_temporal/src/time.rs b/boa_temporal/src/components/time.rs similarity index 88% rename from boa_temporal/src/time.rs rename to boa_temporal/src/components/time.rs index 6c1fb3a9d7..c6450e61b8 100644 --- a/boa_temporal/src/time.rs +++ b/boa_temporal/src/components/time.rs @@ -1,8 +1,8 @@ -//! Temporal Time Representation. +//! This module implements `Time` and any directly related algorithms. use crate::{iso::IsoTime, options::ArithmeticOverflow, TemporalResult}; -/// The Temporal `PlainTime` object. +/// The native Rust implementation of `Temporal.PlainTime`. #[derive(Debug, Default, Clone, Copy)] #[allow(dead_code)] pub struct Time { diff --git a/boa_temporal/src/tz.rs b/boa_temporal/src/components/tz.rs similarity index 97% rename from boa_temporal/src/tz.rs rename to boa_temporal/src/components/tz.rs index 701f268ff0..77c256f659 100644 --- a/boa_temporal/src/tz.rs +++ b/boa_temporal/src/components/tz.rs @@ -6,7 +6,8 @@ use num_bigint::BigInt; use num_traits::ToPrimitive; use crate::{ - calendar::CalendarSlot, datetime::DateTime, instant::Instant, TemporalError, TemporalResult, + components::{calendar::CalendarSlot, DateTime, Instant}, + TemporalError, TemporalResult, }; /// Any object that implements the `TzProtocol` must implement the below methods/properties. diff --git a/boa_temporal/src/year_month.rs b/boa_temporal/src/components/year_month.rs similarity index 86% rename from boa_temporal/src/year_month.rs rename to boa_temporal/src/components/year_month.rs index c7283cb7b0..96e36d6f74 100644 --- a/boa_temporal/src/year_month.rs +++ b/boa_temporal/src/components/year_month.rs @@ -1,13 +1,13 @@ -//! `YearMonth` +//! This module implements `YearMonth` and any directly related algorithms. use crate::{ - calendar::CalendarSlot, + components::calendar::CalendarSlot, iso::{IsoDate, IsoDateSlots}, options::ArithmeticOverflow, TemporalResult, }; -/// The `YearMonth` struct +/// The native Rust implementation of `Temporal.YearMonth`. #[derive(Debug, Default, Clone)] pub struct YearMonth { iso: IsoDate, diff --git a/boa_temporal/src/zoneddatetime.rs b/boa_temporal/src/components/zoneddatetime.rs similarity index 92% rename from boa_temporal/src/zoneddatetime.rs rename to boa_temporal/src/components/zoneddatetime.rs index b55405e142..cea711f799 100644 --- a/boa_temporal/src/zoneddatetime.rs +++ b/boa_temporal/src/components/zoneddatetime.rs @@ -1,13 +1,20 @@ -//! The `ZonedDateTime` module. +//! This module implements `ZonedDateTime` and any directly related algorithms. use num_bigint::BigInt; use tinystr::TinyStr4; -use crate::{calendar::CalendarSlot, instant::Instant, tz::TimeZoneSlot, TemporalResult}; +use crate::{ + components::{ + calendar::{CalendarDateLike, CalendarSlot}, + tz::TimeZoneSlot, + Instant, + }, + TemporalResult, +}; use core::any::Any; -/// Temporal's `ZonedDateTime` object. +/// The native Rust implementation of `Temporal.ZonedDateTime`. #[derive(Debug, Clone)] pub struct ZonedDateTime { instant: Instant, @@ -86,8 +93,7 @@ impl ZonedDateTime { let dt = self .tz .get_datetime_for(&self.instant, &self.calendar, context)?; - self.calendar - .year(&crate::calendar::CalendarDateLike::DateTime(dt), context) + self.calendar.year(&CalendarDateLike::DateTime(dt), context) } /// Returns the `year` value for this `ZonedDateTime`. @@ -102,7 +108,7 @@ impl ZonedDateTime { .tz .get_datetime_for(&self.instant, &self.calendar, context)?; self.calendar - .month(&crate::calendar::CalendarDateLike::DateTime(dt), context) + .month(&CalendarDateLike::DateTime(dt), context) } /// Returns the `month` value for this `ZonedDateTime`. @@ -117,7 +123,7 @@ impl ZonedDateTime { .tz .get_datetime_for(&self.instant, &self.calendar, context)?; self.calendar - .month_code(&crate::calendar::CalendarDateLike::DateTime(dt), context) + .month_code(&CalendarDateLike::DateTime(dt), context) } /// Returns the `monthCode` value for this `ZonedDateTime`. @@ -131,8 +137,7 @@ impl ZonedDateTime { let dt = self .tz .get_datetime_for(&self.instant, &self.calendar, context)?; - self.calendar - .day(&crate::calendar::CalendarDateLike::DateTime(dt), context) + self.calendar.day(&CalendarDateLike::DateTime(dt), context) } /// Returns the `day` value for this `ZonedDateTime`. @@ -221,7 +226,7 @@ impl ZonedDateTime { #[cfg(test)] mod tests { - use crate::tz::TimeZone; + use crate::components::tz::TimeZone; use num_bigint::BigInt; use super::{CalendarSlot, TimeZoneSlot, ZonedDateTime}; diff --git a/boa_temporal/src/error.rs b/boa_temporal/src/error.rs index 18f38873b9..414871b107 100644 --- a/boa_temporal/src/error.rs +++ b/boa_temporal/src/error.rs @@ -1,4 +1,4 @@ -//! An error type for Temporal Errors. +//! This module implements `TemporalError`. use core::fmt; diff --git a/boa_temporal/src/fields.rs b/boa_temporal/src/fields.rs index 1c6d2a9411..e4308c6298 100644 --- a/boa_temporal/src/fields.rs +++ b/boa_temporal/src/fields.rs @@ -1,4 +1,4 @@ -//! `TemporalFields` native Rust representation. +//! This module implements a native Rust `TemporalField` and components. use std::str::FromStr; @@ -84,13 +84,11 @@ impl FromStr for FieldConversion { } } +/// `TemporalFields` acts as a native Rust implementation of the `fields` object +/// /// The temporal fields are laid out in the Temporal proposal under section 13.46 `PrepareTemporalFields` /// with conversion and defaults laid out by Table 17 (displayed below). /// -/// `TemporalFields` is meant to act as a native Rust implementation -/// of the fields. -/// -/// /// ## Table 17: Temporal field requirements /// /// | Property | Conversion | Default | diff --git a/boa_temporal/src/iso.rs b/boa_temporal/src/iso.rs index 73813677c8..c9e6f6753e 100644 --- a/boa_temporal/src/iso.rs +++ b/boa_temporal/src/iso.rs @@ -1,25 +1,26 @@ -//! The `ISO` module implements the internal ISO field slots. +//! This module implements the internal ISO field slots. //! //! The three main types of slots are: //! - `IsoDateTime` //! - `IsoDate` //! - `IsoTime` //! -//! An `IsoDate` that represents the `[[ISOYear]]`, `[[ISOMonth]]`, and `[[ISODay]]` internal slots. -//! An `IsoTime` that represents the `[[ISOHour]]`, `[[ISOMinute]]`, `[[ISOsecond]]`, `[[ISOmillisecond]]`, +//! An `IsoDate` represents the `[[ISOYear]]`, `[[ISOMonth]]`, and `[[ISODay]]` internal slots. +//! +//! An `IsoTime` represents the `[[ISOHour]]`, `[[ISOMinute]]`, `[[ISOsecond]]`, `[[ISOmillisecond]]`, //! `[[ISOmicrosecond]]`, and `[[ISOnanosecond]]` internal slots. +//! //! An `IsoDateTime` has the internal slots of both an `IsoDate` and `IsoTime`. use crate::{ - duration::DateDuration, error::TemporalError, options::ArithmeticOverflow, utils, + components::duration::DateDuration, error::TemporalError, options::ArithmeticOverflow, utils, TemporalResult, }; use icu_calendar::{Date as IcuDate, Iso}; use num_bigint::BigInt; use num_traits::{cast::FromPrimitive, ToPrimitive}; -/// `IsoDateTime` is the Temporal internal representation of -/// a `DateTime` record +/// `IsoDateTime` is the record of the `IsoDate` and `IsoTime` internal slots. #[derive(Debug, Default, Clone, Copy)] pub struct IsoDateTime { date: IsoDate, diff --git a/boa_temporal/src/lib.rs b/boa_temporal/src/lib.rs index d9dac9b4cb..2dfda77c56 100644 --- a/boa_temporal/src/lib.rs +++ b/boa_temporal/src/lib.rs @@ -1,5 +1,15 @@ -//! Boa's `boa_temporal` crate is intended to serve as an engine agnostic -//! implementation the ECMAScript's Temporal builtin and algorithm. +//! Boa's `boa_temporal` crate is an engine agnostic implementation of ECMAScript's Temporal. +//! +//! IMPORTANT NOTE: Please note that this library is actively being developed and is very +//! much experimental and NOT STABLE. +//! +//! [`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]. +//! +//! [proposal]: https://github.com/tc39/proposal-temporal +//! [spec]: https://tc39.es/proposal-temporal/ #![doc = include_str!("../../ABOUT.md")] #![doc( html_logo_url = "https://raw.githubusercontent.com/boa-dev/boa/main/assets/logo.svg", @@ -27,38 +37,38 @@ clippy::missing_panics_doc, )] -pub mod calendar; -pub mod date; -pub mod datetime; -pub mod duration; +pub mod components; pub mod error; pub mod fields; -pub mod instant; pub mod iso; -pub mod month_day; pub mod options; pub mod parser; -pub mod time; -pub mod tz; + +#[doc(hidden)] pub(crate) mod utils; -pub mod year_month; -pub mod zoneddatetime; // TODO: evaluate positives and negatives of using tinystr. // Re-exporting tinystr as a convenience, as it is currently tied into the API. pub use tinystr::TinyAsciiStr; +#[doc(inline)] pub use error::TemporalError; +#[doc(inline)] +pub use fields::TemporalFields; /// The `Temporal` result type pub type TemporalResult = Result; // Relevant numeric constants /// Nanoseconds per day constant: 8.64e+13 +#[doc(hidden)] pub(crate) const NS_PER_DAY: i64 = 86_400_000_000_000; /// Milliseconds per day constant: 8.64e+7 +#[doc(hidden)] pub(crate) const MS_PER_DAY: i32 = 24 * 60 * 60 * 1000; /// Max Instant nanosecond constant +#[doc(hidden)] pub(crate) const NS_MAX_INSTANT: i128 = NS_PER_DAY as i128 * 100_000_000i128; /// Min Instant nanosecond constant +#[doc(hidden)] pub(crate) const NS_MIN_INSTANT: i128 = -NS_MAX_INSTANT; diff --git a/boa_temporal/src/options.rs b/boa_temporal/src/options.rs index 6f6ccd3cff..09027a3575 100644 --- a/boa_temporal/src/options.rs +++ b/boa_temporal/src/options.rs @@ -1,4 +1,7 @@ -//! Temporal Options +//! Native implementation of the `Temporal` options. +//! +//! Temporal has various instances where user's can define options for how an +//! operation may be completed. use core::{fmt, str::FromStr}; diff --git a/boa_temporal/src/parser/duration.rs b/boa_temporal/src/parser/duration.rs index 1bc4785321..3d9421e04f 100644 --- a/boa_temporal/src/parser/duration.rs +++ b/boa_temporal/src/parser/duration.rs @@ -11,7 +11,7 @@ use crate::{ TemporalError, TemporalResult, }; -/// A ISO8601 `DurationRecord` Parse Node. +/// An ISO8601 `DurationRecord` Parse Node. #[derive(Debug, Clone, Copy)] pub(crate) struct DurationParseRecord { /// Duration Sign diff --git a/boa_temporal/src/parser/mod.rs b/boa_temporal/src/parser/mod.rs index 1dece1be82..f9e07fbd8d 100644 --- a/boa_temporal/src/parser/mod.rs +++ b/boa_temporal/src/parser/mod.rs @@ -1,4 +1,4 @@ -//! Implementation of Iso8601 grammar lexing/parsing +//! This module implements parsing for ISO 8601 grammar. use crate::TemporalResult; diff --git a/boa_temporal/src/parser/tests.rs b/boa_temporal/src/parser/tests.rs index b1348e04bd..ef0e18726d 100644 --- a/boa_temporal/src/parser/tests.rs +++ b/boa_temporal/src/parser/tests.rs @@ -1,8 +1,7 @@ use std::str::FromStr; use crate::{ - datetime::DateTime, - duration::Duration, + components::{DateTime, Duration}, parser::{ parse_date_time, Cursor, TemporalInstantString, TemporalMonthDayString, TemporalYearMonthString, diff --git a/boa_temporal/src/utils.rs b/boa_temporal/src/utils.rs index 09ed3b71c2..a4e303c694 100644 --- a/boa_temporal/src/utils.rs +++ b/boa_temporal/src/utils.rs @@ -1,4 +1,4 @@ -//! Utility equations for Temporal +//! Utility date and time equations for Temporal use crate::{ options::{TemporalRoundingMode, TemporalUnsignedRoundingMode},