TimeZone — mi ez, Foundation osztály és időzónák

Mi az a TimeZone a Foundation-ben?

TimeZone — egy értéktípus Swiftben, amely információt nyújt egy földrajzi időzónáról: az UTC-hez viszonyított eltolást, nevet, rövidítést és a nyári időszámításra való áttérés szabályait. Az Objective-C-ben az osztály neve NSTimeZone. Mindkét osztály az IANA Time Zone Database-re (más néven Olson adatbázisra) támaszkodik, amely az 1970 óta történt időzóna-változások történetét tartalmazza.

Minden TimeZone példány tárolja az időzóna azonosítóját (pl. Europe/Moscow), az aktuális eltolást másodpercekben az UTC-től, az isDaylightSavingTime jelzőt és a következő áttérés dátumát. Az azonosító az elsődleges kulcs: a TimeZone(identifier:) inicializálásakor a rendszer betölti a megfelelő rekordot az eszköz időzóna-adatbázisából.

Az IANA (2024) adatai szerint az adatbázis több mint 600 egyedi időzóna-azonosítót tartalmaz. Az Apple az iOS és macOS minden verziójában szállítja ennek az adatbázisnak egy részét, garantálva a számítások egységességét minden eszközön hálózati kérések nélkül.

Hogyan működik a TimeZone iOS-ben és macOS-ben?

Architektúra — a Foundation-ben a TimeZone egy kétszintű rendszerre épül: az időzóna-azonosítóra (egy ember által olvasható név) és annak számítógépes megjelenítésére (az UTC-től való eltolás). A rendszer automatikusan kiválasztja az aktuális időzónát az eszköz beállításaiból, de a fejlesztő felülírhatja azt bizonyos formázási műveletekhez.

A TimeZone szorosan kapcsolódik a Calendar és DateFormatter osztályokhoz. Dátum formázásakor a DateFormatter a TimeZone példány timeZone tulajdonságát használja az abszolút időpillanat (Date) szöveges megjelenítéssé alakításához a megfelelő időzónában. Ha a timeZone nincs beállítva, az alapértelmezett rendszer-időzóna kerül használatra — TimeZone.current.

A TimeZone példányok típusai

Fontos nuansz: A TimeZone(identifier:) nil értéket ad vissza ismeretlen azonosítók esetén. Ez az alkalmazás összeomlásának gyakori oka — a fejlesztők elfelejtik kezelni az opcionális értéket, és hibás azonosítót adnak át a felhasználói bevitelből. Az IANA azonosítóknál a következő betűméret számít: Europe/Moscow — helyes, europe/moscow — nil.

Időzóna-azonosítók formátumai

IANA Time Zone Database a „Régió/Város” (Continent/City) formátumot használja, ahol a régió az egyik kontinens (Africa, America, Asia, Atlantic, Australia, Europe, Indian, Pacific) vagy óceán, a város pedig az időzóna övezetében lévő legnagyobb település. Ez a formátum garantálja az azonosító egyediségét és olvashatóságát.

Az alapformátumon kívül a TimeZone három további azonosítási módot támogat: rövidítéseket (MSK, EST, PST), hárombetűs időzóna-kódokat (GMT, UTC) és numerikus eltolásokat (+0300, -0500). A rövidítések azonban félreérthetők: az EST jelölheti mind az Eastern Standard Time (GMT-5), mind az Eastern Summer Time (GMT+10) időt Ausztráliában. Az Apple kizárólag IANA azonosítók használatát ajánlja.

import Foundation

// Az összes ismert időzóna-azonosító lekérése
let allIdentifiers: [String] = TimeZone.knownTimeZoneIdentifiers
print("Összes időzóna: \(allIdentifiers.count)")

// Szűrés régió szerint
let europeZones = allIdentifiers.filter { $0.hasPrefix("Europe/") }
print("Európai időzónák: \(europeZones)")

// Rövidítések (nem ajánlott production célokra)
if let moscowTimeZone = TimeZone(abbreviation: "MSK") {
    print("MSK másodpercek GMT-től: \(moscowTimeZone.secondsFromGMT())")
}

