`boa_temporal` structure changes and docs update (#3504)

* API changes and docs update

* cargo fmt all

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,
     },

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(())
     }
 

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},

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};
 

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};
 

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)]

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)]

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)]

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)]

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)]

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;

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;
 

boa_temporal/src/components/date.rs

@@ -1,9 +1,11 @@
-//! The `PlainDate` representation.
+//! This module implements `Date` and any directly related algorithms.
 
 use crate::{
+    components::{
         calendar::{AvailableCalendars, CalendarSlot},
-    datetime::DateTime,
-    duration::{DateDuration, Duration},
+        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,

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,

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,

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;
 

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;

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,

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 {

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.

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,

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};

boa_temporal/src/error.rs

@@ -1,4 +1,4 @@
-//! An error type for Temporal Errors.
+//! This module implements `TemporalError`.
 
 use core::fmt;
 

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   |

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,

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<T> = Result<T, TemporalError>;
 
 // 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;

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};
 

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

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;
 

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,

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},