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 (عبرانی یا چینی کیلنڈرز میں leap مہینوں کے لیے بولین جھنڈا)۔ 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 فروری یا غیر leap سال میں 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 leap سالوں کو مدنظر رکھتا ہے۔

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 خود بخود موجودہ مہینے میں دنوں کی تعداد متعین کرتا ہے اور اگلے مہینے پر جاتا ہے۔ بار بار ہونے والے نوٹیفکیشنز کے لیے، Calendar کلید کے ساتھ enumerateDates یا 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:) کے ذریعے — leap سالوں کو مدنظر رکھنے کا واحد صحیح طریقہ۔ TimeInterval پر مبنی حساب (سیکنڈ / 31536000) 29 فروری کو پیدا ہونے والے لوگوں کے لیے غلطی دیتا ہے۔ Calendar صحیح طور پر طے کرتا ہے کہ آیا موجودہ سال میں سالگرہ ہوئی ہے اور صحیح عمر لوٹاتا ہے۔

سال اور مہینے کے مطابق گروپ بندی — تاریخ یا کیلنڈر اسکرینوں کے لیے ایک عام کام۔ DateComponents گروپ بندی کی کلید کے طور پر کام کرتا ہے: واقعہ کی تاریخ سے سال اور مہینہ نکالیں، ایک سٹرنگ کلید بنائیں، اور Dictionary(grouping:) کے ذریعے گروپ کریں۔ ڈسپلے کے لیے، مقامی مہینے کے نام کے لیے "LLLL yyyy" ٹیمپلیٹ کے ساتھ DateFormatter استعمال کریں۔