DateIntervalFormatter — تاریخ کے وقفہ فارمیٹنگ کے اصول

DateIntervalFormatter کیا ہے؟

DateIntervalFormatter Foundation میں Formatter کا ایک ذیلی طبقہ ہے جو DateInterval آبجیکٹ (دو تاریخوں کے درمیان ایک رینج) لیتا ہے اور اس رینج کو بیان کرنے والی ایک مقامی سٹرنگ واپس کرتا ہے۔ مثال کے طور پر، 21 سے 25 جولائی 2024 کی رینج کے لیے، نتیجہ ur_PK کے لیے «21–25 جولائی 2024» ہوگا۔ کلاس دہرائے جانے والے عناصر کو ذہانت سے گروپ کرتی ہے: اگر دونوں تاریخیں ایک ہی مہینے میں ہوں تو مہینے کا نام ایک بار دکھایا جاتا ہے۔

DateIntervalFormatter کی بنیادی قیمت رینج گرامر کا خودکار انتظام ہے۔ دستی فارمیٹنگ کے دوران، ایک ڈویلپر کو شروع/اختتام مہینہ/سال کا موازنہ کرنا، ایک جدا کار منتخب کرنا (ڈیش، «تک»، «bis»)، اور گردان کو سنبھالنا ہوگا۔ DateIntervalFormatter CLDR (Common Locale Data Repository) ڈیٹا کی بنیاد پر خود بخود یہ کرتا ہے، بین الاقوامی ایپلی کیشنز میں بگز کو کم کرتا ہے، خاص طور پر پیچیدہ گرامر والی زبانوں کے لیے۔

Unicode CLDR v44 (2024) کے مطابق، تاریخ کے وقفہ فارمیٹنگ کے قواعد زبانوں کے درمیان نمایاں طور پر مختلف ہوتے ہیں۔ جرمن «bis» (21.–25. Juli 2024) حرف جر استعمال کرتا ہے، فرانسیسی «au» (du 21 au 25 juillet 2024) استعمال کرتا ہے، جاپانی ہائفن (2024 Jul 21–25) استعمال کرتا ہے۔ DateIntervalFormatter ڈویلپر کی طرف سے اضافی کوڈ کے بغیر ان تمام تغیرات کو کور کرتا ہے۔

Foundation میں DateIntervalFormatter کیسے کام کرتا ہے؟

کام کرنے کا اصول DateIntervalFormatter کا ایک رینج بنانے والی دو تاریخوں کا تجزیہ کرنے اور مقامی سیٹنگز کو مدنظر رکھتے ہوئے بہترین سٹرنگ نمائندگی منتخب کرنے پر مبنی ہے۔ کلاس تاریخ کے اجزاء (سال، مہینہ، دن) کا موازنہ کرتی ہے اور گروپنگ کے فیصلے لیتی ہے: اگر سال ایک جیسا ہو تو ایک بار دکھایا جاتا ہے؛ اگر مہینہ ایک جیسا ہو تو ایک بار دکھایا جاتا ہے؛ اگر دن مختلف ہوں تو ایک دن کی رینج دکھائی جاتی ہے۔

گروپنگ منطق CLDR ٹیمپلیٹس کی بنیاد پر لاگو کی گئی ہے۔ فارمیٹر ہر تاریخ کے جزو (Calendar.Component: year, month, day) کی برابری کو بڑے سے چھوٹے کی ترتیب میں چیک کرتا ہے۔ ایک بار جب کوئی جزو مختلف ہوتا ہے، تو تمام چھوٹے اجزاء دونوں تاریخوں کے لیے دکھائے جاتے ہیں۔ مثال کے طور پر، 21–25 جولائی کے لیے: سال مماثل، مہینہ مماثل، دن مختلف → مہینہ ایک بار دکھایا جاتا ہے، دن ہر تاریخ کے لیے دکھائے جاتے ہیں۔

اہم نوٹ: DateIntervalFormatter API کے ذریعے جدا کار کو حسب ضرورت بنانے کی حمایت نہیں کرتا۔ جدا کار مقامی سیٹنگز سے طے ہوتا ہے اور اسے اوور رائیڈ نہیں کیا جا سکتا۔ اگر غیر معیاری جدا کار کی ضرورت ہو (مثال کے طور پر، «تک» کی بجائے «تک تک»)، تو آپ کو DateFormatter استعمال کرکے دستی طور پر تاریخیں فارمیٹ کرنی ہوں گی اور سٹرنگز کو حسب ضرورت جدا کار سے جوڑنا ہوگا۔

