DateComponents — takvim bileşenleri ve NSCalendar nedir

DateComponents nedir?

DateComponents, takvim zamanı bileşenlerini saklamak için tasarlanmış bir Foundation değer türüdür. Her bileşen isteğe bağlı bir Int alanıyla temsil edilir: year, month, day, hour, minute, second, nanosecond, weekday, weekOfMonth, weekOfYear, quarter, yearForWeekOfYear ve diğerleri.

Date'ten temel farkı takvim bağlantısıdır. Date mutlak zamanı (referans tarihten itibaren saniye sayısı) saklarken, DateComponents yalnızca belirli bir Calendar bağlamında anlamlı olan insan tarafından okunabilir bir temsildir. Aynı Date, farklı takvimlerde ve saat dilimlerinde farklı DateComponents ile temsil edilebilir.

DateComponents bağımsız bir zaman türü değildir, bir veri kapsayıcısıdır. DateComponents'i bir tarih olarak yorumlamak için, bileşenlerin takvim sistemiyle nasıl ilişkili olduğunu anlayan bir Calendar gereklidir. Calendar.dateComponents(from: Date) bileşen çıkarma işlemini gerçekleştirir, Calendar.date(from: DateComponents) ters birleştirme işlemini gerçekleştirir.

Alanların isteğe bağlılığı

DateComponents'in her alanı isteğe bağlıdır (Int?), bu kısmi tarihlerle çalışmak için temeldir. Yalnızca yıl ve ay belirtilirse, Calendar eksik alanları varsayılan değerlerle doldurur: gün = 1, saat = 0, dakika = 0. Bu, dönem başlangıç tarihleri oluşturmak için kullanışlıdır — yalnızca ilgili bileşenleri belirtmek yeterlidir.

DateComponents'i == operatörüyle karşılaştırırken, yalnızca belirtilen (nil olmayan) alanlar karşılaştırılır. Her ikisi de yılı 2026 olan ancak ayları farklı olan iki DateComponents yapısı farklı kabul edilir. NSObjectProtocol'deki isEqual, DateComponents için geçerli değildir — DateComponents, NSObject'ten miras almaz.

Tarih bileşenleri: yıl, ay, gün

Ana alanlar DateComponents şunları içerir: year, month, day, hour, minute, second, nanosecond. Her alan ilgili birimde sayısal bir değer saklar: yıl — 2026, ay — 1..12, gün — 1..31, saat — 0..23, dakika — 0..59, saniye — 0..59. nanosaniye 0 ile 999999999 arasında değişebilir.

Hafta alanları — weekday (1..7, Gregoryen takvimde 1 = Pazar), weekOfMonth, weekOfYear. Bu alanlar Calendar'a bağlıdır ve bağlamı dışında bir anlam taşımazlar. weekday, takvimin firstWeekday ayarına bağlıdır: Rus yerel ayarında hafta Pazartesi günü başlar (Gregoryen sistemde weekday = 2), Amerikan yerel ayarında ise Pazar günü başlar (weekday = 1).

Özelleşmiş alanlar — quarter (1..4), yearForWeekOfYear (haftanın ait olduğu yıl), isLeapMonth (İbrani veya Çin takvimlerinde artık aylar için boolean bayrak). calendar ve timeZone alanları, yapının oluşturulduğu ilgili nesnelere referanslar saklar.

Calendar.dateComponents aracılığıyla bileşen çıkarırken, performans için yalnızca gerekli alanları talep etmek önemlidir. Calendar, talep edilen tüm alanları tek bir geçişte çıkarır — bu, her alan için ayrı ayrı Calendar.component çağırmaktan önemli ölçüde daha hızlıdır.

DateComponents oluşturma

DateComponents başlatma — en basit yol: boş bir yapı oluşturun ve gerekli alanları doldurun. Belirtilmeyen tüm alanlar otomatik olarak nil alır. Kısmi bileşenlerden oluşturulan bir tarih, başlatma sırasında doğrulanmaz — hata yalnızca Calendar aracılığıyla Date'e dönüştürülürken ortaya çıkabilir.

