DateIntervalFormatter — baze, formatarea intervalelor de date

Ce este DateIntervalFormatter?

DateIntervalFormatter este o subclasă a Formatter în Foundation care primește un obiect DateInterval (interval între două date) și returnează un șir localizat cu descrierea acestui interval. De exemplu, pentru intervalul 21–25 iulie 2024, rezultatul va fi „21–25 iulie 2024“ pentru ro_RO și „Jul 21–25, 2024“ pentru en_US. Clasa grupează inteligent elementele repetitive: dacă ambele date sunt în aceeași lună, numele lunii este afișat o singură dată.

Valoarea principală a DateIntervalFormatter este procesarea automată a gramaticii intervalelor. În cazul formatării manuale, programatorul ar trebui să compare luna/anul de început și sfârșit, să aleagă separatorul (cratimă, „până la“, „to“, „bis“) și să monitorizeze declinarea. DateIntervalFormatter face acest lucru automat pe baza datelor CLDR (Common Locale Data Repository), ceea ce reduce numărul de erori în aplicațiile internaționale, în special pentru limbile cu gramatică complexă.

Potrivit Unicode CLDR v44 (2024), regulile de formatare a intervalelor de date diferă semnificativ între limbi. Germana folosește prepoziția „bis“ (21.–25. Juli 2024), franceza — „au“ (du 21 au 25 juillet 2024), japoneza — prin cratimă (2024 Jul 21–25). DateIntervalFormatter acoperă toate aceste variații fără cod suplimentar din partea programatorului.

Cum funcționează DateIntervalFormatter în Foundation?

Principiul de funcționare al DateIntervalFormatter se bazează pe analiza a două date care formează intervalul și selectarea reprezentării text optime cu luarea în considerare a locale. Clasa compară componentele datei (an, lună, zi) și ia decizia de grupare: dacă anul este același — este afișat o dată; dacă luna este aceeași — este afișată o dată; dacă zilele diferă — se afișează intervalul de zile.

Logica de grupare este implementată pe baza șabloanelor CLDR. Formatorul verifică egalitatea fiecărei componente a datei (Calendar.Component: year, month, day) în ordinea de la cea mai mare la cea mai mică. De îndată ce o componentă diferă, toate componentele mai mici sunt afișate pentru ambele date. De exemplu, pentru 21–25 iulie: anul se potrivește, luna se potrivește, ziua diferă → luna este afișată o dată, zilele — pentru fiecare dată separat.

Nuanță importantă: DateIntervalFormatter nu acceptă configurarea separatorului prin API. Separatorul este determinat de locale și nu poate fi suprascris. Dacă este necesar un separator personalizat (de exemplu, „între“ în loc de „până la“), va trebui să formatați datele manual prin DateFormatter și să lipiți șirurile cu separator personalizat.

Stiluri de formatare a intervalelor

DateIntervalFormatter oferă două seturi de stiluri: dateStyle și timeStyle — pentru fiecare capăt al intervalului. Aceste stiluri funcționează similar cu DateFormatter: .none ascunde componenta, .short oferă un format scurt (21.07.2024), .medium — mediu (21 iul. 2024), .long — lung (21 iulie 2024), .full — maxim de detaliat (duminică, 21 iulie 2024). Combinând dateStyle și timeStyle, se pot obține diferite niveluri de detaliu.

Exemple de combinații de stiluri

• dateStyle = .medium, timeStyle = .none — doar data: „21–25 iulie 2024“
• dateStyle = .short, timeStyle = .short — dată și oră: „21.07.2024, 14:30 – 25.07.2024, 16:45“
• dateStyle = .none, timeStyle = .short — doar ora: „14:30–16:45“ (dacă datele sunt aceleași)
• dateStyle = .long, timeStyle = .none — dată lungă: „21–25 iulie 2024“
• dateStyle = .full, timeStyle = .short — format complet: „duminică, 21 iulie 2024 – joi, 25 iulie 2024“

Important: dateStyle și timeStyle se aplică la ambele capete ale intervalului în mod egal. Nu se poate seta un stil diferit pentru început și sfârșit (de exemplu, .medium pentru început și .short pentru sfârșit). Dacă este necesar un stil diferit, trebuie să formatați fiecare dată cu un DateFormatter separat și să lipiți rezultatele.

import Foundation

let formatter = DateIntervalFormatter()

// Diferite combinații de stiluri
let startDate = Date()
let endDate = Date().addingTimeInterval(345600) // +4 zile
let interval = DateInterval(start: startDate, end: endDate)

// Doar data, format mediu
formatter.dateStyle = .medium
formatter.timeStyle = .none
print("Doar data: \(formatter.string(from: interval))")

// Format scurt cu timp
formatter.dateStyle = .short
formatter.timeStyle = .short
print("Scurt cu timp: \(formatter.string(from: interval))")

// Format complet
formatter.dateStyle = .full
formatter.timeStyle = .none
print("Data completă: \(formatter.string(from: interval))")

DateIntervalFormatter în Swift: exemple

