DateComponents – bu nədir, təqvim komponentləri və NSCalendar

DateComponents nədir?

DateComponents zamanın təqvim komponentlərini saxlamaq üçün nəzərdə tutulmuş Foundation dəyər tipidir. Hər bir komponent isteğe bağlı Int sahəsi kimi təmsil olunur: year, month, day, hour, minute, second, nanosecond, weekday, weekOfMonth, weekOfYear, quarter, yearForWeekOfYear və digərləri.

Date-dən əsas fərq təqvimə bağlılıqdır. Date mütləq vaxtı (reference date-dən saniyələrin sayı) saxlayır, DateComponents isə yalnız konkret Calendar kontekstində məna kəsb edən insan tərəfindən oxuna bilən təmsilçilikdir. Eyni Date müxtəlif təqvimlərdə və saat qurşaqlarında fərqli DateComponents ilə təmsil oluna bilər.

DateComponents müstəqil zaman tipi deyil, məlumat konteyneridir. DateComponents-in tarix kimi şərh edilməsi üçün komponentlərin təqvim sistemi ilə necə əlaqəli olduğunu anlayan Calendar tələb olunur. Calendar.dateComponents(from: Date) komponentlərin çıxarılmasını, Calendar.date(from: DateComponents) isə tərs yığılmanı həyata keçirir.

Sahələrin isteğe bağlılığı

DateComponents-in hər bir sahəsi isteğe bağlıdır (Int?), bu da natamam tarixlərlə iş üçün prinsipial əhəmiyyət kəsb edir. Yalnız il və ayı göstərsəniz, Calendar çatışmayan sahələri standart dəyərlərlə tamamlayacaq: gün = 1, saat = 0, dəqiqə = 0. Bu, dövrün başlanğıc tarixlərini yaratmaq üçün əlverişlidir – yalnız maraqlı komponentləri təyin etmək kifayətdir.

DateComponents-i == operatoru ilə müqayisə edərkən yalnız təyin edilmiş (nil olmayan) sahələr müqayisə olunur. 2026-cı ili olan, lakin ayları fərqli olan iki DateComponents strukturu fərqli hesab olunur. DateComponents üçün NSObjectProtocol-dən isEqual tətbiq edilmir – DateComponents NSObject-dən miras almır.

Tarix komponentləri: il, ay, gün

Əsas sahələr DateComponents-ə year, month, day, hour, minute, second, nanosecond daxildir. Hər bir sahə müvafiq vahiddə ədədi dəyər saxlayır: il – 2026, ay – 1..12, gün – 1..31, saat – 0..23, dəqiqə – 0..59, saniyə – 0..59. Nanosaniyələr 0..999999999 dəyərlərini qəbul edə bilər.

Həftə sahələri – weekday (1..7, burada 1 = Qriqorian təqvimində bazar), weekOfMonth, weekOfYear. Bu sahələr Calendar-dan asılıdır və onun kontekstindən kənarda məna kəsb etmir. weekday təqvimin firstWeekday parametrindən asılıdır: Azərbaycan lokalında həftə bazar ertəsindən başlayır (Qriqorian sistemində weekday = 2), Amerika lokalında isə – bazardan (weekday = 1).

İxtisaslaşmış sahələr – quarter (1..4), yearForWeekOfYear (həftənin aid olduğu il), isLeapMonth (İvrit və ya Çin təqvimlərində artıq aylar üçün məntiqi bayraq). calendar və timeZone sahələri strukturun yaradıldığı müvafiq obyektlərə istinadları saxlayır.

Calendar.dateComponents vasitəsilə komponentləri çıxararkən məhsuldarlıq üçün yalnız lazımi sahələri tələb etmək vacibdir. Calendar bütün tələb olunan sahələri bir keçiddə çıxarır – bu, hər bir sahə üçün Calendar.component-i ayrıca çağırmaqdan əhəmiyyətli dərəcədə sürətlidir.

DateComponents yaradılması

