ISO8601DateFormatter: kulcsfogalmak és ISO 8601 formázás

Mi az ISO8601DateFormatter?

ISO8601DateFormatter — a Formatter egy specializált alosztálya a Foundation-ben, amely kétirányú konverziót valósít meg a Date és egy ISO 8601 formátumú string között. Az ISO 8601 szabvány (International Standard for the Representation of Dates and Times) meghatározza a nemzetközi dátum- és időcserélő formátumot: 2024-07-21T14:30:00+00:00. A DateFormatter-rel ellentétben ez az osztály nem igényli a dateFormat megadását, és automatikusan meghatározza a string szerkezetét a megadott opciók alapján.

Az ISO8601DateFormatter fő előnyei a DateFormatter-rel szemben: a locale-tól való függetlenség (a parse-olás minden eszközön ugyanúgy működik), beépített támogatás a másodperc törtekhez (bármilyen számú tizedesjeggyel) és a formátum automatikus meghatározása a megadott opciók alapján. Az osztály helyesen kezeli a Z-utótagot (UTC jelölés), a +HH:mm formátumú időzónákat és a csökkentett pontosságot (csak dátum idő nélkül).

A ISO Specification (ISO 8601-1:2019) szerint a szabvány négy pontossági szintet támogat: év (2024), év-hónap (2024-07), teljes dátum (2024-07-21) és dátum-idő időzónával (2024-07-21T14:30:00+00:00). Az ISO8601DateFormatter ezeket a szinteket a formátumopciók kombinálásával fedi le, megszabadítva a fejlesztőt a dateFormat string manuális összeállításától.

Hogyan működik az ISO8601DateFormatter a Foundation-ben?

Működési elv Az ISO8601DateFormatter bitopciók (formatOptions) kombinációján alapul, amelyek mindegyike egy adott dátum- vagy időkomponenst aktivál a kimenetben. Például a .withFullDate opció aktiválja az évet, hónapot és napot; a .withTime — az órákat, perceket és másodperceket. Az opciók kombinálásával a fejlesztő eléri a kívánt pontossági szintet anélkül, hogy dateFormat stringet kellene írnia.

Belsőleg az ISO8601DateFormatter az ICU könyvtárat használja a parse-oláshoz, de rögzített ISO 8601 szabályokkal. Ez azt jelenti, hogy figyelmen kívül hagyja az eszközön beállított Locale és TimeZone beállításokat — az eredmény mindig kiszámítható. Az időzóna beállításához a timeZone tulajdonság használatos, amely alapértelmezetten UTC-vel egyenlő. Ha a timeZone nil értékre van állítva, az eszköz helyi ideje kerül felhasználásra.

Opciók kombinálása: A .withInternetDateTime egyenlő a .withFullDate, .withTime és .withTimeZone kombinálásával. A milliszekundumos stringek parse-olásához adja hozzá a .withFractionalSeconds-t. Fontos megjegyezni, hogy a .withMilliseconds a másodperc törteket három karakterre korlátozza, míg a .withFractionalSeconds bármilyen pontosságot támogat — egy és kilenc tizedesjegy között.

Az ISO 8601 formátum beállításai

Formátum opciók Az ISO8601DateFormatter három csoportra oszlik: dátumkomponensek (withFullDate, withYear, withMonth, withDay, withWeekOfYear), időkomponensek (withTime, withHours, withMinutes, withSeconds) és kiegészítő beállítások (withMilliseconds, withFractionalSeconds, withTimeZone, withColonSeparatorInTimeZone, withDashSeparatorInDate, withFullTime). Ezek kombinálásával gyakorlatilag bármilyen ISO 8601 alformátum előállítható.

Fő opció kombinációk

• .withFullDate — csak dátum: 2024-07-21. YYYY-MM-DD formátumú stringek parse-olásához
• .withFullDate + .withTime — dátum és idő időzóna nélkül: 2024-07-21T14:30:00
• .withInternetDateTime — teljes formátum: 2024-07-21T14:30:00Z vagy 2024-07-21T14:30:00+03:00
• .withInternetDateTime + .withFractionalSeconds — másodperc törtekkel: 2024-07-21T14:30:00.123456+00:00
• .withFullDate + .withTime + .withTimeZone — teljes formátum kettőspont nélkül a tz-ben: 2024-07-21T14:30:00+0300

