DateIntervalFormatter — mga batayan, pag-format ng mga interval ng petsa

Ano ang DateIntervalFormatter?

DateIntervalFormatter ay isang subclass ng Formatter sa Foundation na tumatanggap ng isang DateInterval object (saklaw sa pagitan ng dalawang petsa) at nagbabalik ng isang lokalisadong string na may paglalarawan ng saklaw na ito. Halimbawa, para sa saklaw mula 21 hanggang 25 Hulyo 2024, ang resulta ay magiging “21–25 Hulyo 2024” para sa fil_PH at “Jul 21–25, 2024” para sa en_US. Matalinong pinapangkat ng klase ang mga umuulit na elemento: kung ang parehong petsa ay nasa parehong buwan, ang pangalan ng buwan ay ipinapakita nang isang beses.

Ang pangunahing halaga ng DateIntervalFormatter ay ang awtomatikong pagproseso ng gramatika ng saklaw. Sa manu-manong pag-format, kailangang ihambing ng developer ang buwan/taon ng simula at pagtatapos, pumili ng separator (gitling, “mula–hanggang”, “to”, “bis”) at subaybayan ang deklinasyon. Awtomatikong ginagawa ito ng DateIntervalFormatter batay sa data ng CLDR (Common Locale Data Repository), na nagbabawas ng bilang ng mga bug sa mga internasyonal na aplikasyon, lalo na para sa mga wikang may kumplikadong gramatika.

Ayon sa Unicode CLDR v44 (2024), ang mga panuntunan sa pag-format ng mga saklaw ng petsa ay malaki ang pagkakaiba sa pagitan ng mga wika. Ang Aleman ay gumagamit ng pang-ukol na “bis” (21.–25. Juli 2024), Pranses — “au” (du 21 au 25 juillet 2024), Hapon — sa pamamagitan ng gitling (2024 Jul 21–25). Sinasaklaw ng DateIntervalFormatter ang lahat ng mga baryasyong ito nang walang karagdagang code mula sa developer.

Paano gumagana ang DateIntervalFormatter sa Foundation?

Prinsipyo ng pagpapatakbo ng DateIntervalFormatter ay batay sa pagsusuri ng dalawang petsa na bumubuo sa saklaw at pagpili ng pinakamainam na representasyon ng teksto na isinasaalang-alang ang locale. Inihahambing ng klase ang mga bahagi ng petsa (taon, buwan, araw) at gumagawa ng desisyon tungkol sa pagpapangkat: kung ang taon ay pareho — ipinapakita nang isang beses; kung ang buwan ay pareho — ipinapakita nang isang beses; kung ang mga araw ay magkaiba — ang saklaw ng araw ay ipinapakita.

Lohika ng pagpapangkat ay ipinatupad batay sa mga pattern ng CLDR. Sinusuri ng pemformat ang pagkakapantay-pantay ng bawat bahagi ng petsa (Calendar.Component: year, month, day) sa pagkakasunud-sunod mula sa pinakamalaki hanggang sa pinakamaliit. Sa sandaling mag-iba ang isang bahagi, ang lahat ng mas maliit na bahagi ay ipinapakita para sa parehong petsa. Halimbawa, para sa 21–25 Hulyo: ang taon ay tumutugma, ang buwan ay tumutugma, ang araw ay magkaiba → buwan nang isang beses, mga araw — para sa bawat petsa nang hiwalay.

Mahalagang nuance: Hindi sinusuportahan ng DateIntervalFormatter ang pagsasaayos ng separator sa pamamagitan ng API. Ang separator ay tinutukoy ng locale at hindi maaaring ma-override. Kung kinakailangan ang isang pasadyang separator (halimbawa, “hanggong” sa halip na “–”), kailangan mong i-format ang mga petsa nang manu-mano sa pamamagitan ng DateFormatter at pagsamahin ang mga string gamit ang isang pasadyang separator.

Mga estilo ng pag-format ng interval

DateIntervalFormatter ay nagbibigay ng dalawang set ng estilo: dateStyle at timeStyle — para sa bawat dulo ng saklaw. Ang mga estilo na ito ay gumagana katulad ng DateFormatter: .none itinatago ang bahagi, .short nagbibigay ng maikling format (21.07.2024), .medium — katamtaman (21 Hul 2024), .long — mahaba (21 Hulyo 2024), .full — pinakadetalyado (Linggo, 21 Hulyo 2024). Sa pamamagitan ng pagsasama-sama ng dateStyle at timeStyle, maaaring makuha ang iba’t ibang antas ng detalye.

