[GregorianCalendar] Implement TimeZone support for date(from components: DateComponents) (swiftlang#311)

* [GregorianCalendar] Implement TimeZone support for `date(from components: DateComponents)`

To support DST-observing time zone, add a helper function for TimeZone to return the raw offset and DST offset individually so we can fine tune the behavior for the time during the skipped time frame and the repeated time frame.

* remove an accidental import

* Add non-compatibility tests

* Review feedback: Remove mention of "GMT" in the date argument

* Review feedback: Change the returning type of DST offset from Int to TimeInterval to be consistent with the existing dstOffset API

* Implement the required function for _TimeZoneBridged

* Fix a missing import

Author: itingliu

Sources/FoundationEssentials/Calendar/Calendar_Gregorian.swift

@@ -90,7 +90,6 @@ enum ResolvedDateComponents {
 
     init(dateComponents components: DateComponents) {
         var (year, month) = Self.yearMonth(forDateComponent: components)
-        let minMonth = 1
         let minWeekdayOrdinal = 1
         if let d = components.day {
             if components.yearForWeekOfYear != nil, let weekOfYear = components.weekOfYear {
@@ -125,7 +124,6 @@ enum ResolvedDateComponents {
     }
 
     init(preferComponent c: Calendar.Component, dateComponents components: DateComponents) {
-        let minMonth = 1
         let minWeekdayOrdinal = 1
         switch c {
         case .day:
@@ -464,7 +462,7 @@ internal final class _CalendarGregorian: _CalendarProtocol, @unchecked Sendable
     }
 
 
-    func date(from components: DateComponents, inTimeZone timeZone: TimeZone?, resolvedComponents: ResolvedDateComponents? = nil) -> Date? {
+    func date(from components: DateComponents, inTimeZone timeZone: TimeZone, resolvedComponents: ResolvedDateComponents? = nil) -> Date? {
 
         let resolvedComponents = resolvedComponents ?? ResolvedDateComponents(dateComponents: components)
 
@@ -498,20 +496,14 @@ internal final class _CalendarGregorian: _CalendarProtocol, @unchecked Sendable
             secondsInDay += Double(nanosecond) / Double(nano_coef)
         }
 
-        let timeZoneOffset: Int
-        if let timeZone = timeZone {
-            // TODO: Implement `TimeZone.secondsFromGMT(for date: Date)` to support DST
-            timeZoneOffset = timeZone.secondsFromGMT()
-        } else if let timeZone = components.timeZone {
-            timeZoneOffset = timeZone.secondsFromGMT()
-        } else {
-            timeZoneOffset = 0 // Assume GMT
-        }
+        // Rewind from Julian day, which starts at noon, back to midnight
+        var tmpDate = Date(julianDay: julianDay) - 43200 + secondsInDay
 
-        let timeInThisDay = secondsInDay - Double(timeZoneOffset)
+        // tmpDate now is in GMT. Adjust it back into local time zone
+        let (timeZoneOffset, dstOffset) = timeZone.rawAndDaylightSavingTimeOffset(for: tmpDate)
+        tmpDate = tmpDate - Double(timeZoneOffset) - dstOffset
 
-        // rewind from Julian day, which starts at noon, back to midnight
-        return Date(julianDay: julianDay) - 43200 + timeInThisDay
+        return tmpDate
     }
 
 

Sources/FoundationEssentials/TimeZone/TimeZone.swift

@@ -152,6 +152,10 @@ public struct TimeZone : Hashable, Equatable, Sendable {
         _tz.secondsFromGMT(for: date)
     }
 
+    internal func rawAndDaylightSavingTimeOffset(for date: Date) -> (rawOffset: Int, daylightSavingOffset: TimeInterval) {
+        _tz.rawAndDaylightSavingTimeOffset(for: date)
+    }
+
     /// Returns the abbreviation for the time zone at a given date.
     ///
     /// Note that the abbreviation may be different at different dates. For example, during daylight saving time the US/Eastern time zone has an abbreviation of "EDT." At other times, its abbreviation is "EST."

Sources/FoundationEssentials/TimeZone/TimeZone_Autoupdating.swift

@@ -51,6 +51,10 @@ internal final class _TimeZoneAutoupdating : _TimeZoneProtocol, Sendable {
         TimeZoneCache.cache.current.localizedName(for: style, locale: locale)
     }
 
+    func rawAndDaylightSavingTimeOffset(for date: Date) -> (rawOffset: Int, daylightSavingOffset: TimeInterval) {
+        TimeZoneCache.cache.current.rawAndDaylightSavingTimeOffset(for: date)
+    }
+
     var isAutoupdating: Bool {
         true
     }

Sources/FoundationEssentials/TimeZone/TimeZone_GMT.swift

@@ -47,6 +47,10 @@ package final class _TimeZoneGMT : _TimeZoneProtocol, @unchecked Sendable {
         0.0
     }
 
+    package func rawAndDaylightSavingTimeOffset(for date: Date) -> (rawOffset: Int, daylightSavingOffset: TimeInterval) {
+        (offset, 0)
+    }
+
     package func nextDaylightSavingTimeTransition(after date: Date) -> Date? {
         nil
     }

Sources/FoundationEssentials/TimeZone/TimeZone_Protocol.swift

@@ -17,6 +17,11 @@ package protocol _TimeZoneProtocol : AnyObject, Sendable, CustomDebugStringConve
 
     var identifier: String { get }
     func secondsFromGMT(for date: Date) -> Int
+
+    /// Essentially this is equivalent to adjusting `date` to this time zone using `rawOffset`, then passing the adjusted date to `daylightSavingTimeOffset(for: <adjusted date>)`.
+    /// This also handles the skipped time frame on DST start day differently from `daylightSavingTimeOffset(:)`, where dates in the skipped time frame are considered *not* in DST here, hence the DST offset would be 0.
+    func rawAndDaylightSavingTimeOffset(for date: Date) -> (rawOffset: Int, daylightSavingOffset: TimeInterval)
+
     func abbreviation(for date: Date) -> String?
     func isDaylightSavingTime(for date: Date) -> Bool
     func daylightSavingTimeOffset(for date: Date) -> TimeInterval

Sources/FoundationInternationalization/Calendar/Calendar_ICU.swift

@@ -1729,7 +1729,7 @@ internal final class _CalendarICU: _CalendarProtocol, @unchecked Sendable {
         let start = date - 48.0 * 60.0 * 60.0
 
 
-        guard let nextDSTTransition = _locked_nextDaylightSavingTimeTransition(startingAt: start, limit: start + 4 * 8600 * 1000.0) else {
+        guard let nextDSTTransition = _locked_nextDaylightSavingTimeTransition(startingAt: start, limit: start + 4 * 86400 * 1000.0) else {
             return nil
         }
 

Sources/FoundationInternationalization/TimeZone/TimeZone_Bridge.swift

@@ -82,7 +82,11 @@ internal final class _TimeZoneBridged: _TimeZoneProtocol, @unchecked Sendable {
     func localizedName(for style: TimeZone.NameStyle, locale: Locale?) -> String? {
         _timeZone.localizedName(style, locale: locale)
     }
-    
+
+    func rawAndDaylightSavingTimeOffset(for date: Date) -> (rawOffset: Int, daylightSavingOffset: TimeInterval) {
+        (_timeZone.secondsFromGMT(for: date), _timeZone.daylightSavingTimeOffset(for: date))
+    }
+
     func bridgeToNSTimeZone() -> NSTimeZone {
         _timeZone.copy() as! NSTimeZone
     }

Sources/FoundationInternationalization/TimeZone/TimeZone_GMTICU.swift

@@ -61,6 +61,10 @@ internal final class _TimeZoneGMTICU : _TimeZoneProtocol, @unchecked Sendable {
         nil
     }
 
+    func rawAndDaylightSavingTimeOffset(for date: Date) -> (rawOffset: Int, daylightSavingOffset: TimeInterval) {
+        (offset, 0)
+    }
+
     var debugDescription: String {
         "gmt icu offset \(offset)"
     }

Sources/FoundationInternationalization/TimeZone/TimeZone_ICU.swift

@@ -162,6 +162,26 @@ internal final class _TimeZoneICU: _TimeZoneProtocol, Sendable {
         }
     }
 
+    func rawAndDaylightSavingTimeOffset(for date: Date) -> (rawOffset: Int, daylightSavingOffset: TimeInterval) {
+        return lock.withLock {
+            guard let calendar = $0.calendar(identifier) else { return (0, 0) }
+            var rawOffset: Int32 = 0
+            var dstOffset: Int32 = 0
+            var status = U_ZERO_ERROR
+            let origMillis = ucal_getMillis(calendar, &status)
+            defer {
+                ucal_setMillis(calendar, origMillis, &status)
+            }
+            ucal_setMillis(calendar, date.udate, &status)
+
+            // If the date falls into the skipped time frame when transitioning into DST (e.g. 1:00 - 3:00 AM for PDT), we want to treat it as if DST hasn't happened yet. So, use UCAL_TZ_LOCAL_FORMER for nonExistingTimeOpt.
+            // If the date falls into the repeated time frame when DST ends (e.g. 1:00 - 2:00 AM for PDT), we want the first instance, i.e. the instance before turning back the clock. So, use UCAL_TZ_LOCAL_FORMER for duplicatedTimeOpt.
+            ucal_getTimeZoneOffsetFromLocal(calendar, UCAL_TZ_LOCAL_FORMER, UCAL_TZ_LOCAL_FORMER, &rawOffset, &dstOffset, &status)
+
+            return (Int(rawOffset / 1000), TimeInterval(dstOffset / 1000))
+        }
+    }
+
     func localizedName(for style: TimeZone.NameStyle, locale: Locale?) -> String? {
         let locID = locale?.identifier ?? ""
         return lock.withLock {

Tests/FoundationEssentialsTests/GregorianCalendarTests.swift

@@ -0,0 +1,121 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2017 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+#if canImport(TestSupport)
+import TestSupport
+#endif
+
+#if canImport(FoundationEssentials)
+@testable import FoundationEssentials
+#endif
+
+// Tests for _GregorianCalendar
+final class GregorianCalendarTests : XCTestCase {
+
+    func testDateFromComponents_DST() {
+        // The expected dates were generated using ICU Calendar
+
+        let tz = TimeZone(identifier: "America/Los_Angeles")!
+        let gregorianCalendar = _CalendarGregorian(identifier: .gregorian, timeZone: tz, locale: nil, firstWeekday: nil, minimumDaysInFirstWeek: nil, gregorianStartDate: nil)
+        func test(_ dateComponents: DateComponents, expected: Date, file: StaticString = #file, line: UInt = #line) {
+            let date = gregorianCalendar.date(from: dateComponents)!
+            XCTAssertEqual(date, expected, "DateComponents: \(dateComponents)", file: file, line: line)
+        }
+
+        test(.init(year: 2023, month: 10, day: 16), expected: Date(timeIntervalSince1970: 1697439600.0))
+        test(.init(year: 2023, month: 10, day: 16, hour: 1, minute: 34, second: 52), expected: Date(timeIntervalSince1970: 1697445292.0))
+        test(.init(year: 2023, month: 11, day: 6), expected: Date(timeIntervalSince1970: 1699257600.0))
+        test(.init(year: 2023, month: 3, day: 12), expected: Date(timeIntervalSince1970: 1678608000.0))
+        test(.init(year: 2023, month: 3, day: 12, hour: 1, minute: 34, second: 52), expected: Date(timeIntervalSince1970: 1678613692.0))
+        test(.init(year: 2023, month: 3, day: 12, hour: 2, minute: 34, second: 52), expected: Date(timeIntervalSince1970: 1678617292.0))
+        test(.init(year: 2023, month: 3, day: 12, hour: 3, minute: 34, second: 52), expected: Date(timeIntervalSince1970: 1678617292.0))
+        test(.init(year: 2023, month: 3, day: 13, hour: 0, minute: 0, second: 0), expected: Date(timeIntervalSince1970: 1678690800.0))
+        test(.init(year: 2023, month: 11, day: 5), expected: Date(timeIntervalSince1970: 1699167600.0))
+        test(.init(year: 2023, month: 11, day: 5, hour: 1, minute: 34, second: 52), expected: Date(timeIntervalSince1970: 1699173292.0))
+        test(.init(year: 2023, month: 11, day: 5, hour: 2, minute: 34, second: 52), expected: Date(timeIntervalSince1970: 1699180492.0))
+        test(.init(year: 2023, month: 11, day: 5, hour: 3, minute: 34, second: 52), expected: Date(timeIntervalSince1970: 1699184092.0))
+    }
+
+    func testDateFromComponents() {
+        // The expected dates were generated using ICU Calendar
+        let tz = TimeZone.gmt
+        let cal = _CalendarGregorian(identifier: .gregorian, timeZone: tz, locale: nil, firstWeekday: 1, minimumDaysInFirstWeek: 4, gregorianStartDate: nil)
+        func test(_ dateComponents: DateComponents, expected: Date, file: StaticString = #file, line: UInt = #line) {
+            let date = cal.date(from: dateComponents)
+            XCTAssertEqual(date, expected, "date components: \(dateComponents)", file: file, line: line)
+        }
+
+        test(.init(year: 1582, month: -7, weekday: 5, weekdayOrdinal: 0), expected: Date(timeIntervalSince1970: -12264739200.0))
+        test(.init(year: 1582, month: -3, weekday: 0, weekdayOrdinal: -5), expected: Date(timeIntervalSince1970: -12253680000.0))
+        test(.init(year: 1582, month: 5, weekday: -2, weekdayOrdinal: 3), expected: Date(timeIntervalSince1970: -12231475200.0))
+        test(.init(year: 1582, month: 5, weekday: 4, weekdayOrdinal: 6), expected: Date(timeIntervalSince1970: -12229747200.0))
+        test(.init(year: 2014, month: -4, weekday: -1, weekdayOrdinal: 4), expected: Date(timeIntervalSince1970: 1377216000.0))
+        test(.init(year: 2446, month: -1, weekday: -1, weekdayOrdinal: -1), expected: Date(timeIntervalSince1970: 15017875200.0))
+        test(.init(year: 2878, month: -9, weekday: -9, weekdayOrdinal: 1), expected: Date(timeIntervalSince1970: 28627603200.0))
+        test(.init(year: 2878, month: -5, weekday: 1, weekdayOrdinal: -6), expected: Date(timeIntervalSince1970: 28636934400.0))
+        test(.init(year: 2878, month: 7, weekday: -7, weekdayOrdinal: 8), expected: Date(timeIntervalSince1970: 28673740800.0))
+        test(.init(year: 2878, month: 11, weekday: -1, weekdayOrdinal: 4), expected: Date(timeIntervalSince1970: 28682121600.0))
+
+        test(.init(year: 1582, month: -7, day: 2), expected: Date(timeIntervalSince1970: -12264307200.0))
+        test(.init(year: 1582, month: 1, day: -1), expected: Date(timeIntervalSince1970: -12243398400.0))
+        test(.init(year: 1705, month: 6, day: -6), expected: Date(timeIntervalSince1970: -8350128000.0))
+        test(.init(year: 1705, month: 6, day: 3), expected: Date(timeIntervalSince1970: -8349350400.0))
+        test(.init(year: 1828, month: -9, day: -3), expected: Date(timeIntervalSince1970: -4507920000.0))
+        test(.init(year: 1828, month: 3, day: 0), expected: Date(timeIntervalSince1970: -4476038400.0))
+        test(.init(year: 1828, month: 7, day: 5), expected: Date(timeIntervalSince1970: -4465065600.0))
+        test(.init(year: 2074, month: -4, day: 2), expected: Date(timeIntervalSince1970: 3268857600.0))
+        test(.init(year: 2197, month: 5, day: -2), expected: Date(timeIntervalSince1970: 7173619200.0))
+        test(.init(year: 2197, month: 5, day: 1), expected: Date(timeIntervalSince1970: 7173878400.0))
+        test(.init(year: 2320, month: -2, day: -2), expected: Date(timeIntervalSince1970: 11036649600.0))
+        test(.init(year: 2320, month: 6, day: -3), expected: Date(timeIntervalSince1970: 11057644800.0))
+        test(.init(year: 2443, month: 7, day: 5), expected: Date(timeIntervalSince1970: 14942448000.0))
+        test(.init(year: 2812, month: 5, day: 4), expected: Date(timeIntervalSince1970: 26581651200.0))
+        test(.init(year: 2935, month: 6, day: -3), expected: Date(timeIntervalSince1970: 30465158400.0))
+        test(.init(year: 2935, month: 6, day: 3), expected: Date(timeIntervalSince1970: 30465676800.0))
+
+        test(.init(year: 1582, month: 5, weekOfMonth: -2), expected: Date(timeIntervalSince1970: -12232857600.0))
+        test(.init(year: 1582, month: 5, weekOfMonth: 4), expected: Date(timeIntervalSince1970: -12232857600.0))
+        test(.init(year: 1705, month: 2, weekOfMonth: 1), expected: Date(timeIntervalSince1970: -8359891200.0))
+        test(.init(year: 1705, month: 6, weekOfMonth: -3), expected: Date(timeIntervalSince1970: -8349523200.0))
+        test(.init(year: 1828, month: 7, weekOfMonth: 2), expected: Date(timeIntervalSince1970: -4465411200.0))
+        test(.init(year: 1828, month: 7, weekOfMonth: 5), expected: Date(timeIntervalSince1970: -4465411200.0))
+        test(.init(year: 1828, month: 11, weekOfMonth: 0), expected: Date(timeIntervalSince1970: -4454784000.0))
+        test(.init(year: 2197, month: 5, weekOfMonth: -2), expected: Date(timeIntervalSince1970: 7173878400.0))
+        test(.init(year: 2197, month: 5, weekOfMonth: 1), expected: Date(timeIntervalSince1970: 7173878400.0))
+        test(.init(year: 2320, month: 2, weekOfMonth: 1), expected: Date(timeIntervalSince1970: 11047536000.0))
+        test(.init(year: 2320, month: 6, weekOfMonth: -3), expected: Date(timeIntervalSince1970: 11057990400.0))
+        test(.init(year: 2443, month: -5, weekOfMonth: 4), expected: Date(timeIntervalSince1970: 14910566400.0))
+        test(.init(year: 2443, month: -1, weekOfMonth: -1), expected: Date(timeIntervalSince1970: 14921193600.0))
+        test(.init(year: 2443, month: 7, weekOfMonth: -1), expected: Date(timeIntervalSince1970: 14942102400.0))
+        test(.init(year: 2443, month: 7, weekOfMonth: 2), expected: Date(timeIntervalSince1970: 14942102400.0))
+        test(.init(year: 2812, month: -3, weekOfMonth: -3), expected: Date(timeIntervalSince1970: 26560396800.0))
+        test(.init(year: 2812, month: 5, weekOfMonth: 1), expected: Date(timeIntervalSince1970: 26581392000.0))
+        test(.init(year: 2812, month: 5, weekOfMonth: 4), expected: Date(timeIntervalSince1970: 26581392000.0))
+        test(.init(year: 2935, month: 6, weekOfMonth: 0), expected: Date(timeIntervalSince1970: 30465504000.0))
+
+        test(.init(weekOfYear: 20, yearForWeekOfYear: 1582), expected: Date(timeIntervalSince1970: -12231820800.0))
+        test(.init(weekOfYear: -25, yearForWeekOfYear: 1705), expected: Date(timeIntervalSince1970: -8378035200.0))
+        test(.init(weekOfYear: -4, yearForWeekOfYear: 1705), expected: Date(timeIntervalSince1970: -8365334400.0))
+        test(.init(weekOfYear: 3, yearForWeekOfYear: 1705), expected: Date(timeIntervalSince1970: -8361100800.0))
+        test(.init(weekOfYear: 0, yearForWeekOfYear: 1828), expected: Date(timeIntervalSince1970: -4481913600.0))
+        test(.init(weekOfYear: 25, yearForWeekOfYear: 1951), expected: Date(timeIntervalSince1970: -585187200.0))
+        test(.init(weekOfYear: -34, yearForWeekOfYear: 2074), expected: Date(timeIntervalSince1970: 3260736000.0))
+        test(.init(weekOfYear: 1, yearForWeekOfYear: 2074), expected: Date(timeIntervalSince1970: 3281904000.0))
+        test(.init(weekOfYear: 8, yearForWeekOfYear: 2074), expected: Date(timeIntervalSince1970: 3286137600.0))
+        test(.init(weekOfYear: -1, yearForWeekOfYear: 2443), expected: Date(timeIntervalSince1970: 14925513600.0))
+        test(.init(weekOfYear: 3, yearForWeekOfYear: 2566), expected: Date(timeIntervalSince1970: 18808934400.0))
+        test(.init(weekOfYear: 0, yearForWeekOfYear: 2689), expected: Date(timeIntervalSince1970: 22688726400.0))
+        test(.init(weekOfYear: -52, yearForWeekOfYear: 2812), expected: Date(timeIntervalSince1970: 26538883200.0))
+        test(.init(weekOfYear: 1, yearForWeekOfYear: 2935), expected: Date(timeIntervalSince1970: 30452544000.0))
+        test(.init(weekOfYear: 43, yearForWeekOfYear: 2935), expected: Date(timeIntervalSince1970: 30477945600.0))
+    }
+}