ISO8601DateFormatter: मुख्य अवधारणाएँ और ISO 8601 फ़ॉर्मेटिंग

ISO8601DateFormatter क्या है?

ISO8601DateFormatter Foundation में Formatter का एक विशेष उपवर्ग है जो Date और ISO 8601 फ़ॉर्मेट स्ट्रिंग के बीच द्विदिश रूपांतरण लागू करता है। ISO 8601 मानक (International Standard for the Representation of Dates and Times) तिथियों और समय के आदान-प्रदान के लिए अंतर्राष्ट्रीय फ़ॉर्मेट को परिभाषित करता है: 2024-07-21T14:30:00+00:00। DateFormatter के विपरीत, इस क्लास को dateFormat निर्दिष्ट करने की आवश्यकता नहीं है और यह दिए गए विकल्पों के आधार पर स्ट्रिंग संरचना को स्वचालित रूप से निर्धारित करता है।

ISO8601DateFormatter के DateFormatter पर मुख्य लाभ: लोकेल पर कोई निर्भरता नहीं (पार्सिंग किसी भी उपकरण पर समान रूप से काम करती है), सेकंड के अंशों के लिए अंतर्निहित समर्थन (किसी भी संख्या में दशमलव स्थानों के साथ) और पास किए गए विकल्पों के आधार पर स्वचालित फ़ॉर्मेट पहचान। क्लास Z-प्रत्यय (UTC पदनाम), +HH:mm फ़ॉर्मेट में समय क्षेत्र और कम सटीकता (समय के बिना केवल तिथि) को भी सही ढंग से संभालती है।

ISO विनिर्देश (ISO 8601-1:2019) के अनुसार, मानक सटीकता के चार स्तरों का समर्थन करता है: वर्ष (2024), वर्ष-माह (2024-07), पूर्ण तिथि (2024-07-21) और समय क्षेत्र के साथ तिथि-समय (2024-07-21T14:30:00+00:00)। ISO8601DateFormatter फ़ॉर्मेट विकल्पों के संयोजन के माध्यम से इन सभी स्तरों को कवर करता है, डेवलपर को मैन्युअल रूप से dateFormat स्ट्रिंग बनाने से मुक्त करता है।

Foundation में ISO8601DateFormatter कैसे काम करता है?

कार्य सिद्धांत ISO8601DateFormatter का बिटवाइज़ विकल्पों (formatOptions) के संयोजन पर आधारित है, जिनमें से प्रत्येक आउटपुट में एक विशिष्ट तिथि या समय घटक शामिल करता है। उदाहरण के लिए, .withFullDate विकल्प में वर्ष, माह और दिन शामिल है; .withTime में घंटे, मिनट और सेकंड शामिल हैं। विकल्पों को संयोजित करके, डेवलपर dateFormat स्ट्रिंग लिखे बिना वांछित सटीकता स्तर प्राप्त करता है।

आंतरिक रूप से, ISO8601DateFormatter पार्सिंग के लिए ICU लाइब्रेरी का उपयोग करता है, लेकिन निश्चित ISO 8601 नियमों के साथ। इसका मतलब है कि यह डिवाइस पर Locale और TimeZone सेटिंग्स को अनदेखा करता है — परिणाम हमेशा पूर्वानुमानित होता है। समय क्षेत्र सेट करने के लिए timeZone प्रॉपर्टी का उपयोग किया जाता है, जो डिफ़ॉल्ट रूप से UTC है। यदि timeZone को nil पर सेट किया गया है, तो डिवाइस का स्थानीय समय उपयोग किया जाता है।

विकल्पों का संयोजन: .withInternetDateTime .withFullDate, .withTime और .withTimeZone को संयोजित करने के बराबर है। मिलीसेकंड वाली स्ट्रिंग पार्स करने के लिए, .withFractionalSeconds जोड़ें। यह याद रखना महत्वपूर्ण है कि .withMilliseconds सेकंड के अंशों को तीन अंकों तक सीमित करता है, जबकि .withFractionalSeconds किसी भी सटीकता का समर्थन करता है — दशमलव बिंदु के बाद एक से नौ अंकों तक।

ISO 8601 फ़ॉर्मेट विकल्प

फ़ॉर्मेट विकल्प ISO8601DateFormatter के तीन समूहों में विभाजित हैं: तिथि घटक (withFullDate, withYear, withMonth, withDay, withWeekOfYear), समय घटक (withTime, withHours, withMinutes, withSeconds) और अतिरिक्त सेटिंग्स (withMilliseconds, withFractionalSeconds, withTimeZone, withColonSeparatorInTimeZone, withDashSeparatorInDate, withFullTime)। इन्हें संयोजित करके, आप लगभग कोई भी ISO 8601 उप-फ़ॉर्मेट प्राप्त कर सकते हैं।

मुख्य विकल्प संयोजन