وقفہ فارمیٹنگ اسٹائل

DateIntervalFormatter دو سیٹ اسٹائل فراہم کرتا ہے: dateStyle اور timeStyle رینج کے ہر سرے کے لیے۔ یہ اسٹائل DateFormatter کی طرح کام کرتے ہیں: .none جزو کو چھپاتا ہے، .short ایک مختصر فارمیٹ دیتا ہے (21/07/2024)، .medium (21 جول 2024)، .long (21 جولائی 2024)، .full (اتوار، 21 جولائی 2024)۔ dateStyle اور timeStyle کو ملا کر تفصیل کی مختلف سطحیں حاصل کی جا سکتی ہیں۔

اسٹائل کے امتزاج کی مثالیں

• dateStyle = .medium, timeStyle = .none — صرف تاریخ: «21–25 جولائی 2024»
• dateStyle = .short, timeStyle = .short — تاریخ اور وقت: «21/07/2024، 14:30 – 25/07/2024، 16:45»
• dateStyle = .none, timeStyle = .short — صرف وقت: «14:30–16:45» (اگر تاریخیں ایک جیسی ہوں)
• dateStyle = .long, timeStyle = .none — لمبی تاریخ: «21–25 جولائی 2024»
• dateStyle = .full, timeStyle = .short — مکمل فارمیٹ: «اتوار، 21 جولائی 2024 – جمعرات، 25 جولائی 2024»

اہم: dateStyle اور timeStyle رینج کے دونوں سروں پر یکساں طور پر لاگو ہوتے ہیں۔ آپ شروع اور اختتام کے لیے مختلف اسٹائل مقرر نہیں کر سکتے (مثال کے طور پر، شروع کے لیے .medium اور اختتام کے لیے .short)۔ اگر مختلف اسٹائل کی ضرورت ہو تو آپ کو ہر تاریخ کو الگ DateFormatter سے فارمیٹ کرنا ہوگا اور نتائج کو جوڑنا ہوگا۔

import Foundation

let formatter = DateIntervalFormatter()

// مختلف اسٹائل کے امتزاج
let startDate = Date()
let endDate = Date().addingTimeInterval(345600) // +4 دن
let interval = DateInterval(start: startDate, end: endDate)

// صرف تاریخ، درمیانی فارمیٹ
formatter.dateStyle = .medium
formatter.timeStyle = .none
print("صرف تاریخ: \(formatter.string(from: interval))")

// وقت کے ساتھ مختصر فارمیٹ
formatter.dateStyle = .short
formatter.timeStyle = .short
print("وقت کے ساتھ مختصر: \(formatter.string(from: interval))")

// مکمل فارمیٹ
formatter.dateStyle = .full
formatter.timeStyle = .none
print("مکمل تاریخ: \(formatter.string(from: interval))")

Swift میں DateIntervalFormatter: مثالیں

بنیادی استعمال DateIntervalFormatter میں ایک انسٹینس بنانا، اسٹائل سیٹ کرنا اور string(from:) کال کرنا شامل ہے۔ یہ طریقہ DateInterval قبول کرتا ہے، جو start اور end خصوصیات والا ایک ڈھانچہ ہے۔ DateInterval دو Date اقدار سے بنایا جا سکتا ہے یا Duration (iOS 16+) سے شروع کیا جا سکتا ہے۔ فارمیٹنگ کے بعد، نتیجہ اضافی پروسیسنگ کے بغیر UI ڈسپلے کے لیے تیار ہے۔

import Foundation

let calendar = Calendar.current
let now = Date()

// مخصوص وقفہ کی مثالیں
let examples: [(title: String, start: Date, end: Date)] = [
    (
        "2-hour event",
        now,
        now.addingTimeInterval(7200)
    ),
    (
        "Week-long vacation",
        now,
        now.addingTimeInterval(604800)
    ),
    (
        "Cross-year period",
        calendar.date(from: DateComponents(
            year: 2024, month: 12, day: 25
        ))!,
        calendar.date(from: DateComponents(
            year: 2025, month: 1, day: 5
        ))!
    )
]