// Azonosító keresése eltolás alapján
let utcPlus3 = TimeZone(secondsFromGMT: 10800)
print("Azonosító: \(utcPlus3.identifier)")

Rövidítések a TimeZone.abbreviationDictionary-ben az összes ismert időzóna rövidítéseit tartalmazzák, de ez a szótár nem garantálja az egyediséget: a PST kulcs megfelelhet mind az America/Los_Angeles, mind a Pacific/Pago_Pago címnek. Production kódban mindig IANA azonosítókat használjon.

Nyári időszámításra való áttérés és TimeZone

TimeZone automatikusan figyelembe veszi a nyári és téli időszámításra való áttérést (DST — Daylight Saving Time) minden olyan régióban, ahol ez szokásos. A rendszer az IANA Time Zone Database történelmi adatait használja, amelyek minden időzóna pontos áttérési dátumait tartalmazzák. Az isDaylightSavingTime tulajdonság true értéket ad vissza, ha az időzóna jelenleg nyári időszámításban van.

A nextDaylightSavingTimeTransition metódus lehetővé teszi a következő áttérés dátumának megtudását, ami hasznos a jövőbeli események tervezéséhez. Ez a funkció különösen fontos a gyakori DST-szabályváltozásokkal rendelkező régiókban, mint Brazília vagy Marokkó — 2024-ig Brazília évente változtatta az áttérési dátumokat, és a kézi számítás hibákhoz vezetett az alkalmazásokban.

Az Apple WWDC 2023 adatai szerint az ICU (International Components for Unicode) könyvtár, amely a Foundation alapját képezi, minden iOS-frissítésnél frissíti a DST adatokat. Az alkalmazások nem tárolhatják gyorsítótárban a nyári időszámítással kapcsolatos adatokat több mint egy napig a rendszerfrissítés után — az IANA adatbázis akár az operációs rendszer verziójának frissítése nélkül is megváltozhat időzóna-korrekciók révén.

import Foundation

// DST ellenőrzése Europe/Moscow esetén
let moscow = TimeZone(identifier: "Europe/Moscow")!
let now = Date()
let isMoscowDST = moscow.isDaylightSavingTime(for: now)
print("Moszkva jelenleg DST-ben: \(isMoscowDST)")

// Következő DST-áttérés dátumának lekérése
if let nextTransition = moscow.nextDaylightSavingTimeTransition(
    after: now
) {
    let dstOffset = moscow.daylightSavingTimeOffset(
        for: nextTransition
    )
    print("Következő áttérés: \(nextTransition), DST eltolás: \(dstOffset)s")
}

// Biztonságos konverzió DST-tudatossággal
let newYork = TimeZone(identifier: "America/New_York")!
let offsetNY = newYork.secondsFromGMT(for: now)
print("NY aktuális eltolása: \(offsetNY / 3600)h")

Kritikus nuansz: A secondsFromGMT(for:) figyelembe veszi a DST-t a megadott dátumra, míg a secondsFromGMT() csak az aktuális időre. Történelmi dátumok formázásakor mindig a Date paraméteres változatot használja: secondsFromGMT(for: someHistoricalDate). A különbség elérheti az 1–2 órát, ami kritikus a naplók vagy történelmi adatok szempontjából.

TimeZone Swiftben: kódpéldák

Dátum formázása egy adott időzónával — a leggyakoribb feladat a TimeZone-zal való munka során. A DateFormatter a timeZone tulajdonságot használja a Date szöveggé alakításához. Ha a timeZone nincs expliciten beállítva, a formázó a TimeZone.current — a felhasználó eszközén beállított időzónát használja, ami váratlan eredményekhez vezethet a szerver adatoknál.

import Foundation

// Dátum formázása adott időzónában
let formatter = DateFormatter()
formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"

let tokyo = TimeZone(identifier: "Asia/Tokyo")!
formatter.timeZone = tokyo
let tokyoTime = formatter.string(from: Date())
print("Tokió ideje: \(tokyoTime)")

