DateComponents — यह क्या है, कैलेंडर घटक और NSCalendar

DateComponents क्या है?

DateComponents एक Foundation मान-प्रकार है जो कैलेंडर समय घटकों को संग्रहीत करने के लिए डिज़ाइन किया गया है। प्रत्येक घटक एक वैकल्पिक Int फ़ील्ड द्वारा दर्शाया गया है: year, month, day, hour, minute, second, nanosecond, weekday, weekOfMonth, weekOfYear, quarter, yearForWeekOfYear और अन्य।

Date से मुख्य अंतर कैलेंडर बंधन है। Date पूर्ण समय (संदर्भ तिथि से सेकंड की संख्या) संग्रहीत करता है, जबकि DateComponents एक मानव-पठनीय प्रतिनिधित्व है जो केवल एक विशिष्ट Calendar के संदर्भ में अर्थपूर्ण है। एक ही Date को विभिन्न कैलेंडर और समय क्षेत्रों में अलग-अलग DateComponents द्वारा दर्शाया जा सकता है।

DateComponents एक स्वतंत्र समय प्रकार नहीं है, बल्कि एक डेटा कंटेनर है। DateComponents को तिथि के रूप में व्याख्या करने के लिए एक Calendar की आवश्यकता है जो समझता है कि घटक कैलेंडर प्रणाली से कैसे संबंधित हैं। Calendar.dateComponents(from: Date) घटक निष्कर्षण करता है, Calendar.date(from: DateComponents) विपरीत असेंबली करता है।

फ़ील्ड की वैकल्पिकता

DateComponents का प्रत्येक फ़ील्ड वैकल्पिक है (Int?), जो आंशिक तिथियों के साथ काम करने के लिए मौलिक है। यदि केवल वर्ष और महीना निर्दिष्ट किया गया है, तो Calendar लुप्त फ़ील्ड को डिफ़ॉल्ट मानों से भरता है: दिन = 1, घंटा = 0, मिनट = 0। यह अवधि प्रारंभ तिथियाँ बनाने के लिए सुविधाजनक है — केवल प्रासंगिक घटकों को निर्दिष्ट करने की आवश्यकता है।

== ऑपरेटर के माध्यम से DateComponents की तुलना करते समय, केवल निर्दिष्ट (गैर-nil) फ़ील्ड की तुलना की जाती है। दो DateComponents संरचनाएँ दोनों वर्ष 2026 के साथ लेकिन अलग-अलग महीनों के साथ भिन्न मानी जाती हैं। NSObjectProtocol से isEqual DateComponents पर लागू नहीं होता है — DateComponents NSObject से विरासत नहीं लेता है।

दिनांक घटक: वर्ष, महीना, दिन

मुख्य फ़ील्ड DateComponents में year, month, day, hour, minute, second, nanosecond शामिल हैं। प्रत्येक फ़ील्ड संबंधित इकाई में एक संख्यात्मक मान संग्रहीत करता है: वर्ष — 2026, महीना — 1..12, दिन — 1..31, घंटा — 0..23, मिनट — 0..59, सेकंड — 0..59। नैनोसेकंड 0 से 999999999 तक हो सकते हैं।

सप्ताह फ़ील्ड — weekday (1..7, जहाँ 1 = ग्रेगोरियन कैलेंडर में रविवार), weekOfMonth, weekOfYear। ये फ़ील्ड Calendar पर निर्भर करते हैं और इसके संदर्भ के बाहर उनका कोई अर्थ नहीं है। weekday कैलेंडर की firstWeekday सेटिंग पर निर्भर करता है: रूसी लोकेल में सप्ताह सोमवार से शुरू होता है (ग्रेगोरियन प्रणाली में weekday = 2), जबकि अमेरिकी लोकेल में रविवार से शुरू होता है (weekday = 1)।

विशेष फ़ील्ड — quarter (1..4), yearForWeekOfYear (वह वर्ष जिससे सप्ताह संबंधित है), isLeapMonth (हिब्रू या चीनी कैलेंडर में अधिक मास के लिए बूलियन फ़्लैग)। calendar और timeZone फ़ील्ड उन संबंधित ऑब्जेक्टों के संदर्भ संग्रहीत करते हैं जिनके साथ संरचना बनाई गई थी।

Calendar.dateComponents के माध्यम से घटक निकालते समय, प्रदर्शन के लिए केवल आवश्यक फ़ील्ड का अनुरोध करना महत्वपूर्ण है। Calendar सभी अनुरोधित फ़ील्ड को एक ही पास में निकालता है — यह प्रत्येक फ़ील्ड के लिए अलग-अलग Calendar.component को कॉल करने की तुलना में काफी तेज़ है।

DateComponents बनाना

DateComponents आरंभीकरण — सबसे सरल तरीका: एक खाली संरचना बनाएँ और आवश्यक फ़ील्ड भरें। सभी अनिर्दिष्ट फ़ील्ड स्वचालित रूप से nil प्राप्त करते हैं। आंशिक घटकों से बनाई गई तिथि आरंभीकरण पर मान्य नहीं की जाती है — त्रुटि केवल Calendar के माध्यम से Date में रूपांतरण पर हो सकती है।