• .withFullDate — केवल तिथि: 2024-07-21। YYYY-MM-DD स्ट्रिंग पार्स करने के लिए
• .withFullDate + .withTime — बिना समय क्षेत्र के तिथि और समय: 2024-07-21T14:30:00
• .withInternetDateTime — पूर्ण फ़ॉर्मेट: 2024-07-21T14:30:00Z या 2024-07-21T14:30:00+03:00
• .withInternetDateTime + .withFractionalSeconds — सेकंड के अंशों के साथ: 2024-07-21T14:30:00.123456+00:00
• .withFullDate + .withTime + .withTimeZone — tz में कोलन के बिना पूर्ण फ़ॉर्मेट: 2024-07-21T14:30:00+0300

महत्वपूर्ण बारीकी: .withFractionalSeconds और .withMilliseconds परस्पर अनन्य हैं — यदि दोनों सेट हैं, तो .withFractionalSeconds लागू होता है। सर्वर डेटा से मिलीसेकंड पार्स करने के लिए, .withFractionalSeconds अनुशंसित है, क्योंकि कई सर्वर तीन, छह या नौ अंकों के साथ सेकंड के अंश भेजते हैं, और .withFractionalSeconds किसी भी लंबाई को संभालता है।

import Foundation

// Configure ISO8601DateFormatter
let formatter = ISO8601DateFormatter()
formatter.timeZone = TimeZone(secondsFromGMT: 0)

// Different format option combinations
formatter.formatOptions = [.withFullDate]
let dateOnly = formatter.string(from: Date())
print("Date: \(dateOnly)")

formatter.formatOptions = [.withFullDate, .withTime]
let dateTime = formatter.string(from: Date())
print("DateTime: \(dateTime)")

formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
let full = formatter.string(from: Date())
print("Full: \(full)")

// Parse string with milliseconds
let serverString = "2024-07-21T14:30:00.123456+03:00"
if let parsed = formatter.date(from: serverString) {
    print("Parsed: \(parsed)")
}

Swift में ISO8601DateFormatter: कोड उदाहरण

मूल उपयोग ISO8601DateFormatter का एक इंस्टेंस बनाने, timeZone (सर्वर डेटा के लिए UTC अनुशंसित) और formatOptions सेट करने तक सीमित है, जिसके बाद फ़ॉर्मेटिंग के लिए string(from:) और पार्सिंग के लिए date(from:) कॉल किया जा सकता है। DateFormatter के विपरीत, Locale के बारे में चिंता करने की आवश्यकता नहीं है — क्लास क्षेत्रीय सेटिंग्स को अनदेखा करती है।

import Foundation

let formatter = ISO8601DateFormatter()

// Parse different ISO 8601 formats
let strings: [String] = [
    "2024-07-21T14:30:00Z",
    "2024-07-21T14:30:00+03:00",
    "2024-07-21T14:30:00.123Z",
    "2024-07-21"
]

for str in strings {
    if let autoParsed = formatter.date(from: str) {
        print("Parsed '\(str)': \(autoParsed)")
    } else {
        // Use withFullDate for date-only strings
        formatter.formatOptions = [.withFullDate]
        if let fallback = formatter.date(from: str) {
            print("Fallback parsed '\(str)': \(fallback)")
        }
        formatter.formatOptions = [.withInternetDateTime]
    }
}

// Serialize to RFC 3339 (GitHub API)
formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
let rfc3339 = formatter.string(from: Date())
print("RFC 3339: \(rfc3339)")

चर-लंबाई वाले सेकंड के अंशों वाली तिथियों को पार्स करना — कई आधुनिक API की विशेषता। सर्वर या तो 2024-07-21T14:30:00.123Z (3 अंक) या 2024-07-21T14:30:00.123456Z (6 अंक) भेज सकता है। .withFractionalSeconds विकल्प वाला ISO8601DateFormatter दोनों संस्करणों को सही ढंग से संभालेगा, जबकि dateFormat = "yyyy-MM-dd'T'HH:mm:ss.SSSZ" वाला DateFormatter केवल तीन-अंकीय मिलीसेकंड को संभालेगा।

import Foundation

let variantFormatter = ISO8601DateFormatter()
variantFormatter.formatOptions = [
    .withInternetDateTime,
    .withFractionalSeconds
]

// Different fractional second precision
let variants: [String] = [
    "2024-07-21T14:30:00.1Z",
    "2024-07-21T14:30:00.12Z",
    "2024-07-21T14:30:00.123Z",
    "2024-07-21T14:30:00.123456Z",
    "2024-07-21T14:30:00.123456789Z"
]

for variant in variants {
    if let parsed = variantFormatter.date(from: variant) {
        print("OK: \(variant) -> \(parsed)")
    } else {
        print("FAIL: \(variant)")
    }
}

// Use withMilliseconds (3 digits only)
variantFormatter.formatOptions = [
    .withInternetDateTime,
    .withMilliseconds
]
let milliParsed = variantFormatter.string(from: Date())
print("With milliseconds: \(milliParsed)")

सभी प्रकारों के पार्सिंग का परीक्षण: दिखाया गया कोड प्रदर्शित करता है कि .withFractionalSeconds वाला ISO8601DateFormatter 1 से 9 अंकों तक किसी भी लंबाई के सेकंड के अंशों को सफलतापूर्वक संभालता है। यह विभिन्न सर्वर प्लेटफ़ॉर्म के साथ संगतता के लिए महत्वपूर्ण है: .NET अक्सर 7 अंक (100-नैनोसेकंड टिक) उत्पन्न करता है, Python — 6, Java — संस्करण के आधार पर 3 या 9।

