Calendar — nedir, Date takvimi ve Swift'te hesaplamalar

Foundation'da Calendar Nedir?

Calendar, ICU (International Components for Unicode) tabanlı takvim hesaplamalarını uygulayan bir Foundation sınıfıdır. Takvim, mutlak zamanın (Date) takvim bileşenlerine nasıl eşlendiğini tanımlar: yıl, ay, gün, saat, dakika, saniye. Calendar olmadan hangi yıl, ay ve günde olduğunu bilmek imkansızdır — Date'in kendisi bu bilgiyi içermez.

Takvim üç grup parametreyi dikkate alır: takvim sistemi (Gregoryen, Budist, Japon), saat dilimi ve bölgesel ayarlar. Calendar.current, kullanıcının sistem ayarlarından üçünü de birleştirir. Calendar.autoupdatingCurrent, NotificationCenter aracılığıyla uygulamayı yeniden başlatmadan ayarlar değiştiğinde otomatik olarak güncellenen özel bir sürümdür.

Calendar, Foundation'da bir değer tipidir (value type). Calendar(identifier:) sabit parametrelerle yeni bir örnek oluşturur. Calendar kopyalanabilir, == ile karşılaştırılabilir ve sözlükte anahtar olarak kullanılabilir. Bu, test için belirli timeZone ve locale ayarlarına sahip takvimler oluşturmaya olanak tanır.

Calendar ve NSCalendar

Calendar, Objective-C NSCalendar'ın Swift sürümüdür ve as Calendar / as NSCalendar aracılığıyla köprülenir. Modern Swift'te Calendar her yerde kullanılır. NSCalendar, Objective-C API'leriyle geriye dönük uyumluluk için kalır. Calendar, NS öneki olmadan, type-safe argümanlar ve Swift optional'ları ile eksiksiz bir yöntem setine sahiptir.

Thread Güvenliği — Calendar okuma için thread-safe'dir. Oluşturulan bir örnek birden çok thread'den güvenle okunabilir. Özelliklerin (timeZone, locale) değiştirilmesi thread-safe değildir — farklı yapılandırmalar için ayrı Calendar örnekleri oluşturun.

Foundation'da Takvim Türleri

Foundation, Calendar.Identifier numaralandırması aracılığıyla 17 takvim sistemini destekler. Her sistemin artık yıllar, ay sayısı ve dönem başlangıcı için kendi kuralları vardır. Takvim seçimi tüm hesaplamaları etkiler: dateComponents, dateInterval, nextDate.

Başlıca takvim sistemleri:

• .gregorian — uluslararası standart, 12 ay, 365/366 gün, İsa'nın doğumundan itibaren dönem.
• .buddhist — Budist takvimi, Tayland, Kamboçya, Laos'ta kullanılır, dönem Gregoryen'den 543 yıl ileridedir.
• .japanese — İmparatorluk saltanat dönemlerine göre Japon takvimi, Gregoryen gibi 12 ay.
• .hebrew — İbrani takvimi, 12/13 ay, artık ay Adar II.
• .islamic — İslami takvim, 12 kameri ay, 354/355 gün.
• .indian — Hint ulusal takvimi (Saka), 12 ay.

Calendar(identifier: .gregorian) — en çok kullanılanıdır. Uluslararası standart ISO 8601'e uygundur ve çoğu ülkede varsayılan takvimdir. Uluslararası kitleye sahip uygulamalar için Calendar.current kullanın — kullanıcının sistem takvimiyle otomatik olarak eşleşir.

Calendar ve DateComponents

DateComponents ve Calendar ayrılmaz bir çifttir. Calendar.dateComponents(_:from:), takvimin saat dilimini dikkate alarak Date'ten bileşenleri çıkarır. Calendar.date(from:), DateComponents'ten Date oluşturur ve eksik alanları varsayılan değerlerle doldurur: gün = 1, saat = 0, dakika = 0, saniye = 0.

Calendar.component yöntemi tek bir bileşeni çıkarır, hızlı kontroller için uygundur. Calendar.dateComponents tek bir çağrıda birden çok bileşeni çıkarır — bu daha verimlidir çünkü Calendar her bileşen için ayrı ayrı yerine bir kez takvim hesaplaması yapar. 3+ bileşenli bir liste için her zaman dateComponents kullanın.