Utilizarea de bază a DateIntervalFormatter include crearea unei instanțe, configurarea stilurilor și apelarea string(from:). Metoda acceptă DateInterval — o structură cu proprietățile start și end. DateInterval poate fi creat atât din două Date, cât și inițializat cu Duration (iOS 16+). După formatare, rezultatul este gata de afișare în UI fără procesare suplimentară.

import Foundation

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

// Exemple de intervale specifice
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)")
}

// Formatare prin Calendar (iOS 16+)
if let nextWeek = calendar.date(
    byAdding: .day, value: 7, to: now
) {
    let weekInterval = DateInterval(start: now, end: nextWeek)
    print("Următoarele 7 zile: \(intervalFormatter.string(from: weekInterval))")
}

DateIntervalFormatter și Calendar Booking: în aplicațiile de rezervare (hoteluri, bilete) intervalele de date sunt un element cheie al UI. DateIntervalFormatter procesează corect intervalele interanuale (de exemplu, de la 28 decembrie până la 3 ianuarie), grupând luna și anul pentru fiecare dată separat. Pentru astfel de scenarii, se recomandă utilizarea dateStyle = .medium și timeStyle = .none — cel mai lizibil format pentru date fără timp.

import Foundation

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

// Exemple de rezervare
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("Rezervare: \(booking.formattedInterval)")

// Utilizare cu diferite locale
let enFormatter = DateIntervalFormatter()
enFormatter.dateStyle = .medium
enFormatter.timeStyle = .none
enFormatter.locale = Locale(identifier: "en_US")
print("Engleză: \(enFormatter.string(from: interval))")

DateInterval vs DateIntervalFormatter: DateInterval — structură care reprezintă un interval de date (început și sfârșit). DateIntervalFormatter — formator care transformă această structură într-un șir. DateInterval acceptă, de asemenea, verificările contains(Date) și intersection(with:), ceea ce este util pentru logica de rezervare (verificarea suprapunerii datelor).

Localizarea intervalelor de date

DateIntervalFormatter localizează ieșirea prin proprietatea locale. În mod implicit, se utilizează Locale.current — locale-ul dispozitivului. Pentru a afișa intervale într-o altă limbă (de exemplu, conținut în engleză cu interfața în română), setați locale explicit. Spre deosebire de DateFormatter, DateIntervalFormatter nu necesită setarea Locale pentru datele de server — folosește întotdeauna propria logică internă de grupare bazată pe CLDR.

Diferențele lingvistice în formatarea intervalelor de date sunt semnificativ mai complexe decât pentru datele individuale. Engleza folosește o cratimă simplă: Jul 21–25. Româna — prepoziția „până la“: de la 21 până la 25 iulie. Franceza — prepoziția „au“: du 21 au 25 juillet. Germana — punct după număr și cratimă: 21.–25. Juli. Japoneza — prin cratimă fără prepoziții: Jul 21–25. DateIntervalFormatter acoperă toate aceste variante.

import Foundation

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

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

// Demonstrarea diferitelor locale
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))")
}

// Localizare pentru intervale de timp
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) ora: \(formatter.string(from: timeInterval))")
}

Particularități de localizare: pentru limba română, DateIntervalFormatter folosește prepozițiile „de la“ și „până la“ pentru formatele lungi de dată. Pentru formatul scurt (short) — doar cratimă: 21.07–25.07.2024. Pentru formatul complet (full) — cu specificarea zilei săptămânii. Alegerea formatului depinde de context: pentru lista de rezervări utilizați .medium, pentru vizualizarea detaliată — .long sau .full.

Comparație cu alte formate de date

DateIntervalFormatter ocupă nișa formatării intervalelor de date pe care nu o acoperă alte clase Foundation. DateFormatter formatează date individuale, RelativeDateTimeFormatter — date relative (în urmă/peste), DateComponentsFormatter — durata (2 ore 30 de minute). Fiecare dintre aceste clase își rezolvă propria sarcină și nu pot fi înlocuite reciproc.

Când să utilizați DateIntervalFormatter: pentru afișarea intervalelor de date în UI — rezervarea hotelurilor, evenimente, filtrare după date, istoricul operațiunilor. Pentru calcularea duratei între date, utilizați DateComponentsFormatter, nu DateIntervalFormatter — ultimul nu este destinat afișării duratei. DateFormatter trebuie utilizat doar pentru date individuale, nu pentru lipirea a două date formatate prin concatenare de șiruri — aceasta duce la pierderea localizării separatorului.

Caz limită: DateIntervalFormatter nu acceptă afișarea intervalelor deschise (fără dată de sfârșit). Dacă sfârșitul intervalului este necunoscut (de exemplu, „de la 21 iulie“), utilizați DateFormatter cu prepoziția „de la“ pentru română sau „from“ pentru engleză. DateIntervalFormatter nu acceptă nici intervale cu specificarea orei pentru zile diferite — ora se aplică fiecărei date separat, ceea ce poate părea redundant pentru intervale scurte.