// Elérhető azonosítók a felhasználói kiválasztáshoz
let displayNames: [(String, String)] = TimeZone.knownTimeZoneIdentifiers
    .prefix(20)
    .map { ($0, TimeZone(identifier: $0)!.localizedName(
        for: .generic, locale: .current
    )) }

// Két időzóna összehasonlítása
let london = TimeZone(identifier: "Europe/London")!
let difference = tokyo.secondsFromGMT(for: Date())
    - london.secondsFromGMT(for: Date())
print("Tokió-London különbség: \(difference / 3600)h")

// Munka a rövidítésszótárral
let knownAbbrevs = TimeZone.abbreviationDictionary
for (abbr, ident) in knownAbbrevs.sorted(by: { $0.key < $1.key }).prefix(5) {
    print("\(abbr) -> \(ident)")
}

Lokalizált név — a localizedName(for:locale:) módszer az időzóna ember által olvasható nevét adja vissza a megadott nyelven. Például az Europe/Moscow esetén orosz területi beállítással a módszer „Moszkva” értéket ad vissza, angollal pedig „Moscow Time” értéket. Elérhető stílusok: .standard (szabvány név), .daylightSaving (nyári időszámítás) és .shortGeneric (rövid).

import Foundation

let paris = TimeZone(identifier: "Europe/Paris")!
let nameRU = paris.localizedName(
    for: .standard,
    locale: Locale(identifier: "ru_RU")
)
print("Orosz név: \(nameRU)")

// Annak ellenőrzése, hogy a régió ugyanabban a napban van-e
let isSameDay = Calendar.current.isDate(
    Date(),
    equalTo: Date(),
    toGranularity: .day
)
print("Ugyanaz a nap különböző időzónákban: \(isSameDay)")

Szérializáció — az időzóna-azonosító tárolása a legjobb gyakorlat a TimeZone adatbázisokban vagy UserDefaults-ban való tárolásához. Mentse az azonosítót (Europe/Moscow típusú sztringet), ne az eltolást másodpercekben vagy a rövidítést. Az eltolás változhat a DST változásakor, a rövidítés pedig félreérthető. Helyreállítás: TimeZone(identifier: savedString).

Gyakori hibák a TimeZone-zal való munka során

Rögzített eltolás használata az időzóna-azonosító helyett — a leggyakoribb hiba. A TimeZone(secondsFromGMT: 10800) nem veszi figyelembe a DST-t, ezért az Europe/Moscow esetén nyáron ez a konstrukció 1 órával téves eltolást ad. Mindig IANA azonosítót használjon a nyári időszámítással rendelkező régiókhoz.

Elfelejtett nil-kezelés a TimeZone(identifier:) inicializálásakor — a második leggyakoribb hiba. Ha a felhasználó hibás azonosítót ad meg (pl. „moscow” a „Europe/Moscow” helyett), a konstruktor nil értéket ad vissza. Az opcionális érték kezelése nélkül az alkalmazás futási hibával összeomlik. Használjon guard let vagy TimeZone(identifier:) ismert fallbackkel.

A DST figyelmen kívül hagyása a jövőbeli dátumokkal való munka során. A TimeZone.secondsFromGMT(for:) az egyetlen helyes módszer az eltolás megszerzésére egy adott dátumra. A secondsFromGMT() paraméter nélküli használata történelmi vagy jövőbeli dátumok esetén az aktuális pillanat eltolását adja, ami nem feltétlenül felel meg a tényleges eltolásnak az adott dátumon, különösen a DST-t eltörlő vagy bevezető régiókban.

A Stack Overflow (2024) adatai szerint a DateFormatter-rel kapcsolatos kérdések körülbelül 15%-a a timeZone helytelen beállításához kapcsolódik. Tipikus forgatókönyv: a szerver UTC-ben küldi a dátumot, a fejlesztő formázza azt a formázó timeZone-jának beállítása nélkül, és a dátum az eszköz időzónájában jelenik meg, zavart okozva a különböző régiókból származó felhasználók számára. Szabály: mindig expliciten állítsa be a formázó timeZone-ját a szerver adatokhoz.