Başlatıcı DateComponents(calendar:timeZone:era:year:month:day:hour:minute:second:nanosecond:weekday:…) tüm alanları tek bir çağrıda ayarlamaya olanak tanır. Bu başlatıcı, hazır değerlerden tam bir tarih oluşturmak için kullanışlıdır, ancak okunabilirlik nedeniyle nadiren 5-6'dan fazla argümanla kullanılır.

Calendar.dateComponents(_:from:) — mevcut bir Date'ten DateComponents elde etmenin ana yoludur. İkinci argüman, çıkarılacak bileşenler kümesidir. Calendar, saat dilimini dikkate alarak takvim hesaplamaları yapar ve yalnızca talep edilen alanlarla bir yapı döndürür; kalan alanlar nil olarak kalır.

import Foundation

// Alan başlatıcı aracılığıyla oluşturma
var components = DateComponents()
components.year = 2026
components.month = 7
components.day = 21

// Date'ten çıkarma
let now = Date()
let extracted = Calendar.current.dateComponents(
    [.year, .month, .day],
    from: now
)
print("Today: \(extracted.day!).\(extracted.month!).\(extracted.year!)")

// Genişletilmiş başlatıcı aracılığıyla oluşturma
let birthday = DateComponents(
    calendar: Calendar.current,
    year: 1990, month: 5, day: 15
)

Alanları manuel olarak ayarlayarak DateComponents oluştururken, Date'e dönüştürmeden önce her zaman Calendar'ı kontrol edin. date(from:) dönüşümü sırasında, bileşenler var olmayan bir tarih oluşturuyorsa (örneğin, 31 Şubat veya artık olmayan bir yılda 30 Şubat) Calendar nil döndürebilir. Tarih doğrulaması Calendar'ın sorumluluğundadır, DateComponents'in değil.

DateComponents'i Date'e dönüştürme

Calendar.date(from:) — DateComponents'i Date'e dönüştürmenin ana yöntemidir. Calendar, bileşenleri kendi takvimi ve saat dilimine göre yorumlar. Bazı alanlar ayarlanmamışsa (nil), Calendar varsayılan değerleri kullanır: gün = 1, saat = 0, dakika = 0, saniye = 0.

Yöntem isteğe bağlı bir Date döndürür — bileşenler birbirleriyle çelişiyorsa veya geçersiz bir tarih oluşturuyorsa nil oluşur. Nil'in tipik nedenleri: var olmayan tarih (32 Ocak, 29 Şubat 2023), çelişkili alanlar (aynı kümede weekday=1, day=5), verilen takvim için imkansız yıl (Gregoryen takvimde yıl 0).

timeZone ile DateComponents — DateComponents bir timeZone içeriyorsa, Calendar dönüşüm sırasında bunu kullanır. timeZone belirtilmemişse, Calendar kendi mevcut timeZone'unu kullanır. Calendar.timeZone, tarihin beklenen saat dilimiyle eşleşmiyorsa, sonuç birkaç saat farklılık gösterebilir — timeZone'un nesnelerden birinde açıkça ayarlandığından emin olun.

let calendar = Calendar(identifier: .gregorian)

// DateComponents'ten Date oluşturma
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 belirterek oluşturma
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 tarih farkı için — DateComponents'in başka bir kullanım durumu. Calendar.dateComponents([.year, .month, .day], from: Date(), to: futureDate) iki tarih arasındaki yıl, ay ve gün cinsinden farkı döndürür. Bu, TimeInterval'i bir yıldaki saniye sayısına bölmek yerine yaş hesaplamanın doğru yoludur, çünkü Calendar artık yılları dikkate alır.

Calendar ve DateComponents

Calendar — DateComponents ile çalışan merkezi sınıftır. Tarihleri çıkarma, birleştirme ve karşılaştırma işlemlerinin tümü Calendar üzerinden gerçekleşir. Calendar olmadan DateComponents, zamansal anlamı olmayan bir sayı kümesinden ibarettir. Calendar, bileşenlere yorum kazandırır: ay 2'nin Şubat olduğunu ve weekday 2'nin Pazartesi olduğunu belirler.