Mga halimbawa ng kombinasyon ng estilo

• dateStyle = .medium, timeStyle = .none — petsa lamang: “21–25 Hulyo 2024”
• dateStyle = .short, timeStyle = .short — petsa at oras: “21.07.2024, 14:30 – 25.07.2024, 16:45”
• dateStyle = .none, timeStyle = .short — oras lamang: “14:30–16:45” (kung pareho ang mga petsa)
• dateStyle = .long, timeStyle = .none — mahabang petsa: “21–25 Hulyo 2024”
• dateStyle = .full, timeStyle = .short — buong format: “Linggo, 21 Hulyo 2024 – Huwebes, 25 Hulyo 2024”

Mahalaga: ang dateStyle at timeStyle ay pantay na inilalapat sa parehong dulo ng saklaw. Hindi maaaring magtakda ng iba’t ibang estilo para sa simula at wakas (halimbawa, .medium para sa simula at .short para sa wakas). Kung kinakailangan ang iba’t ibang estilo, dapat mong i-format ang bawat petsa gamit ang isang hiwalay na DateFormatter at pagsamahin ang mga resulta.

import Foundation

let formatter = DateIntervalFormatter()

// Iba’t ibang kombinasyon ng estilo
let startDate = Date()
let endDate = Date().addingTimeInterval(345600) // +4 na araw
let interval = DateInterval(start: startDate, end: endDate)

// Petsa lamang, katamtamang format
formatter.dateStyle = .medium
formatter.timeStyle = .none
print("Petsa lamang: \(formatter.string(from: interval))")

// Maikling format na may oras
formatter.dateStyle = .short
formatter.timeStyle = .short
print("Maikli na may oras: \(formatter.string(from: interval))")

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

DateIntervalFormatter sa Swift: mga halimbawa

Pangunahing paggamit ng DateIntervalFormatter ay kinabibilangan ng paglikha ng instance, pagsasaayos ng mga estilo, at pagtawag ng string(from:). Tinatanggap ng pamamaraan ang DateInterval — isang istraktura na may mga katangiang start at end. Ang DateInterval ay maaaring likha mula sa dalawang Date, o pasimulan ng Duration (iOS 16+). Pagkatapos ng pag-format, ang resulta ay handa nang ipakita sa UI nang walang karagdagang pagproseso.

import Foundation

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

// Mga halimbawa ng tiyak na interval
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)")
}

// Pag-format sa pamamagitan ng Calendar (iOS 16+)
if let nextWeek = calendar.date(
    byAdding: .day, value: 7, to: now
) {
    let weekInterval = DateInterval(start: now, end: nextWeek)
    print("Susunod na 7 araw: \(intervalFormatter.string(from: weekInterval))")
}

DateIntervalFormatter at Calendar Booking: sa mga application ng pag-book (hotel, tiket) ang mga saklaw ng petsa ay isang pangunahing elemento ng UI. Tamang pinoproseso ng DateIntervalFormatter ang mga saklaw na cross-year (halimbawa, mula 28 Disyembre hanggang 3 Enero), pinapangkat ang buwan at taon para sa bawat petsa nang hiwalay. Para sa mga ganitong sitwasyon, inirerekomenda ang paggamit ng dateStyle = .medium at timeStyle = .none — ang pinakamabasang format para sa mga petsa nang walang oras.

import Foundation

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

// Mga halimbawa ng pag-book
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("Pag-book: \(booking.formattedInterval)")

// Paggamit sa iba’t ibang locale
let enFormatter = DateIntervalFormatter()
enFormatter.dateStyle = .medium
enFormatter.timeStyle = .none
enFormatter.locale = Locale(identifier: "en_US")
print("Ingles: \(enFormatter.string(from: interval))")

DateInterval vs DateIntervalFormatter: DateInterval — istraktura na kumakatawan sa isang saklaw ng petsa (simula at wakas). DateIntervalFormatter — pemformat na nagko-convert ng istrakturang ito sa isang string. Sinusuportahan din ng DateInterval ang mga pagsusuri ng contains(Date) at intersection(with:), na kapaki-pakinabang para sa lohika ng pag-book (pagsusuri ng overlap ng petsa).

