rdar://138592292 (🌏 [New Calendars] Date Calculation & API Support) (#3168) (#1409)

* rdar://138592292 (🌏 [New Calendars] Date Calculation & API Support)

- added support for "repeated day" (a.k.a. "adhika tithi" and "leap day") for use with Hindu lunisolar calendars
- updated leap-month-related checks to include Vietnamese, Dangi, and Hindu lunisolar calendars
- updated `availableCalendarIdentifiers` in `TestNSCalendar` to include new calendars

* Update FoundationPreview/Sources/FoundationEssentials/Calendar/DateComponents.swift



* Update FoundationPreview/Sources/FoundationEssentials/Calendar/DateComponents.swift



* added brackets for ifs

* made code that uses or depends on UCAL_IS_REPEATED_DAY conditional on FOUNDATION_FRAMEWORK

* made CalendarTests.test_isRepeatedDayProperty() conditional on FOUNDATION_FRAMEWORK

* removed incorrect uses of FOUNDATION_FRAMEWORK

* changed incorrect use of setLeapMonth to be setRepeatedDay

* added FIXME comments to the `#if FOUNDATION_FRAMEWORK` lines

* add all new calendars to the allCalendars list in CalendarTests

* replaced uses of array.contains() with direct identifier comparisons for efficiency

* fixed problem with finding the start of a repeated day

added test_isDateInSameDayAsRepeatedDay

enabled all the Hindu calendars for the test_isDateInToday, test_isDateInYesterday, and test_isDateInTomorrow now that the ICU and Foundation issues affecting them are fixed

* added support & tests for enumeratino with isRepeatedDay

* changed Calendar_Enumerate.swift to use _dateComponents() instead of component() for isRepeatedDay

backed out the change I'd made it DateComponents.swift to make component() work for isRepeatedDay

* fixed test_repeatedDay in TestNSCalendar.m

also moved it out of FIXED_152328671 conditional block and into FOUNDATION_FRAMEWORK conditional block

* changed minimumRangeOf and maximumRangeOf for .isLeapMonth and .isRepeatedDay

values based on those in kGregorianCalendarLimits in gregocal.cpp in ICU

* updated comment in highestSetUnit

* changed code to encode/decode repeated day as bool (was integer)

* changed value from true to YES

* renamed kCFCalendarUnitRepeatedDay to kCFCalendarUnitIsRepeatedDay

* changed date component comparisons to require exact match for isRepeatedDay

* changed isLunisolarCalendar check to do comparisons instead of using array.contains()

* added FOUNDATION_FRAMEWORK guard around two uses of UCAL_IS_REPEATED_DAY in _locked_setToFirstInstant()

* Adopt swift-testing

* added hasRepeatingMonths() function to Calendar

* changed range for repeated day

* refactored test_repeatedDay()

* added NSCalendarUnitIsRepeatedDay to NSCalendar.h

removed the FOUNDATION_FRAMEWORK guard from TestNSCalendar.m

* updated availability

* changed hasRepeatingMonths from func to var, used it in one more place

* added a test case for repeated days with a calendar that doesn't have any

---------

Co-authored-by: T Liu <[email protected]>

Author: cjchapman

Sources/FoundationEssentials/Calendar/Calendar.swift