Calendar.nextDate ve Calendar.enumerateDates — DateComponents'e dayanan iki yöntem. nextDate(after: Date(), matching: DateComponents) belirtilen bileşenlerle eşleşen bir sonraki tarihi bulur — örneğin, bugünden sonraki Pazartesi. enumerateDates(startingAfter:matching:matchingPolicy:using:) belirtilen sınıra kadar desenle eşleşen tüm tarihler üzerinde yinelenir.

Calendar.dateInterval — belirtilen bileşen için bir DateInterval döndüren yöntem. dateInterval(of: .month, for: Date()) geçerli ayın başlangıcını ve bitişini döndürür. Dahili olarak, bu yöntem dönem sınırlarını bulmak için DateComponents kullanır: ayın ilk ve son günüyle DateComponents oluşturur ve bunları Calendar aracılığıyla Date'e dönüştürür.

let calendar = Calendar.current

// Gelecek Pazartesi
let nextMonday = calendar.nextDate(
    after: Date(),
    matching: DateComponents(weekday: 2),
    matchingPolicy: .nextTime
)!

// Gün cinsinden tarihler arası fark
let diff = calendar.dateComponents(
    [.day], from: Date(), to: nextMonday
)

// Ay aralığı
let monthInterval = calendar.dateInterval(
    of: .month, for: Date()
)!
let startOfMonth = monthInterval.start
let endOfMonth = monthInterval.end

MatchingPolicy — DateComponents ile çalışırken Calendar yöntemlerinin önemli bir parametresidir. strictPolicy tüm bileşenlerin tam eşleşmesini gerektirir, nextTimePolicy bir sonraki zamansal eşleşmeyi seçer, nextTimePreservingSmallerComponents kaynak tarihten daha küçük bileşenleri (dakika, saniye) korur. Politika seçimi, özellikle yaz saati uygulaması geçişleri yoluyla kaydırma yaparken tarih arama sonucunu etkiler.

DateComponents örnekleri

Bir uygulamada DateComponents kullanımının pratik senaryolarını inceleyelim. Her örnek, bir iOS geliştiricisinin takvim tarihleriyle çalışırken karşılaştığı tipik bir görevi gösterir.

Her ayın ilk günü hatırlatıcı

Calendar.nextDate DateComponents(day: 1) ile bir sonraki ayın ilk gününü bulur. Calendar, geçerli aydaki gün sayısını otomatik olarak belirler ve bir sonraki aya geçer. Tekrarlanan bildirimler için, bir Calendar anahtarıyla enumerateDates veya Combine.Timer kullanın.

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

// Yıl cinsinden yaş hesaplama
func ageInYears(from birthDate: Date) -> Int {
    let calendar = Calendar.current
    let ageComponents = calendar.dateComponents(
        [.year], from: birthDate, to: Date()
    )
    return ageComponents.year ?? 0
}

// Yıl ve aya göre etkinlik gruplama
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!)"
    }
}

Yaş hesaplama Calendar.dateComponents([.year], from:to:) aracılığıyla — artık yılları dikkate alan tek doğru yol. TimeInterval tabanlı hesaplama (saniye / 31536000) 29 Şubat'ta doğan kişiler için hata verir. Calendar, geçerli yılda doğum gününün olup olmadığını doğru bir şekilde belirler ve kesin yaşı döndürür.

Yıl ve aya göre gruplama — geçmiş veya takvim ekranları için yaygın bir görev. DateComponents, gruplama anahtarı olarak hizmet eder: etkinlik tarihinden yıl ve ayı çıkarın, bir dize anahtarı oluşturun ve Dictionary(grouping:) aracılığıyla gruplayın. Görüntüleme için, yerelleştirilmiş bir ay adı için "LLLL yyyy" şablonuyla DateFormatter kullanın.