Lokalisasyon ng mga interval ng petsa

DateIntervalFormatter ay nilolokalisa ang output sa pamamagitan ng property na locale. Bilang default, ginagamit ang Locale.current — locale ng device. Upang magpakita ng mga interval sa ibang wika (halimbawa, nilalaman sa Ingles sa interface ng Tagalog), itakda ang locale nang tahasan. Hindi tulad ng DateFormatter, ang DateIntervalFormatter ay hindi nangangailangan ng pagtatakda ng Locale para sa data ng server — palaging ginagamit ang sarili nitong panloob na lohika ng pagpapangkat batay sa CLDR.

Ang mga pagkakaiba sa wika sa pag-format ng mga saklaw ng petsa ay mas kumplikado kaysa sa mga indibidwal na petsa. Ang Ingles ay gumagamit ng simpleng gitling: Jul 21–25. Ang Tagalog — pang-ukol na “mula–hanggang”: mula 21 hanggang 25 Hulyo. Ang Pranses — pang-ukol na “au”: du 21 au 25 juillet. Ang Aleman — tuldok pagkatapos ng numero at gitling: 21.–25. Juli. Ang Hapon — sa pamamagitan ng gitling na walang pang-ukol: Jul 21–25. Sinasaklaw ng DateIntervalFormatter ang lahat ng mga variant na ito.

import Foundation

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

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

// Pagpapakita ng iba’t ibang 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))")
}

// Lokalisasyon para sa mga interval ng oras
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) oras: \(formatter.string(from: timeInterval))")
}

Mga tampok ng lokalisasyon: para sa Tagalog, ang DateIntervalFormatter ay gumagamit ng mga pang-ukol na “mula” at “hanggang” para sa mahabang format ng petsa. Para sa maikling (short) format — gitling lamang: 21.07–25.07.2024. Para sa buong format (full) — na may pagbanggit ng araw ng linggo. Ang pagpili ng format ay depende sa konteksto: para sa listahan ng pag-book gamitin ang .medium, para sa detalyadong pagtingin — .long o .full.

Paghahambing sa iba pang mga pemformat ng petsa

DateIntervalFormatter ay pumupuno sa angkop na lugar ng pag-format ng mga saklaw ng petsa na hindi sakop ng ibang mga klase ng Foundation. Ang DateFormatter ay nagfo-format ng mga indibidwal na petsa, RelativeDateTimeFormatter — mga kaugnay na petsa (nakaraan/sa hinaharap), DateComponentsFormatter — tagal (2 oras 30 minuto). Ang bawat isa sa mga klaseng ito ay lumulutas ng sarili nitong gawain at hindi maaaring palitan.

Kailan gagamitin ang DateIntervalFormatter: para sa pagpapakita ng mga saklaw ng petsa sa UI — pag-book ng hotel, mga kaganapan, pag-filter ayon sa petsa, kasaysayan ng operasyon. Para sa pagkalkula ng tagal sa pagitan ng mga petsa gamitin ang DateComponentsFormatter, hindi ang DateIntervalFormatter — ang huli ay hindi idinisenyo para sa pagpapakita ng tagal. Ang DateFormatter ay dapat gamitin lamang para sa mga indibidwal na petsa, hindi para sa pagsasama ng dalawang na-format na petsa sa pamamagitan ng pagsasama ng string — ito ay humahantong sa pagkawala ng lokalisasyon ng separator.

Gilid na kaso: Hindi sinusuportahan ng DateIntervalFormatter ang pagpapakita ng mga bukas na saklaw (nang walang petsa ng pagtatapos). Kung ang dulo ng saklaw ay hindi alam (halimbawa, “mula 21 Hulyo”), gamitin ang DateFormatter na may pang-ukol na “mula” para sa Tagalog o “from” para sa Ingles. Hindi rin sinusuportahan ng DateIntervalFormatter ang mga saklaw na may pagbanggit ng oras para sa iba’t ibang araw — ang oras ay inilalapat sa bawat petsa nang hiwalay, na maaaring mukhang kalabisan para sa mga maikling saklaw.