from_epoch_milliseconds_and_utc_offset and follow-ups (#6515)

Follow-ups to #6513

Author: sffc

components/time/src/zone/zone_name_timestamp.rs

@@ -21,15 +21,21 @@ use crate::{DateTime, Hour, Minute, Nanosecond, Second, Time};
 /// Internal intermediate type for interfacing with [`ZoneNameTimestamp`].
 #[derive(Debug, Copy, Clone)]
 struct ZoneNameTimestampParts {
+    /// Invariant: between MIN_QUARTER_HOURS_U32 and MAX_QUARTER_HOURS_U32 (inclusive).
+    /// This range covers almost 500 years.
     quarter_hours_since_local_unix_epoch: u32,
+    /// Currently the metadata is unused. It is reserved for future use, such as:
+    /// - A time zone UTC offset
+    /// - Extra bits for the epoch quarter-hours
+    /// - Bitmask to use the epoch quarter hour bits more efficiently
     metadata: u8,
 }
 
 impl ZoneNameTimestampParts {
     /// Recovers the DateTime from these parts.
     fn date_time(self) -> DateTime<Iso> {
         let qh = self.quarter_hours_since_local_unix_epoch;
-        // Note: the `as` casts below are trivially save because the rem_euclid is in range
+        // Note: the `as` casts below are trivially safe because the remainder is in range
         let (days, remainder) = (
             (qh / QUARTER_HOURS_IN_DAY_U32) as i64,
             (qh % QUARTER_HOURS_IN_DAY_U32) as u8,
@@ -71,7 +77,6 @@ impl ZoneNameTimestampParts {
                 0
             }
         };
-        let metadata = if metadata > 0x7F { 0 } else { metadata };
         ZoneNameTimestampParts {
             quarter_hours_since_local_unix_epoch: qh_u32,
             metadata,

ffi/capi/bindings/c/ZonedIsoDateTime.h

@@ -112,12 +112,32 @@ pub mod ffi {
             Box::new(TimeZone(self.id))
         }
 
+        /// Sets the datetime at which to interpret the time zone
+        /// for display name lookup.
+        ///
+        /// Notes:
+        ///
+        /// - If not set, the formatting datetime is used if possible.
+        /// - The constraints are the same as with `ZoneNameTimestamp` in Rust.
+        /// - Set to year 1000 or 9999 for a reference far in the past or future.
         #[diplomat::rust_link(icu::time::TimeZoneInfo::at_date_time_iso, FnInStruct)]
+        #[diplomat::rust_link(icu::time::zone::ZoneNameTimestamp, Struct, compact)]
         #[diplomat::rust_link(
             icu::time::TimeZoneInfo::with_zone_name_timestamp,
             FnInStruct,
             hidden
         )]
+        #[diplomat::rust_link(
+            icu::time::zone::ZoneNameTimestamp::from_date_time_iso,
+            FnInStruct,
+            hidden
+        )]
+        #[diplomat::rust_link(
+            icu::time::zone::ZoneNameTimestamp::far_in_future,
+            FnInStruct,
+            hidden
+        )] // documented
+        #[diplomat::rust_link(icu::time::zone::ZoneNameTimestamp::far_in_past, FnInStruct, hidden)] // documented
         pub fn at_date_time_iso(&self, date: &IsoDate, time: &Time) -> Box<Self> {
             Box::new(Self {
                 zone_name_timestamp: Some(icu_time::zone::ZoneNameTimestamp::from_date_time_iso(
@@ -131,6 +151,11 @@ pub mod ffi {
         }
 
         #[diplomat::rust_link(icu::time::TimeZoneInfo::zone_name_timestamp, FnInStruct)]
+        #[diplomat::rust_link(
+            icu::time::zone::ZoneNameTimestamp::to_date_time_iso,
+            FnInStruct,
+            hidden
+        )]
         pub fn zone_name_date_time(&self) -> Option<IsoDateTime> {
             let datetime = self.zone_name_timestamp?.to_date_time_iso();
             Some(IsoDateTime {

ffi/capi/bindings/cpp/icu4x/TimeZoneInfo.d.hpp

@@ -15,7 +15,7 @@ pub mod ffi {
     use crate::unstable::iana_parser::ffi::IanaParser;
     use crate::unstable::time::ffi::Time;
     use crate::unstable::timezone::ffi::TimeZoneInfo;
-    use crate::unstable::variant_offset::ffi::VariantOffsetsCalculator;
+    use crate::unstable::variant_offset::ffi::{UtcOffset, VariantOffsetsCalculator};
 
     /// An ICU4X ZonedDateTime object capable of containing a ISO-8601 date, time, and zone.
     #[diplomat::rust_link(icu::time::ZonedDateTime, Struct)]
@@ -49,6 +49,29 @@ pub mod ffi {
                 zone: Box::new(TimeZoneInfo::from(zone)),
             })
         }
+
+        /// Creates a new [`ZonedDateTime`] from milliseconds since epoch (timestamp) and a UTC offset.
+        ///
+        /// Note: [`ZonedDateTime`]s created with this constructor can only be formatted using localized offset zone styles.
+        #[diplomat::rust_link(
+            icu::time::ZonedDateTime::from_epoch_milliseconds_and_utc_offset,
+            FnInStruct
+        )]
+        #[diplomat::attr(all(supports = named_constructors, supports = fallible_constructors), named_constructor = "from_epoch_milliseconds_and_utc_offset")]
+        pub fn from_epoch_milliseconds_and_utc_offset(
+            epoch_milliseconds: i64,
+            utc_offset: &UtcOffset,
+        ) -> ZonedIsoDateTime {
+            let zdt = icu_time::ZonedDateTime::from_epoch_milliseconds_and_utc_offset(
+                epoch_milliseconds,
+                utc_offset.0,
+            );
+            ZonedIsoDateTime {
+                date: Box::new(IsoDate(zdt.date)),
+                time: Box::new(Time(zdt.time)),
+                zone: Box::new(TimeZoneInfo::from(utc_offset.0)),
+            }
+        }
     }
 
     /// An ICU4X DateTime object capable of containing a date, time, and zone for any calendar.

ffi/capi/bindings/cpp/icu4x/ZonedIsoDateTime.d.hpp

@@ -15,12 +15,6 @@
 
 
 fixed_decimal::Decimal::new#FnInTypedef
-icu::time::ZonedDateTime::from_epoch_milliseconds_and_utc_offset#FnInStruct
-icu::time::zone::ZoneNameTimestamp#Struct
-icu::time::zone::ZoneNameTimestamp::far_in_future#FnInStruct
-icu::time::zone::ZoneNameTimestamp::far_in_past#FnInStruct
-icu::time::zone::ZoneNameTimestamp::from_date_time_iso#FnInStruct
-icu::time::zone::ZoneNameTimestamp::to_date_time_iso#FnInStruct
 icu_provider_adapters::fork::ForkByMarkerProvider::inner#FnInTypedef
 icu_provider_adapters::fork::ForkByMarkerProvider::inner_mut#FnInTypedef
 icu_provider_adapters::fork::ForkByMarkerProvider::into_inner#FnInTypedef