आरंभक DateComponents(calendar:timeZone:era:year:month:day:hour:minute:second:nanosecond:weekday:…) एक ही कॉल में सभी फ़ील्ड सेट करने की अनुमति देता है। यह आरंभक तैयार मानों से पूर्ण तिथि बनाने के लिए सुविधाजनक है, लेकिन पठनीयता के कारण शायद ही कभी 5-6 से अधिक तर्कों के साथ उपयोग किया जाता है।

Calendar.dateComponents(_:from:) — मौजूदा Date से DateComponents प्राप्त करने का प्राथमिक तरीका। दूसरा तर्क निकाले जाने वाले घटकों का सेट है। Calendar समय क्षेत्र को ध्यान में रखते हुए कैलेंडर गणना करता है और केवल अनुरोधित फ़ील्ड के साथ एक संरचना लौटाता है; शेष फ़ील्ड nil रहते हैं।

import Foundation

// फ़ील्ड आरंभक के माध्यम से निर्माण
var components = DateComponents()
components.year = 2026
components.month = 7
components.day = 21

// Date से निष्कर्षण
let now = Date()
let extracted = Calendar.current.dateComponents(
    [.year, .month, .day],
    from: now
)
print("Today: \(extracted.day!).\(extracted.month!).\(extracted.year!)")

// विस्तारित आरंभक के माध्यम से निर्माण
let birthday = DateComponents(
    calendar: Calendar.current,
    year: 1990, month: 5, day: 15
)

DateComponents को मैन्युअल रूप से फ़ील्ड सेट करके बनाते समय, Date में रूपांतरण से पहले हमेशा Calendar की जाँच करें। date(from:) रूपांतरण करते समय, Calendar nil लौटा सकता है यदि घटक एक अस्तित्वहीन तिथि बनाते हैं — उदाहरण के लिए, 31 फरवरी या गैर-लीप वर्ष में 30 फरवरी। तिथि सत्यापन Calendar की जिम्मेदारी है, DateComponents की नहीं।

DateComponents को Date में बदलना

Calendar.date(from:) — DateComponents को Date में बदलने की प्राथमिक विधि। Calendar अपने कैलेंडर और समय क्षेत्र के अनुसार घटकों की व्याख्या करता है। यदि कुछ फ़ील्ड सेट नहीं हैं (nil), Calendar डिफ़ॉल्ट मानों का उपयोग करता है: दिन = 1, घंटा = 0, मिनट = 0, सेकंड = 0।

विधि एक वैकल्पिक Date लौटाती है — nil तब होता है जब घटक एक-दूसरे का खंडन करते हैं या एक अमान्य तिथि बनाते हैं। nil के सामान्य कारण: अस्तित्वहीन तिथि (32 जनवरी, 29 फरवरी 2023), विरोधाभासी फ़ील्ड (एक ही सेट में weekday=1, day=5), दिए गए कैलेंडर के लिए असंभव वर्ष (ग्रेगोरियन कैलेंडर में वर्ष 0)।

timeZone के साथ DateComponents — यदि DateComponents में timeZone है, तो Calendar रूपांतरण के दौरान इसका उपयोग करता है। यदि timeZone निर्दिष्ट नहीं है, तो Calendar अपनी वर्तमान timeZone का उपयोग करता है। यदि Calendar.timeZone तिथि के अपेक्षित समय क्षेत्र से मेल नहीं खाता है, तो परिणाम कई घंटों तक भिन्न हो सकता है — सुनिश्चित करें कि timeZone किसी एक ऑब्जेक्ट में स्पष्ट रूप से सेट है।

let calendar = Calendar(identifier: .gregorian)

// DateComponents से Date बनाना
var comps = DateComponents()
comps.year = 2026
comps.month = 12
comps.day = 25
comps.hour = 10

if let date = calendar.date(from: comps) {
    print("Christmas: \(date)")
}

// timeZone निर्दिष्ट करके बनाना
calendar.timeZone = TimeZone(identifier: "UTC")!
let utcComps = DateComponents(
    calendar: calendar, year: 2026, month: 7, day: 21,
    hour: 12
)
let utcDate = calendar.date(from: utcComps)!

Calendar.dateComponents तिथि अंतर के लिए — DateComponents का एक और उपयोग मामला। Calendar.dateComponents([.year, .month, .day], from: Date(), to: futureDate) दो तिथियों के बीच वर्षों, महीनों और दिनों में अंतर लौटाता है। यह TimeInterval को एक वर्ष में सेकंड की संख्या से विभाजित करने के बजाय आयु की गणना करने का सही तरीका है, क्योंकि Calendar लीप वर्षों को ध्यान में रखता है।

Calendar और DateComponents

Calendar — केंद्रीय वर्ग जो DateComponents के साथ काम करता है। तिथियों को निकालने, असेंबल करने और तुलना करने के सभी संचालन Calendar के माध्यम से होते हैं। Calendar के बिना, DateComponents बिना किसी लौकिक अर्थ के संख्याओं का एक सेट मात्र है। Calendar घटकों को उनकी व्याख्या देता है: यह निर्धारित करता है कि महीना 2 फरवरी है, और weekday 2 सोमवार है।

