DateIntervalFormatter — fondamenti della formattazione degli intervalli di date

Cos'è DateIntervalFormatter?

DateIntervalFormatter è una sottoclasse di Formatter in Foundation che prende un oggetto DateInterval (un intervallo tra due date) e restituisce una stringa localizzata che descrive quell'intervallo. Ad esempio, per l'intervallo dal 21 al 25 luglio 2024, il risultato sarebbe “21–25 luglio 2024” per it_IT. La classe raggruppa intelligentemente gli elementi ripetuti: se entrambe le date sono nello stesso mese, il nome del mese viene mostrato una volta.

Il valore principale di DateIntervalFormatter è la gestione automatica della grammatica degli intervalli. Durante la formattazione manuale, uno sviluppatore dovrebbe confrontare mese/anno di inizio e fine, scegliere un separatore (trattino, “al”, “bis”) e gestire la declinazione. DateIntervalFormatter lo fa automaticamente basandosi sui dati CLDR (Common Locale Data Repository), riducendo i bug nelle applicazioni internazionali, specialmente per lingue con grammatica complessa.

Secondo Unicode CLDR v44 (2024), le regole di formattazione degli intervalli di date variano significativamente tra le lingue. Il tedesco usa la preposizione “bis” (21.–25. Juli 2024), il francese usa “au” (du 21 au 25 juillet 2024), il giapponese usa un trattino (2024 Jul 21–25). DateIntervalFormatter copre tutte queste variazioni senza codice aggiuntivo da parte dello sviluppatore.

Come funziona DateIntervalFormatter in Foundation?

Il principio di funzionamento di DateIntervalFormatter si basa sull'analisi di due date che formano un intervallo e sulla selezione della rappresentazione testuale ottimale considerando le impostazioni regionali. La classe confronta i componenti della data (anno, mese, giorno) e prende decisioni di raggruppamento: se l'anno è lo stesso, viene mostrato una volta; se il mese è lo stesso, viene mostrato una volta; se i giorni differiscono, viene mostrato un intervallo di giorni.

Logica di raggruppamento implementata basata su modelli CLDR. Il formattatore verifica l'uguaglianza di ogni componente della data (Calendar.Component: year, month, day) in ordine dal più grande al più piccolo. Una volta che un componente differisce, tutti i componenti più piccoli vengono mostrati per entrambe le date. Ad esempio, per il 21–25 luglio: anno corrisponde, mese corrisponde, giorno differisce → il mese viene mostrato una volta, i giorni vengono mostrati per ogni data.

Nota importante: DateIntervalFormatter non supporta la personalizzazione del separatore tramite API. Il separatore è determinato dalle impostazioni regionali e non può essere sovrascritto. Se è necessario un separatore non standard (ad esempio, “da” invece di “al”), dovrai formattare le date manualmente con DateFormatter e concatenare le stringhe con un separatore personalizzato.

Stili di formattazione degli intervalli

DateIntervalFormatter fornisce due set di stili: dateStyle e timeStyle per ogni estremità dell'intervallo. Questi stili funzionano in modo simile a DateFormatter: .none nasconde il componente, .short dà un formato corto (21/07/2024), .medium (21 lug 2024), .long (21 luglio 2024), .full (domenica 21 luglio 2024). Combinando dateStyle e timeStyle, si possono ottenere diversi livelli di dettaglio.

Esempi di combinazioni di stili

• dateStyle = .medium, timeStyle = .none — solo data: “21–25 luglio 2024”
• dateStyle = .short, timeStyle = .short — data e ora: “21/07/2024, 14:30 – 25/07/2024, 16:45”
• dateStyle = .none, timeStyle = .short — solo ora: “14:30–16:45” (se le date sono uguali)
• dateStyle = .long, timeStyle = .none — data lunga: “21–25 luglio 2024”
• dateStyle = .full, timeStyle = .short — formato completo: “domenica 21 luglio 2024 – giovedì 25 luglio 2024”

Importante: dateStyle e timeStyle si applicano a entrambe le estremità dell'intervallo allo stesso modo. Non è possibile impostare stili diversi per l'inizio e la fine (ad esempio, .medium per l'inizio e .short per la fine). Se sono necessari stili diversi, devi formattare ogni data con un DateFormatter separato e concatenare i risultati.

import Foundation

let formatter = DateIntervalFormatter()

// Combinazioni di stili diverse
let startDate = Date()
let endDate = Date().addingTimeInterval(345600) // +4 giorni
let interval = DateInterval(start: startDate, end: endDate)

// Solo data, formato medio
formatter.dateStyle = .medium
formatter.timeStyle = .none
print("Solo data: \(formatter.string(from: interval))")

// Formato breve con ora
formatter.dateStyle = .short
formatter.timeStyle = .short
print("Breve con ora: \(formatter.string(from: interval))")

// Formato completo
formatter.dateStyle = .full
formatter.timeStyle = .none
print("Data completa: \(formatter.string(from: interval))")

DateIntervalFormatter in Swift: esempi

Utilizzo di base di DateIntervalFormatter include la creazione di un'istanza, l'impostazione degli stili e la chiamata a string(from:). Il metodo accetta DateInterval, una struttura con proprietà start e end. DateInterval può essere creato da due valori Date o inizializzato con Duration (iOS 16+). Dopo la formattazione, il risultato è pronto per la visualizzazione nell'interfaccia senza elaborazione aggiuntiva.

import Foundation

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

// Esempi di intervalli specifici
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)")
}