DateComponents-in inisializasiyası – ən sadə üsul: boş struktur yaradır və lazımi sahələri doldurursunuz. Bütün göstərilməyən sahələr avtomatik olaraq nil alır. Qismən komponentlərdən yaradılan tarix inisializasiya mərhələsində yoxlanılmır – xəta yalnız Calendar vasitəsilə Date-ə çevrilərkən yarana bilər.

DateComponents(calendar:timeZone:era:year:month:day:hour:minute:second:nanosecond:weekday:…) inisializatoru bütün sahələri bir çağırışda təyin etməyə imkan verir. Bu inisializator hazır dəyərlərdən tam tarix yaratmaq üçün əlverişlidir, lakin oxunaqlılıq səbəbindən 5-6 arqumentdən çoxu ilə nadir hallarda istifadə olunur.

Calendar.dateComponents(_:from:) – mövcud Date-dən DateComponents əldə etməyin əsas üsulu. İkinci arqument çıxarılmalı olan komponentlər dəstidir. Calendar saat qurşağı nəzərə alınmaqla təqvim hesablamalarını aparır və yalnız tələb olunan sahələri olan strukturu qaytarır, qalan sahələr nil olaraq qalır.

import Foundation

// Sahələrin inisializatoru vasitəsilə yaradılması
var components = DateComponents()
components.year = 2026
components.month = 7
components.day = 21

// Date-dən çıxarılması
let now = Date()
let extracted = Calendar.current.dateComponents(
    [.year, .month, .day],
    from: now
)
print("Today: \(extracted.day!).\(extracted.month!).\(extracted.year!)")

// Genişləndirilmiş inisializator vasitəsilə yaradılması
let birthday = DateComponents(
    calendar: Calendar.current,
    year: 1990, month: 5, day: 15
)

DateComponents-i əl ilə sahələr vasitəsilə yaradarkən həmişə Calendar-ı Date-ə çevirməzdən əvvəl yoxlayın. Calendar date(from:) çevirərkən komponentlər mövcud olmayan tarix yaradarsa nil qaytara bilər – məsələn, 31 fevral və ya artıq il olmayan ildə 30 fevral. Tarixin yoxlanması Calendar-ın məsuliyyətidir, DateComponents-in deyil.

DateComponents-in Date-ə çevrilməsi

Calendar.date(from:) – DateComponents-i Date-ə çevirməyin əsas metodu. Calendar komponentləri öz təqviminə və saat qurşağına uyğun şərh edir. Əgər bəzi sahələr təyin edilməyibsə (nil), Calendar standart dəyərlərdən istifadə edir: gün = 1, saat = 0, dəqiqə = 0, saniyə = 0.

Metod isteğe bağlı Date qaytarır – nil komponentlər bir-birinə zidd olduqda və ya yanlış tarix yaratdıqda baş verir. Nil-in tipik səbəbləri: mövcud olmayan tarix (32 yanvar, 29 fevral 2023), ziddiyyətli sahələr (bir dəstdə weekday=1, day=5), verilmiş təqvim üçün qeyri-mümkün il (Qriqorian təqvimində il 0).

timeZone ilə DateComponents – əgər DateComponents timeZone ehtiva edirsə, Calendar onu çevirmə zamanı istifadə edir. timeZone göstərilməyibsə, Calendar öz cari timeZone-dan istifadə edir. Calendar.timeZone gözlənilən saat qurşağı ilə üst-üstə düşmürsə, nəticə bir neçə saat fərqlənə bilər – obyektlərdən birində timeZone-un açıq şəkildə təyin olunduğuna əmin olun.

let calendar = Calendar(identifier: .gregorian)

// DateComponents-dən Date yaradılması
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 göstərilməklə yaradılması
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 tarix fərqi üçün – DateComponents-in istifadəsinin digər ssenarisi. Calendar.dateComponents([.year, .month, .day], from: Date(), to: futureDate) iki tarix arasındakı fərqi illər, aylar və günlərlə qaytarır. Bu, TimeInterval-in ildəki saniyələrin sayına bölünməsi əvəzinə yaşın hesablanmasının düzgün üsuludur, çünki Calendar artıq illəri nəzərə alır.

Calendar və DateComponents