@@ -248,6 +248,7 @@ public struct Calendar : Hashable, Equatable, Sendable {
         package static let timeZone = ComponentSet(rawValue: 1 << 15)
         package static let isLeapMonth = ComponentSet(rawValue: 1 << 16)
         package static let dayOfYear = ComponentSet(rawValue: 1 << 18)
+        package static let isRepeatedDay = ComponentSet(rawValue: 1 << 19)
 
         package var count: Int {
             rawValue.nonzeroBitCount
@@ -272,6 +273,7 @@ public struct Calendar : Hashable, Equatable, Sendable {
             if contains(.calendar) { result.insert(.calendar) }
             if contains(.timeZone) { result.insert(.timeZone) }
             if contains(.isLeapMonth) { result.insert(.isLeapMonth) }
+            if contains(.isRepeatedDay) { result.insert(.isRepeatedDay) }
             if contains(.dayOfYear) { result.insert(.dayOfYear) }
             return result
         }
@@ -293,8 +295,9 @@ public struct Calendar : Hashable, Equatable, Sendable {
             if self.contains(.yearForWeekOfYear) { return .yearForWeekOfYear }
             if self.contains(.nanosecond) { return .nanosecond }
 
-            // The algorithms that call this function assume that isLeapMonth counts as a 'highest unit set', but the order is after nanosecond.
+            // The algorithms that call this function assume that isLeapMonth and isRepeatedDay can count as 'highest unit set', but they are ordered after nanosecond.
             if self.contains(.isLeapMonth) { return .isLeapMonth }
+            if self.contains(.isRepeatedDay) { return .isRepeatedDay }
 
             // The calendar and timeZone properties do not count as a 'highest unit set', since they are not ordered in time like the others are.
             return nil
@@ -325,7 +328,8 @@ public struct Calendar : Hashable, Equatable, Sendable {
         case timeZone
         @available(macOS 14, iOS 17, tvOS 17, watchOS 10, *)
         case isLeapMonth
-        
+        @available(FoundationPreview 6.2, *)
+        case isRepeatedDay
         @available(macOS 15, iOS 18, tvOS 18, watchOS 11, *)
         case dayOfYear
 
@@ -349,6 +353,7 @@ public struct Calendar : Hashable, Equatable, Sendable {
             case .calendar: return ComponentSet.calendar.rawValue
             case .timeZone: return ComponentSet.timeZone.rawValue
             case .isLeapMonth: return ComponentSet.isLeapMonth.rawValue
+            case .isRepeatedDay: return ComponentSet.isRepeatedDay.rawValue
             }
         }
 
@@ -372,6 +377,7 @@ public struct Calendar : Hashable, Equatable, Sendable {
             case .calendar: "calendar"
             case .timeZone: "timeZone"
             case .isLeapMonth: "isLeapMonth"
+            case .isRepeatedDay: "isRepeatedDay"
             }
         }
     }
@@ -694,6 +700,11 @@ public struct Calendar : Hashable, Equatable, Sendable {
         return dc
     }
 
+    /// True if this is a lunisolar calendar that repeats the month number for a leap month, false otherwise.
+    var hasRepeatingMonths: Bool {
+        return identifier == .chinese || identifier == .dangi || identifier == .gujarati || identifier == .kannada || identifier == .marathi || identifier == .telugu || identifier == .vietnamese || identifier == .vikram
+    }
+
     /// Returns all the date components of a date, as if in a given time zone (instead of the `Calendar` time zone).
     ///
     /// The time zone overrides the time zone of the `Calendar` for the purposes of this calculation.
@@ -809,7 +820,7 @@ public struct Calendar : Hashable, Equatable, Sendable {
         }
 
         switch component {
-        case .calendar, .timeZone, .isLeapMonth:
+        case .calendar, .timeZone, .isLeapMonth, .isRepeatedDay:
             return .orderedSame
         case .day, .hour:
             // Day here so we don't assume that time zone fall back situations don't fall back into a previous day
@@ -902,6 +913,9 @@ public struct Calendar : Hashable, Equatable, Sendable {
         let comp1 = self.dateComponents(Set(units), from: date1)
         let comp2 = self.dateComponents(Set(units), from: date2)
 
+        // check if this is a lunisolar calendar that repeats the day number for a leap day
+        let hasRepeatingDays = identifier == .gujarati || identifier == .kannada || identifier == .marathi || identifier == .telugu || identifier == .vikram
+
         for c in units {
             guard let value1 = comp1.value(for: c), let value2 = comp2.value(for: c) else {
                 return fallback
@@ -913,7 +927,7 @@ public struct Calendar : Hashable, Equatable, Sendable {
                 return .orderedAscending
             }
 
-            if c == .month && identifier == .chinese {
+            if c == .month && hasRepeatingMonths {
                 let leap1 = comp1.isLeapMonth ?? false
                 let leap2 = comp2.isLeapMonth ?? false
 
@@ -924,6 +938,17 @@ public struct Calendar : Hashable, Equatable, Sendable {
                 }
             }
 
+            if c == .day && hasRepeatingDays {
+                let repeated1 = comp1.isRepeatedDay ?? false
+                let repeated2 = comp2.isRepeatedDay ?? false
+
+                if !repeated1 && repeated2 {
+                    return .orderedAscending
+                } else if repeated1 && !repeated2 {
+                    return .orderedDescending
+                }
+            }
+
             if component == c {
                 return .orderedSame
             }
@@ -1341,6 +1366,12 @@ public struct Calendar : Hashable, Equatable, Sendable {
             comp.isLeapMonth = _dateComponents(.month, from: date).isLeapMonth
         }
 
+        if components.isRepeatedDay != nil {
+            // `isRepeatedDay` isn't part of `actualUnits`, so we have to retrieve
+            // it separately
+            comp.isRepeatedDay = _dateComponents(.isRepeatedDay, from: date).isRepeatedDay
+        }
+
         // Apply an epsilon to comparison of nanosecond values
         if let nanosecond = comp.nanosecond, let tempNanosecond = tempComp.nanosecond {
             if labs(CLong(nanosecond - tempNanosecond)) > 500 {

Sources/FoundationEssentials/Calendar/Calendar_Enumerate.swift

@@ -149,7 +149,7 @@ extension DateComponents {
             guard calendar.value(v, isValidFor: .nanosecond) else { return false }
         }
 
-        if !hasAtLeastOneFieldSet && (isLeapMonth ?? false) {
+        if !hasAtLeastOneFieldSet && !(isLeapMonth ?? false) && !(isRepeatedDay ?? false) {
             return false
         }
 
@@ -217,6 +217,7 @@ extension DateComponents {
         if self.yearForWeekOfYear != nil { units.insert(.yearForWeekOfYear) }
         if self.dayOfYear != nil { units.insert(.dayOfYear) }
         if self.nanosecond != nil { units.insert(.nanosecond) }
+        if self.isRepeatedDay != nil { units.insert(.isRepeatedDay) }
         return units
     }
 
@@ -1205,7 +1206,6 @@ extension Calendar {
 
         // We need to check for leap* situations
         let isGregorianCalendar = identifier == .gregorian
-        let isChineseCalendar = identifier == .chinese
 
         if nextHighestUnit == .year || leapMonthMismatch {
             let desiredMonth = compsToMatch.month
@@ -1216,7 +1216,7 @@ extension Calendar {
                 return matchDate
             }
 
-            if isChineseCalendar {
+            if hasRepeatingMonths {
                 if leapMonthMismatch {
                     return try _adjustedDateForMismatchedChineseLeapMonth(start: start, searchingDate: searchingDate, matchDate: matchDate, matchingComponents: matchingComponents, compsToMatch: compsToMatch, direction: direction, matchingPolicy: matchingPolicy, repeatedTimePolicy: repeatedTimePolicy, isExactMatch: &isExactMatch, isLeapDay: &isLeapDay)
                 } else {
@@ -1624,8 +1624,7 @@ extension Calendar {
             return nil
         }
 
-        let isChineseCalendar = self.identifier == .chinese
-        let isLeapMonthDesired = isChineseCalendar && (components.isLeapMonth ?? false)
+        let isLeapMonthDesired = hasRepeatingMonths && (components.isLeapMonth ?? false)
 
         // After this point, result is at least startDate
         var result = startDate
@@ -1661,7 +1660,7 @@ extension Calendar {
             } while month != dateMonth
         }
 
-        // As far as we know, this is only relevant for the Chinese calendar.  In that calendar, the leap month has the same month number as the preceding month.
+        // This is relevant for the Chinese, Vietnamese, Korean, and Hindu lunisolar calendars.  In those calendars, the leap month has the same month number as the preceding month.
         // If we're searching forwards in time looking for a leap month, we need to skip the first occurrence we found of that month number because the first occurrence would not be the leap month; however, we only do this is if we are matching strictly. If we don't care about strict matching, we can skip this and let the caller handle it so it can deal with the approximations if necessary.
         if isLeapMonthDesired && strictMatching {
             // Check to see if we are already at a leap month
@@ -1956,14 +1955,27 @@ extension Calendar {
         return result
     }
 
+    internal func dayMatches(day: Int?, dateDay: Int,
+                             repeatedDay: Bool?, dateRepeatedDay: Bool) -> Bool {
+        // the intent here is to match day if the target component's day is not nil
+        // and to match isRepeatedDay if the target component's isRepeated day is not nil
+        let dayMatch = day == nil || day == dateDay
+        let repeatedMatch = repeatedDay == nil || repeatedDay == dateRepeatedDay
+        return dayMatch && repeatedMatch
+    }
+
     internal func dateAfterMatchingDay(startingAt startDate: Date, originalStartDate: Date, components comps: DateComponents, direction: SearchDirection) throws -> Date? {
-        guard let day = comps.day else {
+        let day = comps.day
+        let repeatedDay = comps.isRepeatedDay
+
+        guard day != nil || repeatedDay == true else {
             // Nothing to do
             return nil
         }
 
         var result = startDate
         var dateDay = component(.day, from: result)
+        var dateIsRepeatedDay = _dateComponents(.isRepeatedDay, from: result).isRepeatedDay ?? false
         let month = comps.month
 
         if month != nil && direction == .backward {
@@ -1978,12 +1990,13 @@ extension Calendar {
                     if let anotherFoundRange = dateInterval(of: .day, for: tempSearchDate) {
                         result = anotherFoundRange.start
                         dateDay = component(.day, from: result)
+                        dateIsRepeatedDay = _dateComponents(.isRepeatedDay, from: result).isRepeatedDay ?? false
                     }
                 }
             }
         }
 
-        if day != dateDay {
+        if !dayMatches(day: day, dateDay: dateDay, repeatedDay: repeatedDay, dateRepeatedDay: dateIsRepeatedDay)  {
             // The condition below keeps us from blowing past a month day by day to find a day which does not exist.
             // e.g. trying to find the 30th of February starting in January would go to March 30th if we don't stop here
             let originalMonth = component(.month, from: result)
@@ -2028,6 +2041,7 @@ extension Calendar {
                  }
 
                 dateDay = component(.day, from: tempSearchDate)
+                dateIsRepeatedDay = _dateComponents(.isRepeatedDay, from: tempSearchDate).isRepeatedDay ?? false
                 let dateMonth = component(.month, from: tempSearchDate)
 
                 try verifyAdvancingResult(tempSearchDate, previous: result, direction: direction)
@@ -2039,7 +2053,7 @@ extension Calendar {
                     break
                 }
 
-            } while day != dateDay
+            } while !dayMatches(day: day, dateDay: dateDay, repeatedDay: repeatedDay, dateRepeatedDay: dateIsRepeatedDay)
 
             // If we blew past a month in its entirety, roll back by a day to the very end of the month.
             if (advancedPastWholeMonth) {
@@ -2456,7 +2470,7 @@ extension Calendar.Component {
             return .yearForWeekOfYear
         case .quarter, .isLeapMonth, .month, .dayOfYear:
             return .year
-        case .day, .weekOfMonth, .weekdayOrdinal:
+        case .day, .weekOfMonth, .weekdayOrdinal, .isRepeatedDay:
             return .month
         case .weekday:
             return .weekOfMonth

Sources/FoundationEssentials/Calendar/Calendar_Gregorian.swift

@@ -350,8 +350,9 @@ internal final class _CalendarGregorian: _CalendarProtocol, @unchecked Sendable
         case .weekOfYear: 1..<53
         case .yearForWeekOfYear: 140742..<140743
         case .nanosecond: 0..<1000000000
-        // There is no leap month in Gregorian calendar
+        // There is no leap month or repeated day in Gregorian calendar
         case .isLeapMonth: 0..<1
+        case .isRepeatedDay: 0..<1
         case .dayOfYear: 1..<366
         case .calendar, .timeZone:
             nil
@@ -382,6 +383,7 @@ internal final class _CalendarGregorian: _CalendarProtocol, @unchecked Sendable
         case .yearForWeekOfYear: return 140742..<144684
         case .nanosecond: return 0..<1000000000
         case .isLeapMonth: return 0..<1
+        case .isRepeatedDay: return 0..<1
         case .dayOfYear: return 1..<367
         case .calendar, .timeZone:
             return nil
@@ -721,6 +723,8 @@ internal final class _CalendarGregorian: _CalendarProtocol, @unchecked Sendable
             return nil
         case .isLeapMonth:
             return nil
+        case .isRepeatedDay:
+            return nil
         }
     }
 
@@ -868,7 +872,7 @@ internal final class _CalendarGregorian: _CalendarProtocol, @unchecked Sendable
 
         var effectiveUnit = unit
         switch effectiveUnit {
-        case .calendar, .timeZone, .isLeapMonth:
+        case .calendar, .timeZone, .isLeapMonth, .isRepeatedDay:
             return nil
         case .era:
             if time < -63113904000.0 {
@@ -1447,7 +1451,7 @@ internal final class _CalendarGregorian: _CalendarProtocol, @unchecked Sendable
         let time = date.timeIntervalSinceReferenceDate
         var effectiveUnit = component
         switch effectiveUnit {
-        case .calendar, .timeZone, .isLeapMonth:
+        case .calendar, .timeZone, .isLeapMonth, .isRepeatedDay:
             return nil
         case .era:
             if time < -63113904000.0 {
@@ -2329,7 +2333,7 @@ internal final class _CalendarGregorian: _CalendarProtocol, @unchecked Sendable
             // TODO: This isn't supported in Calendar_ICU either. We should do it here though.
             return date
             // nothing to do for the below fields
-        case .calendar, .timeZone, .isLeapMonth:
+        case .calendar, .timeZone, .isLeapMonth, .isRepeatedDay:
             return date
         case .day, .dayOfYear, .hour, .minute, .second, .weekday, .weekdayOrdinal, .weekOfMonth, .weekOfYear, .nanosecond:
             // Handle below
@@ -2376,7 +2380,7 @@ internal final class _CalendarGregorian: _CalendarProtocol, @unchecked Sendable
             nanoseconds = Double(amount) / 1_000_000_000.0
             keepWallTime = false
 
-        case .era, .year, .month, .quarter, .yearForWeekOfYear, .calendar, .timeZone, .isLeapMonth:
+        case .era, .year, .month, .quarter, .yearForWeekOfYear, .calendar, .timeZone, .isLeapMonth, .isRepeatedDay:
             preconditionFailure("Should not reach")
         }
 
@@ -2731,7 +2735,7 @@ internal final class _CalendarGregorian: _CalendarProtocol, @unchecked Sendable
 
         case .nanosecond:
             return date + (Double(amount) * 1.0e-9)
-        case .calendar, .timeZone, .isLeapMonth:
+        case .calendar, .timeZone, .isLeapMonth, .isRepeatedDay:
             return date
         }
 
@@ -2896,7 +2900,7 @@ internal final class _CalendarGregorian: _CalendarProtocol, @unchecked Sendable
         }
 
         switch component {
-        case .calendar, .timeZone, .isLeapMonth:
+        case .calendar, .timeZone, .isLeapMonth, .isRepeatedDay:
             preconditionFailure("Invalid arguments")
 
         case .era:
@@ -3078,7 +3082,7 @@ internal final class _CalendarGregorian: _CalendarProtocol, @unchecked Sendable
                     dc.setValue(end > start ? Int(Int32.max) : Int(Int32.min), for: component)
                 }
 
-            case .timeZone, .isLeapMonth, .calendar:
+            case .timeZone, .isLeapMonth, .isRepeatedDay, .calendar:
                 // No leap month support needed here, since these are quantities, not values
                 break
             case .quarter: