DateIntervalFormatter — əsaslar, tarix intervallarının formatlanması

DateIntervalFormatter nədir?

DateIntervalFormatter Foundation-də Formatter-in alt sinfidir, DateInterval obyektini (iki tarix arasında diapazon) qəbul edir və bu diapazonun təsviri ilə lokalizə olunmuş sətr qaytarır. Məsələn, 21 iyuldan 25 iyula kimi 2024-cü il diapazonu üçün nəticə az_AZ üçün “21–25 iyul 2024” və en_US üçün “Jul 21–25, 2024” olacaq. Sinif aşağıdakı elementləri ağıllı şəkildə qruplaşdırır: əgər hər iki tarix eyni aydadırsa, ayın adı bir dəfə göstərilir.

DateIntervalFormatter-in əsas dəyəri diapazonların qrammatikasının avtomatik işlənməsidir. Əl ilə formatlaşdırma zamanı proqramçı başlanğıc və sonun ayını/ilini müqayisə etməli, ayırıcı seçməli (tire, “-dən/dək”, “to”, “bis”) və hallanmaya nəzarət etməli olacaqdı. DateIntervalFormatter bunu CLDR (Common Locale Data Repository) məlumatları əsasında avtomatik edir, bu da beynəlxalq tətbiqlərdə, xüsusən mürəkkəb qrammatikaya malik dillərdə səhvlərin sayını azaldır.

Unicode CLDR v44 (2024)-ə görə, tarix diapazonlarının formatlaşdırma qaydaları dillər arasında çox fərqlənir. Alman “bis” ön sözündən (21.–25. Juli 2024), fransız “au” (du 21 au 25 juillet 2024), yapon — defisdən istifadə edir (2024 Jul 21–25). DateIntervalFormatter bütün bu variantları proqramçı tərəfindən əlavə kod yazılmadan əhatə edir.

DateIntervalFormatter Foundation-də necə işləyir?

İşləmə prinsipi DateIntervalFormatter diapazonu təşkil edə iki tarixin təhlilinə və locale nəzərə alınmaqla optimal mətn təqdimatının seçilməsinə əsaslanır. Sinif tarix komponentlərini (il, ay, gün) müqayisə edir və qruplaşdırma haqqında qərar verir: əgər il eynidirsə — bir dəfə göstərilir; əgər ay eynidirsə — bir dəfə göstərilir; əgər günlər fərqlidirsə — gün diapazonu göstərilir.

Qruplaşdırma məntiqi CLDR nümunələri əsasında həyata keçirilir. Formatlayıcı hər bir tarix komponentinin (Calendar.Component: year, month, day) bərabərliyini böyükdən kiçiyə doğru yoxlayır. Komponent fərqlənən kimi, bütün kiçik komponentlər hər iki tarix üçün göstərilir. Məsələn, 21–25 iyul: il uyğun, ay uyğun, gün fərqli → ay bir dəfə, günlər hər tarix üçün ayrı göstərilir.

Önəmli nüans: DateIntervalFormatter API vasitəsilə ayırıcının konfiqurasiyasını dəstəkləmir. Ayırıcı locale tərəfindən müəyyən edilir və dəyişdirilə bilməz. Qeyri-standart ayırıcı tələb olunarsa (məsələn, “-dək” əvəzinə “-ə kimi”), tarixləri DateFormatter vasitəsilə əl ilə formatlaşdırıb özɑl ayırıcı ilə birləşdirməli olacaqsınız.

Interval formatlaşdırma stilləri

DateIntervalFormatter iki stil dəsti təqdim edir: dateStyle və timeStyle — diapazonun hər iki ucu üçün. Bu stillər DateFormatter-ə bənzər işləyir: .none komponenti gizlədir, .short qısa format verir (21.07.2024), .medium — orta (21 iyul 2024), .long — tam (21 iyul 2024), .full — maksimum təfərrüatlı (bazar, 21 iyul 2024). dateStyle və timeStyle-ı birləşdirərək müxtəlif təfərrüat səviyyələri əldə etmək olar.