let intervalFormatter = DateIntervalFormatter()
intervalFormatter.dateStyle = .medium
intervalFormatter.timeStyle = .short

for (title, start, end) in examples {
    let interval = DateInterval(start: start, end: end)
    let result = intervalFormatter.string(from: interval)
    print("\(title): \(result)")
}

// Calendar کے ذریعے فارمیٹ (iOS 16+)
if let nextWeek = calendar.date(
    byAdding: .day, value: 7, to: now
) {
    let weekInterval = DateInterval(start: now, end: nextWeek)
    print("اگلے 7 دن: \(intervalFormatter.string(from: weekInterval))")
}

DateIntervalFormatter اور کیلنڈر بکنگ: بکنگ ایپلی کیشنز (ہوٹل، ٹکٹ) میں، تاریخ کے وقفے ایک اہم UI عنصر ہیں۔ DateIntervalFormatter بین سالانہ وقفوں کو درست طریقے سے سنبھالتا ہے (مثال کے طور پر، 28 دسمبر سے 3 جنوری)، ہر تاریخ کے لیے الگ الگ مہینہ اور سال گروپ کرتا ہے۔ ایسے منظرناموں کے لیے dateStyle = .medium اور timeStyle = .none استعمال کرنے کی سفارش کی جاتی ہے، جو وقت کے بغیر تاریخوں کے لیے سب سے زیادہ پڑھنے کے قابل فارمیٹ ہے۔

import Foundation

let formatter = DateIntervalFormatter()
formatter.dateStyle = .long
formatter.timeStyle = .none

// بکنگ کی مثالیں
struct Booking {
    let checkIn: Date
    let checkOut: Date

    var formattedInterval: String {
        let interval = DateInterval(start: checkIn, end: checkOut)
        return formatter.string(from: interval)
    }
}

let booking = Booking(
    checkIn: calendar.date(from: DateComponents(
        year: 2024, month: 7, day: 21
    ))!,
    checkOut: calendar.date(from: DateComponents(
        year: 2024, month: 7, day: 25
    ))!
)
print("بکنگ: \(booking.formattedInterval)")

// مختلف مقامی سیٹنگز کے ساتھ استعمال
let enFormatter = DateIntervalFormatter()
enFormatter.dateStyle = .medium
enFormatter.timeStyle = .none
enFormatter.locale = Locale(identifier: "en_US")
print("انگریزی: \(enFormatter.string(from: interval))")

DateInterval بمقابلہ DateIntervalFormatter: DateInterval ایک ڈھانچہ ہے جو تاریخ کی رینج (شروع اور اختتام) کی نمائندگی کرتا ہے۔ DateIntervalFormatter ایک فارمیٹر ہے جو اس ڈھانچے کو سٹرنگ میں تبدیل کرتا ہے۔ DateInterval contains(Date) چیک اور intersection(with:) بھی سپورٹ کرتا ہے، جو بکنگ منطق (تاریخ اوورلیپ چیک) کے لیے مفید ہے۔

تاریخ کے وقفوں کا مقامی کرنا

DateIntervalFormatter locale خاصیت کے ذریعے آؤٹ پٹ کو مقامی بناتا ہے۔ ڈیفالٹ طور پر، Locale.current استعمال ہوتا ہے، ڈیوائس کی مقامی سیٹنگ۔ وقفوں کو کسی اور زبان میں دکھانے کے لیے (مثال کے طور پر، اردو انٹرفیس کے ساتھ انگریزی مواد)، locale کو واضح طور پر سیٹ کریں۔ DateFormatter کے برعکس، DateIntervalFormatter کو سرور سائڈ ڈیٹا کے لیے locale سیٹ کرنے کی ضرورت نہیں ہے۔ یہ ہمیشہ اپنی داخلی CLDR پر مبنی گروپنگ منطق استعمال کرتا ہے۔