// Formattazione tramite Calendar (iOS 16+)
if let nextWeek = calendar.date(
    byAdding: .day, value: 7, to: now
) {
    let weekInterval = DateInterval(start: now, end: nextWeek)
    print("Prossimi 7 giorni: \(intervalFormatter.string(from: weekInterval))")
}

DateIntervalFormatter e prenotazioni calendario: nelle applicazioni di prenotazione (hotel, biglietti), gli intervalli di date sono un elemento chiave dell'interfaccia. DateIntervalFormatter gestisce correttamente gli intervalli tra anni (ad esempio, dal 28 dicembre al 3 gennaio), raggruppando mese e anno separatamente per ogni data. Per tali scenari, si consiglia di utilizzare dateStyle = .medium e timeStyle = .none, il formato più leggibile per le date senza ora.

import Foundation

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

// Esempi di prenotazione
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("Prenotazione: \(booking.formattedInterval)")

// Utilizzo con diverse impostazioni regionali
let enFormatter = DateIntervalFormatter()
enFormatter.dateStyle = .medium
enFormatter.timeStyle = .none
enFormatter.locale = Locale(identifier: "en_US")
print("Inglese: \(enFormatter.string(from: interval))")

DateInterval vs DateIntervalFormatter: DateInterval è una struttura che rappresenta un intervallo di date (inizio e fine). DateIntervalFormatter è un formattatore che converte questa struttura in una stringa. DateInterval supporta anche controlli contains(Date) e intersection(with:), utili per la logica di prenotazione (verifica sovrapposizione date).

Localizzazione degli intervalli di date

DateIntervalFormatter localizza l'output tramite la proprietà locale. Per impostazione predefinita, viene utilizzato Locale.current, le impostazioni regionali del dispositivo. Per visualizzare intervalli in un'altra lingua (ad esempio, contenuto in inglese con interfaccia italiana), imposta esplicitamente la locale. A differenza di DateFormatter, DateIntervalFormatter non richiede l'impostazione della locale per i dati lato server. Utilizza sempre la sua logica di raggruppamento interna basata su CLDR.

Le differenze linguistiche nella formattazione degli intervalli di date sono significativamente più complesse che per le date singole. L'italiano usa la preposizione “al”: dal 21 al 25 luglio. L'inglese usa un semplice trattino: Jul 21–25. Il francese usa la preposizione “au”: du 21 au 25 juillet. DateIntervalFormatter copre tutte queste varianti.

import Foundation

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

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

// Mostrare diverse impostazioni regionali
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))")
}

// Localizzazione per intervalli di tempo
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))")
}

Specificità di localizzazione: per l'italiano, DateIntervalFormatter usa “al” per i formati lunghi. Per i formati brevi, usa il trattino. La scelta del formato dipende dal contesto: per un elenco di prenotazioni usa .medium, per la vista dettagliata usa .long o .full.

Confronto con altri formattatori di date

DateIntervalFormatter occupa la nicchia della formattazione degli intervalli di date, che non è coperta da altre classi Foundation. DateFormatter formatta date singole, RelativeDateTimeFormatter formatta date relative (fa/in), DateComponentsFormatter formatta la durata (2 ore 30 minuti). Ognuna di queste classi risolve un compito specifico e non possono essere usate in modo intercambiabile.

Quando usare DateIntervalFormatter: per visualizzare intervalli di date nell'interfaccia — prenotazioni hotel, eventi, filtraggio per date, cronologia operazioni. Per calcolare la durata tra date, usa DateComponentsFormatter, non DateIntervalFormatter, poiché quest'ultimo non è progettato per visualizzare la durata. DateFormatter dovrebbe essere usato solo per date singole, non per concatenare due date formattate tramite concatenazione di stringhe, poiché ciò porta alla perdita della localizzazione del separatore.

Cas limite: DateIntervalFormatter non supporta la visualizzazione di intervalli aperti (senza data di fine). Se la fine dell'intervallo è sconosciuta (ad esempio, “dal 21 luglio”), usa DateFormatter con la preposizione “dal”. Inoltre, DateIntervalFormatter non supporta intervalli con ora specificata per giorni diversi. L'ora viene applicata a ciascuna data separatamente, il che può sembrare ridondante per intervalli brevi.