Calendar.compare, belirtilen hassasiyette iki Date'i karşılaştırır. toGranularity parametresi bileşen hassasiyetini belirler: .year yalnızca yılı, .month — yıl ve ayı, .day — yıl, ay, günü karşılaştırır. Bu, saati göz ardı ederek iki tarihin aynı güne denk gelip gelmediğini kontrol etmek için kullanışlıdır.

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

// Tek bir bileşeni çıkarma
let year = calendar.component(.year, from: now)

// Bir dizi bileşeni çıkarma
let comps = calendar.dateComponents(
    [.year, .month, .day], from: now
)

// Gün hassasiyetiyle karşılaştırma
let isSameDay = calendar.compare(date1, to: date2,
                                  toGranularity: .day) == .orderedSame

// Tarihin bugün olup olmadığını kontrol et
let isToday = calendar.isDateInToday(someDate)

Calendar.isDateInToday, isDateInTomorrow, isDateInYesterday — göreceli kontroller için yöntemler. Calendar.isDate(_:inSameDayAs:), takvimin saat dilimini dikkate alarak iki tarihin aynı takvim gününe denk gelip gelmediğini kontrol eder. Bu yöntemler dahili olarak Calendar.compare kullanır ve sık çağrılar için optimize edilmiştir.

Calendar Hesaplamaları

Calendar.dateInterval, analitik ve kullanıcı arayüzü için en kullanışlı yöntemlerden biridir. Belirtilen bileşen için bir DateInterval döndürür: bir gün, hafta, ay, yılın başlangıcı ve bitişi. DateInterval, start (Date) ve end (Date) — dönem sınırlarını içerir. Örneğin, dateInterval(of: .weekOfYear, for: Date()) geçerli haftanın Pazartesi başlangıcını ve Pazar bitişini döndürür.

Calendar.date byAdding ile — tarihleri kaydırmak için bir yöntem. Calendar.date(byAdding: .day, value: 7, to: Date()) bir hafta sonraki tarihi döndürür. Calendar.date(byAdding: DateComponents) daha esnek bir sürümdür ve aynı anda birden çok bileşeni kaydırmaya olanak tanır: +1 ay +3 gün. Calendar otomatik olarak farklı ay uzunluklarını ve artık yılları dikkate alır.

Calendar.nextDate, belirtilen DateComponents ile eşleşen bir sonraki tarihi arar. matchingPolicy parametresi, uyuşmazlık durumunda davranışı tanımlar: .nextTime — zamandaki bir sonraki eşleşme, .nextTimePreservingSmallerComponents — orijinal tarihten dakika ve saniyeleri korur, .strict — tam eşleşme gerektirir.

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

// Haftanın başı ve sonu
let weekInterval = calendar.dateInterval(
    of: .weekOfYear, for: today
)!

// 1 ay kaydırma
let nextMonth = calendar.date(
    byAdding: .month, value: 1, to: today
)!

// DateComponents aracılığıyla kaydırma
var delta = DateComponents()
delta.month = 1
delta.day = 3
let shifted = calendar.date(byAdding: delta, to: today)!

// Bir sonraki 13'üncü Cuma
let friday13Components = DateComponents(
    weekday: 6, day: 13
)
let nextFriday13 = calendar.nextDate(
    after: today, matching: friday13Components,
    matchingPolicy: .nextTime
)

EnumerateDates — bir desene göre tarihler üzerinde yineleme yapmak için güçlü bir yöntem. Calendar.enumerateDates(startingAfter:matching:matchingPolicy:using:), blok stop = true döndürene kadar her eşleşme için bir blok çağırır. Takvimlerde ve programlarda yinelenen olaylar oluşturmak için kullanılır. Bu yöntem, ICU tarafından optimize edildiğinden, nextDate ile manuel döngüden daha verimlidir.

TimeZone ve Locale

TimeZone, Calendar'ın ayrılmaz bir parçasıdır. Saat dilimi, mutlak bir Date'in hangi takvim saatine karşılık geldiğini belirler. UTC'de ve Moskova'da aynı Date farklı bileşenler üretir: UTC'de Date() 10:00 gösterebilirken, MSK'da — 13:00. Calendar.timeZone varsayılan olarak TimeZone.current'tir.