Calendar – DateComponents ilə işləyən mərkəzi sinif. Tarixlərin çıxarılması, yığılması və müqayisəsi üzrə bütün əməliyyatlar Calendar vasitəsilə aparılır. Calendar olmadan DateComponents zaman mənası olmayan sadə ədədlər toplusudur. Calendar komponentlərə şərh verir: ay 2-nin fevral, weekday 2-nin isə bazar ertəsi olduğunu müəyyən edir.

Calendar.nextDate və Calendar.enumerateDates – DateComponents-ə əsaslanan iki metod. nextDate(after: Date(), matching: DateComponents) verilmiş komponentlərə uyğun gələn növbəti tarixi tapır – məsələn, bugündən sonrakı növbəti bazar ertəsi. enumerateDates(startingAfter:matching:matchingPolicy:using:) göstərilən limitə qədər nümunəyə uyğun gələn bütün tarixləri sadalayır.

Calendar.dateInterval – göstərilən komponent üçün DateInterval qaytaran metod. dateInterval(of: .month, for: Date()) cari ayın başlanğıcını və sonunu qaytarır. Daxildə bu metod dövrün sərhədlərini tapmaq üçün DateComponents-dən istifadə edir: ayın birinci və son günü ilə DateComponents yaradır, onları Calendar vasitəsilə Date-ə çevirir.

let calendar = Calendar.current

// Növbəti bazar ertəsi
let nextMonday = calendar.nextDate(
    after: Date(),
    matching: DateComponents(weekday: 2),
    matchingPolicy: .nextTime
)!

// Tarixlər arasında günlərlə fərq
let diff = calendar.dateComponents(
    [.day], from: Date(), to: nextMonday
)

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

MatchingPolicy – DateComponents ilə işləyərkən Calendar metodlarının vacib parametridir. strictPolicy bütün komponentlərin dəqiq uyğunluğunu tələb edir, nextTimePolicy zamana görə növbəti uyğunluğu seçir, nextTimePreservingSmallerComponents orijinal tarixdən kiçik komponentləri (dəqiqələr, saniyələr) qoruyur. Siyasət seçimi tarix axtarışının nəticəsinə təsir edir, xüsusən də yay/qış saatına keçid zamanı.

DateComponents nümunələri

DateComponents-in tətbiqdə praktik ssenarilərini nəzərdən keçirək. Hər bir nümunə iOS tərtibatçısının təqvim tarixləri ilə işləyərkən qarşılaşdığı tipik tapşırığı nümayiş etdirir.

Hər ayın ilk günü üçün xatırlatma

Calendar.nextDate DateComponents(day: 1) ilə növbəti ayın ilk gününü tapır. Calendar cari ayda günlərin sayını avtomatik müəyyən edir və növbəti aya keçir. Təkrarlanan bildirişlər üçün enumerateDates və ya Calendar açarı ilə Combine.Timer istifadə edin.

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

// İllərlə yaşın hesablanması
func ageInYears(from birthDate: Date) -> Int {
    let calendar = Calendar.current
    let ageComponents = calendar.dateComponents(
        [.year], from: birthDate, to: Date()
    )
    return ageComponents.year ?? 0
}

// Hadisələrin il və aya görə qruplaşdırılması
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şın hesablanması Calendar.dateComponents([.year], from:to:) vasitəsilə – artıq illəri nəzərə alan yeganə düzgün üsul. TimeInterval-ə əsaslanan hesablama (saniyələr / 31536000) 29 fevralda doğulanlar üçün səhv verir. Calendar cari ildə ad gününün olub-olmadığını düzgün müəyyən edir və dəqiq yaşı qaytarır.

İl və aya görə qruplaşdırma – tarixçə və ya təqvim ekranları üçün geniş yayılmış tapşırıq. DateComponents qruplaşdırma açarı kimi xidmət edir: hadisə tarixindən il və ayı çıxarırsınız, sətir açarı yaradırsınız və Dictionary(grouping:) vasitəsilə qruplaşdırırsınız. Göstərmək üçün ayların lokallaşdırılmış adı üçün „LLLL yyyy” şablonu ilə DateFormatter istifadə edin.