Fontos árnyalat: A .withFractionalSeconds és .withMilliseconds kölcsönösen kizárják egymást — ha mindkettő be van állítva, a .withFractionalSeconds érvényesül. A szerveradatokból történő milliszekundum parse-oláshoz a .withFractionalSeconds ajánlott, mivel sok szerver három, hat vagy kilenc karakterrel küldi a másodperc törteket, és a .withFractionalSeconds bármilyen hosszt kezel.

import Foundation

// ISO8601DateFormatter konfigurálása
let formatter = ISO8601DateFormatter()
formatter.timeZone = TimeZone(secondsFromGMT: 0)

// Különböző formátum opció kombinációk
formatter.formatOptions = [.withFullDate]
let dateOnly = formatter.string(from: Date())
print("Dátum: \(dateOnly)")

formatter.formatOptions = [.withFullDate, .withTime]
let dateTime = formatter.string(from: Date())
print("DateTime: \(dateTime)")

formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
let full = formatter.string(from: Date())
print("Teljes: \(full)")

// String parse-olása milliszekundumokkal
let serverString = "2024-07-21T14:30:00.123456+03:00"
if let parsed = formatter.date(from: serverString) {
    print("Parse-olva: \(parsed)")
}

ISO8601DateFormatter Swift-ben: kódpéldák

Alapvető használat Az ISO8601DateFormatter használata egy példány létrehozására, a timeZone (szerveradatokhoz UTC ajánlott) és formatOptions beállítására redukálódik, ezután meghívható a string(from:) formázáshoz és a date(from:) parse-oláshoz. A DateFormatter-rel ellentétben nem kell aggódni a Locale miatt — az osztály figyelmen kívül hagyja a regionális beállításokat.

import Foundation

let formatter = ISO8601DateFormatter()

// Különböző ISO 8601 formátumok parse-olása
let strings: [String] = [
    "2024-07-21T14:30:00Z",
    "2024-07-21T14:30:00+03:00",
    "2024-07-21T14:30:00.123Z",
    "2024-07-21"
]

for str in strings {
    if let autoParsed = formatter.date(from: str) {
        print("Parse-olva '\(str)': \(autoParsed)")
    } else {
        // Használja a withFullDate-t csak dátum stringekhez
        formatter.formatOptions = [.withFullDate]
        if let fallback = formatter.date(from: str) {
            print("Fallback parse-olva '\(str)': \(fallback)")
        }
        formatter.formatOptions = [.withInternetDateTime]
    }
}

// Szerializálás RFC 3339-re (GitHub API)
formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
let rfc3339 = formatter.string(from: Date())
print("RFC 3339: \(rfc3339)")

Változó hosszúságú tört másodperceket tartalmazó dátumok parse-olása — számos modern API jellemzője. A szerver küldhet 2024-07-21T14:30:00.123Z (3 karakter) és 2024-07-21T14:30:00.123456Z (6 karakter) formátumot is. Az ISO8601DateFormatter a .withFractionalSeconds opcióval mindkét változatot helyesen kezeli, míg a DateFormatter a dateFormat = „yyyy-MM-dd’T’HH:mm:ss.SSSZ” beállítással csak a háromjegyű milliszekundumokat dolgozza fel.

import Foundation

let variantFormatter = ISO8601DateFormatter()
variantFormatter.formatOptions = [
    .withInternetDateTime,
    .withFractionalSeconds
]

// Különböző tört másodperc pontosság
let variants: [String] = [
    "2024-07-21T14:30:00.1Z",
    "2024-07-21T14:30:00.12Z",
    "2024-07-21T14:30:00.123Z",
    "2024-07-21T14:30:00.123456Z",
    "2024-07-21T14:30:00.123456789Z"
]

for variant in variants {
    if let parsed = variantFormatter.date(from: variant) {
        print("OK: \(variant) -> \(parsed)")
    } else {
        print("FAIL: \(variant)")
    }
}

// Használja a withMilliseconds-t (csak 3 számjegy)
variantFormatter.formatOptions = [
    .withInternetDateTime,
    .withMilliseconds
]
let milliParsed = variantFormatter.string(from: Date())
print("Milliszekundumokkal: \(milliParsed)")