Locale, haftanın ilk gününü, yılın ilk haftasındaki minimum gün sayısını (minDaysInFirstWeek) ve ay/hafta günü adlarını (DateFormatter aracılığıyla dönüştürme sırasında) etkiler. Calendar.locale varsayılan olarak Locale.current'tir. Rus bölgesel ayarlarında hafta Pazartesi günü başlar, Amerikan ayarlarında — Pazar günü.

Calendar.availableIdentifiers, desteklenen tüm takvim tanımlayıcılarının bir listesini döndürür. Statik özellik Calendar.availableCalendarIdentifiers, aynı tanımlayıcılara sahip bir dize dizisidir. Takvim seçim arayüzü oluşturmak ve cihazda belirli bir takvim sisteminin kullanılabilirliğini kontrol etmek için kullanılır.

// Belirli saat dilimiyle Calendar
var utcCalendar = Calendar(identifier: .gregorian)
utcCalendar.timeZone = TimeZone(identifier: "UTC")!

// Rus bölgesel ayarlarıyla Calendar
var russianCalendar = Calendar(identifier: .gregorian)
russianCalendar.locale = Locale(identifier: "ru_RU")

// İlk iş günü bölgesel ayarlara bağlıdır
let firstWeekday = russianCalendar.firstWeekday
// 2 = Pazartesi (ru_RU'da)

// Mevcut takvimlerin listesi
for identifier in Calendar.availableIdentifiers {
    print(identifier)
}

firstWeekday — haftanın hangi gününün ilk olarak kabul edildiğini belirleyen bir Calendar özelliğidir. Rus bölgesel ayarlarında Sunday = 2 (Pazartesi ilktir). Amerikan bölgesel ayarlarında Sunday = 1. Bu, weekOfMonth ve weekOfYear'ı etkiler: aynı tarih farklı bölgesel ayarlarda farklı hafta numaralarına ait olabilir. Tarihlerle çalışan uygulamalar için Calendar.current kullanın veya firstWeekday'i açıkça ayarlayın.

Calendar ile Çalışma Örnekleri

Calendar'in yeteneklerini gösteren pratik senaryoları inceleyelim. Her örnek belirli bir iOS geliştirme görevini çözer ve takvim hesaplamalarının doğru kullanımını gösterir.

Kontrol: tarih bu ayda mı?

Calendar.dateInterval(of: .month, for:) geçerli ayın sınırlarını döndürür. Bir Date'in bu aralık içinde olup olmadığını kontrol etmek, bir tarihin geçerli aya ait olup olmadığını belirlemenin en hızlı yoludur. Bir alternatif, .month hassasiyetiyle Calendar.compare kullanmaktır: sonuç .orderedSame ise, ay eşleşir.

func isInCurrentMonth(_ date: Date) -> Bool {
    let calendar = Calendar.current
    let monthInterval = calendar.dateInterval(
        of: .month, for: Date()
    )!
    return monthInterval.contains(date)
}

// Bir aydaki gün sayısı
func daysInMonth(for date: Date) -> Int {
    let calendar = Calendar.current
    return calendar.range(
        of: .day, in: .month, for: date
    )?.count ?? 0
}

// Doğru sarmalamayla ay ekleme
func addMonths(_ months: Int, to date: Date) -> Date {
    let calendar = Calendar.current
    return calendar.date(
        byAdding: .month, value: months, to: date
    )!
}

Calendar.range(of:in:for:), başka bir bileşenin bağlamında belirtilen bir bileşen için geçerli değerlerin aralığını döndürür. Örneğin, range(of: .day, in: .month, for: date) 31 günlük aylar için 1..<32 veya artık yıl olmayan bir yılda Şubat için 1..<29 döndürür. Sabit kodlanmış değerler kullanmak yerine bir aydaki gün sayısını öğrenmenin doğru yoludur.

Ay ekleme, Calendar.date(byAdding:value:to:) aracılığıyla sınır tarihlerini doğru şekilde işler. 31 Ocak'a 1 ay eklenirse, Calendar 28 Şubat'ı (veya artık yılda 29) döndürür, TimeInterval aracılığıyla sadece 30 gün eklenmesiyle elde edilecek 3 Mart yerine. Bu, takvim hesaplamaları için TimeInterval kullanmamanın bir başka nedenidir.