تاریخ کے وقفہ فارمیٹنگ میں لسانی فرق واحد تاریخوں کے مقابلے میں نمایاں طور پر زیادہ پیچیدہ ہیں۔ اردو «تک» حرف جر استعمال کرتی ہے: 21 سے 25 جولائی تک۔ انگریزی سادہ ڈیش استعمال کرتی ہے: Jul 21–25۔ فرانسیسی «au» استعمال کرتی ہے: du 21 au 25 juillet۔ DateIntervalFormatter ان تمام تغیرات کو کور کرتا ہے۔

import Foundation

let formatter = DateIntervalFormatter()
formatter.dateStyle = .medium
formatter.timeStyle = .none

let start = Date()
let end = Date().addingTimeInterval(259200) // +3 دن
let interval = DateInterval(start: start, end: end)

// مختلف مقامی سیٹنگز دکھائیں
let localeIds = ["ru_RU", "en_US", "de_DE", "fr_FR", "ja_JP", "zh_CN"]
for localeId in localeIds {
    formatter.locale = Locale(identifier: localeId)
    print("\(localeId): \(formatter.string(from: interval))")
}

// وقت کے وقفوں کے لیے مقامی کرنا
formatter.dateStyle = .none
formatter.timeStyle = .short

let todayStart = Date()
let todayEnd = Date().addingTimeInterval(3600)
let timeInterval = DateInterval(start: todayStart, end: todayEnd)

for localeId in ["ru_RU", "en_US", "de_DE"] {
    formatter.locale = Locale(identifier: localeId)
    print("\(localeId) وقت: \(formatter.string(from: timeInterval))")
}

مقامی کرنے کی خصوصیات: اردو کے لیے، DateIntervalFormatter لمبے فارمیٹس کے لیے «تک» استعمال کرتا ہے۔ مختصر فارمیٹس کے لیے، یہ ڈیش استعمال کرتا ہے۔ فارمیٹ کا انتخاب سیاق و سباق پر منحصر ہے: بکنگ کی فہرست کے لیے .medium استعمال کریں، تفصیلی منظر کے لیے .long یا .full استعمال کریں۔

دیگر تاریخ فارمیٹرز سے موازنہ

DateIntervalFormatter تاریخ کی حدود کو فارمیٹ کرنے کے مقام کو بھرتا ہے، جو دوسرے Foundation کلاسز کے ذریعے کور نہیں کیا جاتا۔ DateFormatter واحد تاریخوں کو فارمیٹ کرتا ہے، RelativeDateTimeFormatter رشتہ دار تاریخوں کو فارمیٹ کرتا ہے (پہلے/میں)، DateComponentsFormatter مدت کو فارمیٹ کرتا ہے (2 گھنٹے 30 منٹ)۔ ان میں سے ہر کلاس ایک مخصوص کام حل کرتی ہے اور ایک دوسرے کے بدلے استعمال نہیں کی جا سکتی۔

DateIntervalFormatter کب استعمال کریں: UI میں تاریخ کی حدود دکھانے کے لیے — ہوٹل بکنگ، ایونٹس، تاریخ کے مطابق فلٹرنگ، آپریشن ہسٹری۔ تاریخوں کے درمیان مدت کا حساب لگانے کے لیے، DateComponentsFormatter استعمال کریں، DateIntervalFormatter نہیں، کیونکہ مؤخر الذکر مدت دکھانے کے لیے ڈیزائن نہیں کیا گیا۔ DateFormatter صرف واحد تاریخوں کے لیے استعمال کیا جانا چاہیے، سٹرنگ جوڑ کے ذریعے دو فارمیٹ شدہ تاریخوں کو جوڑنے کے لیے نہیں، کیونکہ اس سے جدا کار کی مقامی کاری ختم ہو جاتی ہے۔

کنارے کی صورت: DateIntervalFormatter کھلے سرے والے وقفوں (اختتامی تاریخ کے بغیر) کو دکھانے کی حمایت نہیں کرتا۔ اگر رینج کا اختتام نامعلوم ہو (مثال کے طور پر، «21 جولائی سے»)، تو «سے» کے ساتھ DateFormatter استعمال کریں۔ نیز، DateIntervalFormatter مختلف دنوں کے لیے وقت کی تصریح کے ساتھ وقفوں کی حمایت نہیں کرتا۔ وقت ہر تاریخ پر الگ لاگو ہوتا ہے، جو مختصر وقفوں کے لیے بے کار لگ سکتا ہے۔