Stil kombinasiyalarının nümunələri

• dateStyle = .medium, timeStyle = .none — yalnız tarix: “21–25 iyul 2024”
• dateStyle = .short, timeStyle = .short — tarix və vaxt: “21.07.2024, 14:30 – 25.07.2024, 16:45”
• dateStyle = .none, timeStyle = .short — yalnız vaxt: “14:30–16:45” (əgər tarixlər eynidirsə)
• dateStyle = .long, timeStyle = .none — uzun tarix: “21–25 iyul 2024-cü il”
• dateStyle = .full, timeStyle = .short — tam format: “bazar, 21 iyul 2024 – cümə axşamı, 25 iyul 2024”

Önəmli: dateStyle və timeStyle diapazonun hər iki ucuna eyni şəkildə tətbiq olunur. Başlanğıc və son üçün fərqli stil təyin etmək olmaz (məsələn, başlanğıc üçün .medium, son üçün .short). Fərqli stil tələb olunarsa, hər bir tarixi ayrı DateFormatter ilə formatlaşdırıb nəticələri birləşdirmək lazımdır.

import Foundation

let formatter = DateIntervalFormatter()

// Müxtəlif stil kombinasiyaları
let startDate = Date()
let endDate = Date().addingTimeInterval(345600) // +4 gün
let interval = DateInterval(start: startDate, end: endDate)

// Yalnız tarix, orta format
formatter.dateStyle = .medium
formatter.timeStyle = .none
print("Yalnız tarix: \(formatter.string(from: interval))")

// Qısa format vaxtla
formatter.dateStyle = .short
formatter.timeStyle = .short
print("Vaxtla qısa: \(formatter.string(from: interval))")

// Tam format
formatter.dateStyle = .full
formatter.timeStyle = .none
print("Tam tarix: \(formatter.string(from: interval))")

DateIntervalFormatter Swift-də: nümunələr

Əsas istifadə DateIntervalFormatter-in yaradılması, stillərin konfiqurasiyası və string(from:) çağırılmasını əhatə edir. Metod start və end xüsusiyyətləri olan DateInterval strukturunu qəbul edir. DateInterval həm iki Date-dən, həm də Duration ilə (iOS 16+) yaradıla bilər. Formatlaşdırmadan sonra nəticə əlavə emal olmadan UI-də göstərilməyə hazırdır.

import Foundation

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

// Xüsusi interval nümunələri
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 vasitəsilə formatlaşdırma (iOS 16+)
if let nextWeek = calendar.date(
    byAdding: .day, value: 7, to: now
) {
    let weekInterval = DateInterval(start: now, end: nextWeek)
    print("Növbəti 7 gün: \(intervalFormatter.string(from: weekInterval))")
}

DateIntervalFormatter və Calendar Booking: rezervasiya tətbiqlərində (otellər, biletlər) tarix diapazonları UI-nın əsas elementidir. DateIntervalFormatter illərarası diapazonları düzgün emal edir (məsələn, 28 dekabrdan 3 yanvara kimi), ay və ili hər tarix üçün ayrı qruplaşdıraraq. Belə ssenarilərdə dateStyle = .medium və timeStyle = .none istifadə etmək tövsiyə olunur — vaxtsız tarixlər üçün ən oxunaqlı format.

import Foundation

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

// Rezervasiya nümunələri
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("Rezervasiya: \(booking.formattedInterval)")

// Müxtəlif locale-lərlə istifadə
let enFormatter = DateIntervalFormatter()
enFormatter.dateStyle = .medium
enFormatter.timeStyle = .none
enFormatter.locale = Locale(identifier: "en_US")
print("İngilis: \(enFormatter.string(from: interval))")

DateInterval vs DateIntervalFormatter: DateInterval — tarix diapazonunu təmsil edən struktur (başlanğıc və son). DateIntervalFormatter — bu strukturu sətrə çevirən formatlayıcı. DateInterval həmçinin contains(Date) və intersection(with:) yoxlamalarını dəstəkləyir, bu da rezervasiya məntiqi üçün faydalıdır (tarixlərin üst-üstə düşməsinin yoxlanması).