Calendar.nextDate और Calendar.enumerateDates — DateComponents पर आधारित दो विधियाँ। nextDate(after: Date(), matching: DateComponents) निर्दिष्ट घटकों से मेल खाने वाली अगली तिथि ढूँढता है — उदाहरण के लिए, आज के बाद अगला सोमवार। enumerateDates(startingAfter:matching:matchingPolicy:using:) निर्दिष्ट सीमा तक पैटर्न से मेल खाने वाली सभी तिथियों पर पुनरावृति करता है।

Calendar.dateInterval — एक विधि जो निर्दिष्ट घटक के लिए DateInterval लौटाती है। dateInterval(of: .month, for: Date()) वर्तमान महीने की शुरुआत और अंत लौटाता है। आंतरिक रूप से, यह विधि अवधि सीमाएँ खोजने के लिए DateComponents का उपयोग करती है: यह महीने के पहले और अंतिम दिन के साथ DateComponents बनाती है और उन्हें Calendar के माध्यम से Date में बदलती है।

let calendar = Calendar.current

// अगला सोमवार
let nextMonday = calendar.nextDate(
    after: Date(),
    matching: DateComponents(weekday: 2),
    matchingPolicy: .nextTime
)!

// दिनों में तिथियों के बीच अंतर
let diff = calendar.dateComponents(
    [.day], from: Date(), to: nextMonday
)

// महीने की सीमा
let monthInterval = calendar.dateInterval(
    of: .month, for: Date()
)!
let startOfMonth = monthInterval.start
let endOfMonth = monthInterval.end

MatchingPolicy — DateComponents के साथ काम करते समय Calendar विधियों का एक महत्वपूर्ण पैरामीटर। strictPolicy को सभी घटकों के सटीक मिलान की आवश्यकता होती है, nextTimePolicy अगले समय-वार मिलान का चयन करता है, nextTimePreservingSmallerComponents स्रोत तिथि से छोटे घटकों (मिनट, सेकंड) को संरक्षित करता है। नीति का चुनाव तिथि खोज के परिणाम को प्रभावित करता है, विशेष रूप से डेलाइट सेविंग टाइम संक्रमण के माध्यम से बदलाव करते समय।

DateComponents उदाहरण

आइए एक एप्लिकेशन में DateComponents के व्यावहारिक उपयोग के मामलों का पता लगाएँ। प्रत्येक उदाहरण एक विशिष्ट कार्य प्रदर्शित करता है जो एक iOS डेवलपर को कैलेंडर तिथियों के साथ काम करते समय सामना करना पड़ता है।

प्रत्येक महीने के पहले दिन अनुस्मारक

Calendar.nextDate DateComponents(day: 1) के साथ अगले महीने का पहला दिन ढूँढता है। Calendar स्वचालित रूप से वर्तमान महीने में दिनों की संख्या निर्धारित करता है और अगले पर जाता है। आवर्ती सूचनाओं के लिए, enumerateDates या Calendar कुंजी के साथ Combine.Timer का उपयोग करें।

func firstDayOfNextMonth(from date: Date) -> Date {
    let calendar = Calendar.current
    let comps = DateComponents(day: 1)
    return calendar.nextDate(
        after: date,
        matching: comps,
        matchingPolicy: .nextTime
    )!
}

// वर्षों में आयु की गणना
func ageInYears(from birthDate: Date) -> Int {
    let calendar = Calendar.current
    let ageComponents = calendar.dateComponents(
        [.year], from: birthDate, to: Date()
    )
    return ageComponents.year ?? 0
}

// वर्ष और महीने के अनुसार घटनाओं का समूहीकरण
func groupEventsByMonth(_ events: [Event]) -> [String: [Event]] {
    let calendar = Calendar.current
    return Dictionary(grouping: events) { event in
        let comps = calendar.dateComponents(
            [.year, .month], from: event.date
        )
        return "\(comps.year!)-\(comps.month!)"
    }
}

आयु गणना Calendar.dateComponents([.year], from:to:) के माध्यम से — लीप वर्षों को ध्यान में रखने वाला एकमात्र सही तरीका। TimeInterval-आधारित गणना (सेकंड / 31536000) 29 फरवरी को जन्मे लोगों के लिए त्रुटि देती है। Calendar सही ढंग से निर्धारित करता है कि वर्तमान वर्ष में जन्मदिन हुआ है या नहीं और सटीक आयु लौटाता है।

वर्ष और महीने के अनुसार समूहीकरण — इतिहास या कैलेंडर स्क्रीन के लिए एक सामान्य कार्य। DateComponents समूहीकरण कुंजी के रूप में कार्य करता है: घटना तिथि से वर्ष और महीना निकालें, एक स्ट्रिंग कुंजी बनाएँ, और Dictionary(grouping:) के माध्यम से समूहित करें। प्रदर्शन के लिए, स्थानीयकृत महीने के नाम के लिए "LLLL yyyy" टेम्पलेट के साथ DateFormatter का उपयोग करें।