Add UtcOffset struct for PartialZonedDateTime (#207)

This PR introduces to `UtcOffset` parse for use with
`PartialZonedDateTime`.

The goal ultimately is providing the tools / API for
[PrepareCalendarFields](https://tc39.es/proposal-temporal/#sec-temporal-preparecalendarfields)
to be implemented, specifically the ToOffsetString conversion, while
also better representing the general invariant of
`PartialZonedDateTime`'s offset.

Author: nekevss

src/builtins/core/timezone.rs

@@ -3,11 +3,13 @@
 use alloc::string::String;
 use alloc::{vec, vec::Vec};
 
+use ixdtf::parsers::records::{TimeZoneRecord, UtcOffsetRecord};
 use num_traits::ToPrimitive;
 
 use crate::builtins::core::duration::DateDuration;
 use crate::parsers::{
-    parse_allowed_timezone_formats, parse_identifier, FormattableOffset, FormattableTime, Precision,
+    parse_allowed_timezone_formats, parse_identifier, parse_offset, FormattableOffset,
+    FormattableTime, Precision,
 };
 use crate::provider::{TimeZoneOffset, TimeZoneProvider};
 use crate::{
@@ -21,20 +23,83 @@ use crate::{Calendar, Sign};
 
 const NS_IN_HOUR: i128 = 60 * 60 * 1000 * 1000 * 1000;
 
+/// A UTC time zone offset stored in minutes
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct UtcOffset(pub(crate) i16);
+
+impl UtcOffset {
+    pub(crate) fn from_ixdtf_record(record: UtcOffsetRecord) -> Self {
+        // NOTE: ixdtf parser restricts minute/second to 0..=60
+        let minutes = i16::from(record.hour) * 60 + record.minute as i16;
+        Self(minutes * i16::from(record.sign as i8))
+    }
+
+    pub fn to_string(&self) -> TemporalResult<String> {
+        let sign = if self.0 < 0 {
+            Sign::Negative
+        } else {
+            Sign::Positive
+        };
+        let hour = (self.0.abs() / 60) as u8;
+        let minute = (self.0.abs() % 60) as u8;
+        let formattable_offset = FormattableOffset {
+            sign,
+            time: FormattableTime {
+                hour,
+                minute,
+                second: 0,
+                nanosecond: 0,
+                precision: Precision::Minute,
+                include_sep: true,
+            },
+        };
+        Ok(formattable_offset.to_string())
+    }
+}
+
+impl core::str::FromStr for UtcOffset {
+    type Err = TemporalError;
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let mut cursor = s.chars().peekable();
+        match parse_offset(&mut cursor)? {
+            Some(offset) => Ok(Self(offset)),
+            None => Err(TemporalError::range().with_message("Invalid offset")),
+        }
+    }
+}
+
 // TODO: Potentially migrate to Cow<'a, str>
 // TODO: There may be an argument to have Offset minutes be a (Cow<'a, str>,, i16) to
 // prevent allocations / writing, TBD
-#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub enum TimeZone {
     IanaIdentifier(String),
-    OffsetMinutes(i16),
+    UtcOffset(UtcOffset),
 }
 
 impl TimeZone {
+    // Create a `TimeZone` from an ixdtf `TimeZoneRecord`.
+    #[inline]
+    pub(crate) fn from_time_zone_record(record: TimeZoneRecord) -> TemporalResult<Self> {
+        let timezone = match record {
+            TimeZoneRecord::Name(s) => {
+                TimeZone::IanaIdentifier(String::from_utf8_lossy(s).into_owned())
+            }
+            TimeZoneRecord::Offset(offset_record) => {
+                let offset = UtcOffset::from_ixdtf_record(offset_record);
+                TimeZone::UtcOffset(offset)
+            }
+            // TimeZoneRecord is non_exhaustive, but all current branches are matching.
+            _ => return Err(TemporalError::assert()),
+        };
+
+        Ok(timezone)
+    }
+
     /// Parses a `TimeZone` from a provided `&str`.
     pub fn try_from_identifier_str(identifier: &str) -> TemporalResult<Self> {
         if identifier == "Z" {
-            return Ok(TimeZone::OffsetMinutes(0));
+            return Ok(TimeZone::UtcOffset(UtcOffset(0)));
         }
         parse_identifier(identifier)
     }
@@ -52,27 +117,7 @@ impl TimeZone {
     pub fn identifier(&self) -> TemporalResult<String> {
         match self {
             TimeZone::IanaIdentifier(s) => Ok(s.clone()),
-            TimeZone::OffsetMinutes(m) => {
-                let sign = if *m < 0 {
-                    Sign::Negative
-                } else {
-                    Sign::Positive
-                };
-                let hour = (m.abs() / 60) as u8;
-                let minute = (m.abs() % 60) as u8;
-                let formattable_offset = FormattableOffset {
-                    sign,
-                    time: FormattableTime {
-                        hour,
-                        minute,
-                        second: 0,
-                        nanosecond: 0,
-                        precision: Precision::Minute,
-                        include_sep: true,
-                    },
-                };
-                Ok(formattable_offset.to_string())
-            }
+            TimeZone::UtcOffset(offset) => offset.to_string(),
         }
     }
 }
@@ -108,7 +153,7 @@ impl TimeZone {
         // 1. Let parseResult be ! ParseTimeZoneIdentifier(timeZone).
         match self {
             // 2. If parseResult.[[OffsetMinutes]] is not empty, return parseResult.[[OffsetMinutes]] × (60 × 10**9).
-            Self::OffsetMinutes(minutes) => Ok(i128::from(*minutes) * 60_000_000_000i128),
+            Self::UtcOffset(offset) => Ok(i128::from(offset.0) * 60_000_000_000i128),
             // 3. Return GetNamedTimeZoneOffsetNanoseconds(parseResult.[[Name]], epochNs).
             Self::IanaIdentifier(identifier) => provider
                 .get_named_tz_offset_nanoseconds(identifier, utc_epoch)
@@ -137,7 +182,7 @@ impl TimeZone {
         // 1.Let parseResult be ! ParseTimeZoneIdentifier(timeZone).
         let possible_nanoseconds = match self {
             // 2. If parseResult.[[OffsetMinutes]] is not empty, then
-            Self::OffsetMinutes(minutes) => {
+            Self::UtcOffset(UtcOffset(minutes)) => {
                 // a. Let balanced be
                 // BalanceISODateTime(isoDateTime.[[ISODate]].[[Year]],
                 // isoDateTime.[[ISODate]].[[Month]],

src/builtins/core/zoneddatetime.rs

@@ -2,14 +2,14 @@
 
 use alloc::string::String;
 use core::{cmp::Ordering, num::NonZeroU128};
-use ixdtf::parsers::records::{TimeZoneRecord, UtcOffsetRecordOrZ};
+use ixdtf::parsers::records::UtcOffsetRecordOrZ;
 use tinystr::TinyAsciiStr;
 
 use crate::{
     builtins::core::{
         calendar::Calendar,
         duration::normalized::{NormalizedDurationRecord, NormalizedTimeDuration},
-        timezone::TimeZone,
+        timezone::{TimeZone, UtcOffset},
         Duration, Instant, PlainDate, PlainDateTime, PlainTime,
     },
     iso::{IsoDate, IsoDateTime, IsoTime},
@@ -19,9 +19,7 @@ use crate::{
         ResolvedRoundingOptions, RoundingIncrement, TemporalRoundingMode, TemporalUnit,
         ToStringRoundingOptions, UnitGroup,
     },
-    parsers::{
-        self, parse_offset, FormattableOffset, FormattableTime, IxdtfStringBuilder, Precision,
-    },
+    parsers::{self, FormattableOffset, FormattableTime, IxdtfStringBuilder, Precision},
     partial::{PartialDate, PartialTime},
     provider::{TimeZoneProvider, TransitionDirection},
     rounding::{IncrementRounder, Round},
@@ -38,7 +36,7 @@ pub struct PartialZonedDateTime {
     /// The `PartialTime` portion of a `PartialZonedDateTime`
     pub time: PartialTime,
     /// An optional offset string
-    pub offset: Option<String>,
+    pub offset: Option<UtcOffset>,
     /// The time zone value of a partial time zone.
     pub timezone: Option<TimeZone>,
 }
@@ -70,7 +68,7 @@ impl PartialZonedDateTime {
         self
     }
 
-    pub fn with_offset(mut self, offset: Option<String>) -> Self {
+    pub const fn with_offset(mut self, offset: Option<UtcOffset>) -> Self {
         self.offset = offset;
         self
     }
@@ -397,15 +395,9 @@ impl ZonedDateTime {
         };
 
         // Handle time zones
-        let offset = partial
+        let offset_nanos = partial
             .offset
-            .map(|offset| {
-                let mut cursor = offset.chars().peekable();
-                parse_offset(&mut cursor)
-            })
-            .transpose()?;
-
-        let offset_nanos = offset.map(|minutes| i64::from(minutes) * 60_000_000_000);
+            .map(|offset| i64::from(offset.0) * 60_000_000_000);
 
         let timezone = partial.timezone.unwrap_or_default();
 
@@ -938,18 +930,7 @@ impl ZonedDateTime {
         // NOTE (nekevss): `parse_zoned_date_time` guarantees that this value exists.
         let annotation = parse_result.tz.temporal_unwrap()?;
 
-        let timezone = match annotation.tz {
-            TimeZoneRecord::Name(s) => {
-                TimeZone::IanaIdentifier(String::from_utf8_lossy(s).into_owned())
-            }
-            TimeZoneRecord::Offset(offset_record) => {
-                // NOTE: ixdtf parser restricts minute/second to 0..=60
-                let minutes = i16::from(offset_record.hour) * 60 + offset_record.minute as i16;
-                TimeZone::OffsetMinutes(minutes * i16::from(offset_record.sign as i8))
-            }
-            // TimeZoneRecord is non_exhaustive, but all current branches are matching.
-            _ => return Err(TemporalError::assert()),
-        };
+        let timezone = TimeZone::from_time_zone_record(annotation.tz)?;
 
         let (offset_nanos, is_exact) = parse_result
             .offset

src/lib.rs

@@ -97,7 +97,7 @@ pub mod time {
 
 pub use crate::builtins::{
     calendar::{Calendar, MonthCode},
-    core::timezone::TimeZone,
+    core::timezone::{TimeZone, UtcOffset},
     DateDuration, Duration, Instant, Now, PlainDate, PlainDateTime, PlainMonthDay, PlainTime,
     PlainYearMonth, TimeDuration, ZonedDateTime,
 };

src/options/relative_to.rs

@@ -1,16 +1,14 @@
 //! RelativeTo rounding option
 
-use alloc::string::String;
-
 use crate::builtins::core::zoneddatetime::interpret_isodatetime_offset;
 use crate::builtins::core::{calendar::Calendar, timezone::TimeZone, PlainDate, ZonedDateTime};
 use crate::iso::{IsoDate, IsoTime};
 use crate::options::{ArithmeticOverflow, Disambiguation, OffsetDisambiguation};
 use crate::parsers::parse_date_time;
 use crate::provider::TimeZoneProvider;
-use crate::{TemporalError, TemporalResult, TemporalUnwrap};
+use crate::{TemporalResult, TemporalUnwrap};
 
-use ixdtf::parsers::records::{TimeZoneRecord, UtcOffsetRecordOrZ};
+use ixdtf::parsers::records::UtcOffsetRecordOrZ;
 
 // ==== RelativeTo Object ====
 
@@ -62,18 +60,7 @@ impl RelativeTo {
             .into());
         };
 
-        let timezone = match annotation.tz {
-            TimeZoneRecord::Name(s) => {
-                TimeZone::IanaIdentifier(String::from_utf8_lossy(s).into_owned())
-            }
-            TimeZoneRecord::Offset(offset_record) => {
-                // NOTE: ixdtf parser restricts minute/second to 0..=60
-                let minutes = i16::from(offset_record.hour) * 60 + offset_record.minute as i16;
-                TimeZone::OffsetMinutes(minutes * i16::from(offset_record.sign as i8))
-            }
-            // TimeZoneRecord is non_exhaustive, but all current branches are matching.
-            _ => return Err(TemporalError::assert()),
-        };
+        let timezone = TimeZone::from_time_zone_record(annotation.tz)?;
 
         let (offset_nanos, is_exact) = result
             .offset

src/parsers/timezone.rs

@@ -1,12 +1,8 @@
 use alloc::borrow::ToOwned;
-use alloc::string::String;
 use core::{iter::Peekable, str::Chars};
-use ixdtf::parsers::{
-    records::{TimeZoneRecord, UtcOffsetRecord, UtcOffsetRecordOrZ},
-    IxdtfParser,
-};
+use ixdtf::parsers::{records::UtcOffsetRecordOrZ, IxdtfParser};
 
-use crate::{TemporalError, TemporalResult, TimeZone};
+use crate::{builtins::timezone::UtcOffset, TemporalError, TemporalResult, TimeZone};
 
 use super::{parse_ixdtf, ParseVariant};
 
@@ -34,45 +30,38 @@ pub(crate) fn parse_allowed_timezone_formats(s: &str) -> Option<TimeZone> {
     };
 
     if let Some(annotation) = annotation {
-        match annotation.tz {
-            TimeZoneRecord::Name(s) => {
-                let identifier = String::from_utf8_lossy(s).into_owned();
-                return Some(TimeZone::IanaIdentifier(identifier));
-            }
-            TimeZoneRecord::Offset(offset) => return Some(timezone_from_offset_record(offset)),
-            _ => {}
-        }
+        return TimeZone::from_time_zone_record(annotation.tz).ok();
     };
 
     if let Some(offset) = offset {
         match offset {
             UtcOffsetRecordOrZ::Z => return Some(TimeZone::default()),
-            UtcOffsetRecordOrZ::Offset(offset) => return Some(timezone_from_offset_record(offset)),
+            UtcOffsetRecordOrZ::Offset(offset) => {
+                return Some(TimeZone::UtcOffset(UtcOffset::from_ixdtf_record(offset)))
+            }
         }
     }
 
     None
 }
 
-fn timezone_from_offset_record(record: UtcOffsetRecord) -> TimeZone {
-    let minutes = (record.hour as i16 * 60) + record.minute as i16 + (record.second as i16 / 60);
-    TimeZone::OffsetMinutes(minutes * record.sign as i16)
-}
-
 #[inline]
 pub(crate) fn parse_identifier(source: &str) -> TemporalResult<TimeZone> {
     let mut cursor = source.chars().peekable();
-    if cursor.peek().is_some_and(is_ascii_sign) {
-        let offset_minutes = parse_offset(&mut cursor)?;
-        return Ok(TimeZone::OffsetMinutes(offset_minutes));
+    if let Some(offset) = parse_offset(&mut cursor)? {
+        return Ok(TimeZone::UtcOffset(UtcOffset(offset)));
     } else if parse_iana_component(&mut cursor) {
         return Ok(TimeZone::IanaIdentifier(source.to_owned()));
     }
     Err(TemporalError::range().with_message("Invalid TimeZone Identifier"))
 }
 
 #[inline]
-pub(crate) fn parse_offset(chars: &mut Peekable<Chars<'_>>) -> TemporalResult<i16> {
+pub(crate) fn parse_offset(chars: &mut Peekable<Chars<'_>>) -> TemporalResult<Option<i16>> {
+    if chars.peek().is_none() || !chars.peek().is_some_and(is_ascii_sign) {
+        return Ok(None);
+    }
+
     let sign = chars.next().map_or(1, |c| if c == '+' { 1 } else { -1 });
     // First offset portion
     let hours = parse_digit_pair(chars)?;
@@ -90,7 +79,7 @@ pub(crate) fn parse_offset(chars: &mut Peekable<Chars<'_>>) -> TemporalResult<i1
         None => 0,
     };
 
-    Ok((hours * 60 + minutes) * sign)
+    Ok(Some((hours * 60 + minutes) * sign))
 }
 
 fn parse_digit_pair(chars: &mut Peekable<Chars<'_>>) -> TemporalResult<i16> {