Tarix intervallarının lokalizasiyası

DateIntervalFormatter locale xüsusiyyəti vasitəsilə çıxışı lokalizə edir. Standart olaraq Locale.current — cihazın locale-i istifadə olunur. Intervalları başqa dildə göstərmək üçün (məsələn, Azərbaycan interfeysində ingilis məzmunu), locale-i açıq şəkildə təyin edin. DateFormatter-dən fərqli olaraq, DateIntervalFormatter server məlumatları üçün Locale təyin edilməsini tələb etmir — o, həmişə CLDR-ə əsaslanan daxili qruplaşdırma məntiqindən istifadə edir.

Tarix diapazonlarının formatlaşdırılmasında dil fərqləri tək tarixlərdən qat-qat mürəkkəbdir. İngilis sadə tiredən istifadə edir: Jul 21–25. Azərbaycan — “-dən/dək”: 21-dən 25-dək iyul. Fransız — “au”: du 21 au 25 juillet. Alman — rəqəmdən sonra nöqtə və tire: 21.–25. Juli. Yapon — ön sözsüz defis: Jul 21–25. DateIntervalFormatter bütün bu variantları əhatə edir.

import Foundation

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

let start = Date()
let end = Date().addingTimeInterval(259200) // +3 gün
let interval = DateInterval(start: start, end: end)

// Müxtəlif locale-lərin nümayişi
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))")
}

// Vaxt intervalları üçün lokalizasiya
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) vaxt: \(formatter.string(from: timeInterval))")
}

Lokalizasiya xüsusiyyətləri: Azərbaycan dili üçün DateIntervalFormatter uzun tarix formatlarında “-dən” və “-dək” ön sözlərindən istifadə edir. Qısa (short) format üçün — yalnız tire: 21.07–25.07.2024. Tam format (full) üçün — həftənin günü göstərilir. Format seçimi kontekstdən asılıdır: rezervasiya siyahısı üçün .medium, ətraflı baxış üçün .long və ya .full istifadə edin.

Digər tarix formatlayıcıları ilə müqayisə

DateIntervalFormatter Foundation-ın digər siniflərinin əhatə etmədiyi tarix diapazonlarının formatlaşdırılması yerini tutur. DateFormatter tək tarixləri, RelativeDateTimeFormatter — nisbi tarixləri (əvvəl/sonra), DateComponentsFormatter — müddəti (2 saat 30 dəqiqə) formatlaşdırır. Bu siniflərin hər biri öz məsələsini həll edir və onları bir-birini əvəz etmək olmaz.

DateIntervalFormatter nə vaxt istifadə edilməli: UI-də tarix diapazonlarını göstərmək üçün — otellərin rezervasiyası, hadisələr, tarixlər üzrə filtrləmə, əməliyyat tarixçəsi. Tarixlər arasında müddəti hesablamaq üçün DateComponentsFormatter istifadə edin, DateIntervalFormatter yox — sonuncu müddəti göstərmək üçün nəzərdə tutulmayıb. DateFormatter yalnız tək tarixlər üçün istifadə edilməli, iki formatlaşdırılmış tarixin sətr birləşdirməsi ilə yapışdırılması üçün yox — bu, ayırıcının lokalizasiyasının itirilməsinə səbəb olur.

Edge case: DateIntervalFormatter açıq diapazonların (bitmə tarixi olmadan) göstərilməsini dəstəkləmir. Diapazonun sonu məlum deyilsə (məsələn, “21 iyuldan”), Azərbaycan dili üçün “-dən” ön sözü ilə DateFormatter istifadə edin. DateIntervalFormatter həmçinin müxtəlif günlər üçün vaxt göstərilən diapazonları dəstəkləmir — vaxt hər tarixə ayrı tətbiq olunur, bu da qısa diapazonlar üçün artıq görünə bilər.