Az összes változat parse-olásának tesztelése: a fenti kód bemutatja, hogy az ISO8601DateFormatter a .withFractionalSeconds segítségével sikeresen feldolgozza a másodperc törteket bármilyen, 1 és 9 karakter közötti hosszúságban. Ez fontos a különböző szerverplatformokkal való kompatibilitáshoz: a .NET gyakran 7 karaktert (100 nanomásodperces tick-eket), a Python — 6, a Java — verziótól függően 3 vagy 9 karaktert generál.

Összehasonlítás a DateFormatter-rel ISO 8601 esetén

DateFormatter szintén képes parse-olni ISO 8601-et, de manuálisan kell beállítani a dateFormat, locale és timeZone értékeket. A fő probléma, hogy a DateFormatter függ a Locale-tól, és ha nincs beállítva en_US_POSIX, a parse-olás meghibásodhat a nem szabványos dátumformátumú régiókban élő felhasználóknál. Az ISO8601DateFormatter ezt a problémát architektúra szinten oldja meg: nem használ Locale-t.

Mikor használjuk a DateFormatter-t: ha nem ISO 8601 formátumban kell formázni egy dátumot (például „2024. július 21.” a UI számára), vagy ha iOS 9 és régebbi verziók támogatása szükséges. Minden szerverrel történő dátumcsere feladathoz használja az ISO8601DateFormatter-t — biztonságosabb, hatékonyabb és kevesebb kódot igényel. A DateFormatter ISO 8601 esetén a locale-hoz és regionális beállításokhoz kapcsolódó potenciális hibák forrása.

Migráció DateFormatter-ről ISO8601DateFormatter-re: cserélje ki a DateFormatter létrehozását + dateFormat + locale + timeZone beállítását az ISO8601DateFormatter létrehozására + formatOptions + timeZone beállítására. A string parse-olása változatlan marad a date(from:) segítségével. Visszafelé kompatibilitáshoz használható a #available(iOS 10, *) DateFormatter-re történő fallback-kel.

Gyakori hibák az ISO 8601 parse-olásakor

Elfelejtett formatOptions beállítás azt eredményezi, hogy a formatter az alapértelmezett értéket használja — .withInternetDateTime. Ha a szerver csak dátumot küld idő nélkül (2024-07-21), a parse-olás nil-t ad vissza. Mindig ellenőrizze, hogy a formatOptions lefedje az összes lehetséges formátumot, amely a szerverről érkezhet. Változó formátumú API-khoz használjon fallback kísérleteket különböző opciókombinációkkal.

A withMilliseconds és withFractionalSeconds összekeverése — gyakori hiba a másodperc törteket tartalmazó dátumok parse-olásakor. A withMilliseconds pontosan 3 tizedesjegyet vár. Ha a szerver 6 számjegyet küld (mikroszekundumok), a withMilliseconds-szel történő parse-olás hibával végződik. Használja a .withFractionalSeconds-t bármilyen karakterszámú kompatibilitáshoz. A .withFractionalSeconds iOS 13-ban jelent meg; régebbi verziókhoz használja a DateFormatter-t dateFormat-fal.

Az időzóna figyelmen kívül hagyása — egy másik gyakori probléma. Ha a szerver időzónával küldi a dátumot (+03:00), és a formatter UTC-re van állítva, a parse-olás nem fog meghiúsulni, de az eredmény UTC-ben lesz. A fejlesztők gyakran elvárják, hogy a Date megtartsa az időzónát, de a Date egy abszolút időpillanat, és nem tárol időzóna információt. A helyes megjelenítéshez mentse az időzónát külön, vagy használja az ISO8601DateFormatter-t a megfelelő timeZone-nal.

Az Apple Forum (2024) szerint az ISO8601DateFormatter-rel kapcsolatos kérdések körülbelül 20%-a arra a formátumra vonatkozik, ahol a másodpercek opcionálisak. Az ISO 8601 szabvány engedélyezi a másodperc nélküli formátumot: 2024-07-21T14:30+03:00. Az ISO8601DateFormatter a .withInternetDateTime opcióval nem támogatja ezt a formátumot — a parse-olásához DateFormatter szükséges a dateFormat = „yyyy-MM-dd’T’HH:mmZ” beállítással. Ezt a korlátozást figyelembe kell venni a rövidített időformátumot használó API-kkal végzett munka során.