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 بتانے کی ضرورت نہیں ہے اور یہ دیے گئے آپشنز کی بنیاد پر سٹرنگ کی ساخت خود بخود متعین کرتی ہے۔

DateFormatter کے مقابلے میں ISO8601DateFormatter کے اہم فوائد: مقامی ترتیبات پر کوئی انحصار نہیں (پارکنگ کسی بھی آلے پر یکساں کام کرتی ہے)، سیکنڈ کے کسر کے لیے بلٹ ان سپورٹ (کسی بھی تعداد میں اعشاریہ مقامات کے ساتھ) اور پاس کردہ آپشنز کی بنیاد پر خودکار فارمیٹ کا پتہ لگانا۔ یہ کلاس 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)")

متغیر لمبائی کے سیکنڈ کسر والی تاریخوں کو پارس کرنا — بہت سے جدید APIs کی خصوصیت ہے۔ ایک سرور 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 سرور سے آنے والے تمام ممکنہ فارمیٹس کا احاطہ کرتا ہے۔ متغیر فارمیٹس والے APIs کے لیے، مختلف آپشن امتزاج کے ساتھ فال بیک کوششیں استعمال کریں۔

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 کی ضرورت ہوگی۔ مختصر وقت کے فارمیٹ استعمال کرنے والے APIs کے ساتھ کام کرتے وقت اس حد کو مدنظر رکھنا ضروری ہے۔