ISO 8601 के लिए DateFormatter से तुलना

DateFormatter भी ISO 8601 पार्स कर सकता है, लेकिन इसके लिए dateFormat, locale और timeZone की मैन्युअल सेटिंग की आवश्यकता होती है। मुख्य समस्या यह है कि DateFormatter Locale पर निर्भर करता है, और यदि en_US_POSIX सेट नहीं किया गया है, तो गैर-मानक तिथि प्रारूपों वाले क्षेत्रों के उपयोगकर्ताओं के लिए पार्सिंग विफल हो सकती है। ISO8601DateFormatter इस समस्या को आर्किटेक्चर स्तर पर हल करता है: यह Locale का उपयोग नहीं करता।

DateFormatter का उपयोग कब करें: यदि आपको तिथि को गैर-ISO 8601 फ़ॉर्मेट में फ़ॉर्मेट करने की आवश्यकता है (जैसे UI के लिए "21 जुलाई 2024") या यदि आपको iOS 9 और पुराने संस्करणों का समर्थन करने की आवश्यकता है। सर्वर-क्लाइंट तिथि आदान-प्रदान के सभी कार्यों के लिए, ISO8601DateFormatter का उपयोग करें — यह सुरक्षित, अधिक कुशल है और कम कोड की आवश्यकता होती है। ISO 8601 के लिए DateFormatter लोकेल और क्षेत्रीय सेटिंग्स से संबंधित संभावित बगों का एक स्रोत है।

DateFormatter से ISO8601DateFormatter में माइग्रेट करना: DateFormatter + dateFormat + locale + timeZone के निर्माण को ISO8601DateFormatter + formatOptions + timeZone से बदलें। date(from:) के माध्यम से स्ट्रिंग पार्सिंग अपरिवर्तित रहती है। पिछड़ी संगतता के लिए, आप DateFormatter पर फ़ॉलबैक के साथ #available(iOS 10, *) का उपयोग कर सकते हैं।

ISO 8601 पार्स करते समय सामान्य गलतियाँ

भूली हुई formatOptions सेटिंग के कारण फ़ॉर्मेटर डिफ़ॉल्ट मान — .withInternetDateTime का उपयोग करता है। यदि सर्वर बिना समय के तिथि भेजता है (2024-07-21), तो पार्सिंग nil लौटाएगी। हमेशा जाँचें कि formatOptions सर्वर से आने वाले सभी संभावित फ़ॉर्मेट को कवर करते हैं। परिवर्तनीय फ़ॉर्मेट वाले API के लिए, विभिन्न विकल्प संयोजनों के साथ फ़ॉलबैक प्रयासों का उपयोग करें।

withMilliseconds और withFractionalSeconds के बीच भ्रम — सेकंड के अंशों वाली तिथियों को पार्स करते समय एक सामान्य गलती। withMilliseconds दशमलव बिंदु के बाद ठीक 3 अंकों की अपेक्षा करता है। यदि सर्वर 6 अंक (माइक्रोसेकंड) भेजता है, तो withMilliseconds के साथ पार्सिंग विफल हो जाएगी। किसी भी संख्या में अंकों के साथ संगतता के लिए .withFractionalSeconds का उपयोग करें। .withFractionalSeconds iOS 13 में उपलब्ध हुआ; पुराने संस्करणों के लिए, dateFormat के साथ DateFormatter का उपयोग करें।

समय क्षेत्र को अनदेखा करना — एक और सामान्य समस्या। यदि सर्वर समय क्षेत्र (+03:00) के साथ तिथि भेजता है, और फ़ॉर्मेटर UTC पर सेट है, तो पार्सिंग विफल नहीं होगी, लेकिन परिणाम UTC में होगा। डेवलपर अक्सर उम्मीद करते हैं कि Date समय क्षेत्र को संरक्षित करेगा, लेकिन Date समय में एक पूर्ण क्षण है — यह समय क्षेत्र की जानकारी संग्रहीत नहीं करता। सही प्रदर्शन के लिए, समय क्षेत्र को अलग से सहेजें या सही timeZone के साथ ISO8601DateFormatter का उपयोग करें।

Apple फ़ोरम (2024) के अनुसार, ISO8601DateFormatter के बारे में लगभग 20% प्रश्न उस फ़ॉर्मेट से संबंधित हैं जहाँ सेकंड वैकल्पिक हैं। ISO 8601 मानक सेकंड के बिना फ़ॉर्मेट की अनुमति देता है: 2024-07-21T14:30+03:00। .withInternetDateTime वाला ISO8601DateFormatter इस फ़ॉर्मेट का समर्थन नहीं करता — इसे पार्स करने के लिए dateFormat = "yyyy-MM-dd'T'HH:mmZ" वाले DateFormatter की आवश्यकता होगी। संक्षिप्त समय फ़ॉर्मेट का उपयोग करने वाले API के साथ काम करते समय इस सीमा पर विचार करना महत्वपूर्ण है।