ISO8601DateFormatter: temel kavramlar ve ISO 8601 biçimlendirme

ISO8601DateFormatter nedir?

ISO8601DateFormatter, Foundation'da Formatter'ın özelleştirilmiş bir alt sınıfıdır ve Date ile ISO 8601 biçimli dizeler arasında çift yönlü dönüşüm uygular. ISO 8601 standardı (International Standard for the Representation of Dates and Times), tarih ve saat alışverişi için uluslararası bir biçim tanımlar: 2024-07-21T14:30:00+00:00. DateFormatter'ın aksine, bu sınıf dateFormat belirtilmesini gerektirmez ve verilen seçeneklere göre dize yapısını otomatik olarak belirler.

ISO8601DateFormatter'ın DateFormatter'a göre ana avantajları: yerel ayara bağımlılık yok (ayrıştırma herhangi bir cihazda aynı şekilde çalışır), saniye kesirleri için yerleşik destek (herhangi bir sayıda ondalık basamakla) ve iletilen seçeneklere dayalı otomatik biçim algılama. Sınıf ayrıca Z sonekini (UTC tanımı), +HH:mm biçimindeki zaman dilimlerini ve azaltılmış hassasiyeti (saatsiz sadece tarih) doğru şekilde işler.

ISO Spesifikasyonuna (ISO 8601-1:2019) göre, standart dört hassasiyet seviyesini destekler: yıl (2024), yıl-ay (2024-07), tam tarih (2024-07-21) ve zaman dilimli tarih-saat (2024-07-21T14:30:00+00:00). ISO8601DateFormatter, biçim seçeneklerinin bir kombinasyonu aracılığıyla tüm bu seviyeleri kapsar ve geliştiriciyi manuel olarak dateFormat dizeleri oluşturmaktan kurtarır.

Foundation'da ISO8601DateFormatter nasıl çalışır?

Çalışma prensibi ISO8601DateFormatter, her biri çıktıya belirli bir tarih veya saat bileşeni ekleyen bit seçeneklerinin (formatOptions) bir kombinasyonuna dayanır. Örneğin, .withFullDate seçeneği yıl, ay ve günü içerir; .withTime saat, dakika ve saniyeyi içerir. Seçenekleri birleştirerek, geliştirici bir dateFormat dizesi yazmadan istenen hassasiyet seviyesini elde eder.

Dahili olarak, ISO8601DateFormatter ayrıştırma için ICU kütüphanesini kullanır, ancak sabit ISO 8601 kurallarıyla. Bu, cihazdaki Locale ve TimeZone ayarlarını yok saydığı anlamına gelir — sonuç her zaman tahmin edilebilirdir. Zaman dilimini ayarlamak için varsayılanı UTC olan timeZone özelliği kullanılır. timeZone nil olarak ayarlanırsa, cihazın yerel saati kullanılır.

Seçeneklerin birleştirilmesi: .withInternetDateTime, .withFullDate, .withTime ve .withTimeZone'un birleştirilmesine eşdeğerdir. Milisaniyeli dizeleri ayrıştırmak için .withFractionalSeconds ekleyin. .withMilliseconds'in saniye kesirlerini üç basamakla sınırladığını, .withFractionalSeconds'ın ise ondalık noktadan sonra birden dokuza kadar herhangi bir hassasiyeti desteklediğini unutmamak önemlidir.

ISO 8601 Biçim Seçenekleri

Biçim seçenekleri ISO8601DateFormatter'ın seçenekleri üç gruba ayrılır: tarih bileşenleri (withFullDate, withYear, withMonth, withDay, withWeekOfYear), saat bileşenleri (withTime, withHours, withMinutes, withSeconds) ve ek ayarlar (withMilliseconds, withFractionalSeconds, withTimeZone, withColonSeparatorInTimeZone, withDashSeparatorInDate, withFullTime). Bunları birleştirerek neredeyse herhangi bir ISO 8601 alt biçimini elde edebilirsiniz.

Ana Seçenek Kombinasyonları

• .withFullDate — sadece tarih: 2024-07-21. YYYY-MM-DD dizelerini ayrıştırmak için
• .withFullDate + .withTime — zaman dilimi olmayan tarih ve saat: 2024-07-21T14:30:00
• .withInternetDateTime — tam biçim: 2024-07-21T14:30:00Z veya 2024-07-21T14:30:00+03:00
• .withInternetDateTime + .withFractionalSeconds — saniye kesirleriyle: 2024-07-21T14:30:00.123456+00:00
• .withFullDate + .withTime + .withTimeZone — tz'de iki nokta olmadan tam biçim: 2024-07-21T14:30:00+0300

Önemli nüans: .withFractionalSeconds ve .withMilliseconds birbirini dışlar — her ikisi de ayarlanırsa, .withFractionalSeconds uygulanır. Sunucu verilerinden milisaniyeleri ayrıştırmak için .withFractionalSeconds önerilir, çünkü birçok sunucu üç, altı veya dokuz basamaklı saniye kesirleri gönderir ve .withFractionalSeconds herhangi bir uzunluğu işler.

import Foundation

// Configure ISO8601DateFormatter
let formatter = ISO8601DateFormatter()
formatter.timeZone = TimeZone(secondsFromGMT: 0)

// Different format option combinations
formatter.formatOptions = [.withFullDate]
let dateOnly = formatter.string(from: Date())
print("Date: \(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("Full: \(full)")

// Parse string with milliseconds
let serverString = "2024-07-21T14:30:00.123456+03:00"
if let parsed = formatter.date(from: serverString) {
    print("Parsed: \(parsed)")
}

Swift'te ISO8601DateFormatter: kod örnekleri

Temel kullanım ISO8601DateFormatter'ın kullanımı, bir örnek oluşturma, timeZone (sunucu verileri için UTC önerilir) ve formatOptions ayarlama ile başlar, ardından biçimlendirme için string(from:) ve ayrıştırma için date(from:) çağrılabilir. DateFormatter'ın aksine, Locale hakkında endişelenmeye gerek yoktur — sınıf bölgesel ayarları yok sayar.

import Foundation

let formatter = ISO8601DateFormatter()

// Parse different ISO 8601 formats
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("Parsed '\(str)': \(autoParsed)")
    } else {
        // Use withFullDate for date-only strings
        formatter.formatOptions = [.withFullDate]
        if let fallback = formatter.date(from: str) {
            print("Fallback parsed '\(str)': \(fallback)")
        }
        formatter.formatOptions = [.withInternetDateTime]
    }
}

// Serialize to RFC 3339 (GitHub API)
formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
let rfc3339 = formatter.string(from: Date())
print("RFC 3339: \(rfc3339)")

Değişken uzunlukta saniye kesirleri olan tarihleri ayrıştırma — birçok modern API'nin özelliğidir. Bir sunucu 2024-07-21T14:30:00.123Z (3 basamak) veya 2024-07-21T14:30:00.123456Z (6 basamak) gönderebilir. .withFractionalSeconds seçeneği ile ISO8601DateFormatter her iki değişkeni de doğru şekilde işlerken, dateFormat = "yyyy-MM-dd'T'HH:mm:ss.SSSZ" ile DateFormatter yalnızca üç basamaklı milisaniyeleri işler.

import Foundation

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

// Different fractional second precision
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)")
    }
}

// Use withMilliseconds (3 digits only)
variantFormatter.formatOptions = [
    .withInternetDateTime,
    .withMilliseconds
]
let milliParsed = variantFormatter.string(from: Date())
print("With milliseconds: \(milliParsed)")

Tüm değişkenlerin ayrıştırma testi: gösterilen kod, .withFractionalSeconds ile ISO8601DateFormatter'ın 1 ila 9 basamak arasında herhangi bir uzunluktaki saniye kesirlerini başarıyla işlediğini gösterir. Bu, farklı sunucu platformlarıyla uyumluluk için önemlidir: .NET genellikle 7 basamak (100 nanosaniye tick) üretir, Python — 6, Java — sürüme bağlı olarak 3 veya 9.

ISO 8601 için DateFormatter ile Karşılaştırma

DateFormatter da ISO 8601'i ayrıştırabilir, ancak dateFormat, locale ve timeZone'un manuel olarak yapılandırılmasını gerektirir. Ana sorun, DateFormatter'ın Locale'ye bağlı olması ve en_US_POSIX ayarlanmazsa, standart olmayan tarih biçimlerine sahip bölgelerdeki kullanıcılar için ayrıştırmanın başarısız olabilmesidir. ISO8601DateFormatter bu sorunu mimari düzeyde çözer: Locale kullanmaz.

DateFormatter ne zaman kullanılır: bir tarihi ISO 8601 olmayan bir biçimde biçimlendirmeniz gerekiyorsa (örneğin, kullanıcı arayüzü için "21 Temmuz 2024") veya iOS 9 ve öncesini desteklemeniz gerekiyorsa. Tüm sunucu-istemci tarih alışverişi görevleri için ISO8601DateFormatter kullanın — daha güvenli, daha verimli ve daha az kod gerektirir. ISO 8601 için DateFormatter, yerel ayar ve bölgesel ayarlarla ilgili potansiyel hataların kaynağıdır.

DateFormatter'dan ISO8601DateFormatter'a geçiş: DateFormatter + dateFormat + locale + timeZone oluşturmayı, ISO8601DateFormatter + formatOptions + timeZone ile değiştirin. date(from:) aracılığıyla dize ayrıştırma değişmeden kalır. Geriye dönük uyumluluk için, DateFormatter'a geri dönüşle birlikte #available(iOS 10, *) kullanabilirsiniz.

ISO 8601 Ayrıştırırken Yaygın Hatalar

Unutulan formatOptions yapılandırması biçimlendiricinin varsayılan değeri — .withInternetDateTime — kullanmasına neden olur. Sunucu saatsiz bir tarih gönderirse (2024-07-21), ayrıştırma nil döndürür. formatOptions'ın sunucudan gelebilecek tüm olası biçimleri kapsadığını her zaman kontrol edin. Değişken biçimlere sahip API'ler için farklı seçenek kombinasyonlarıyla geri dönüş denemeleri kullanın.

withMilliseconds ve withFractionalSeconds arasındaki karışıklık — saniye kesirleri olan tarihleri ayrıştırırken yaygın bir hatadır. withMilliseconds, ondalık noktadan sonra tam olarak 3 basamak bekler. Sunucu 6 basamak (mikrosaniye) gönderirse, withMilliseconds ile ayrıştırma başarısız olur. Herhangi bir sayıda basamakla uyumluluk için .withFractionalSeconds kullanın. .withFractionalSeconds iOS 13'te kullanıma sunulmuştur; daha eski sürümler için dateFormat ile DateFormatter kullanın.

Zaman dilimini yok saymak — başka bir yaygın sorundur. Sunucu zaman dilimiyle (+03:00) bir tarih gönderir ve biçimlendirici UTC'ye ayarlanmışsa, ayrıştırma başarısız olmaz, ancak sonuç UTC olur. Geliştiriciler genellikle Date'in zaman dilimini korumasını bekler, ancak Date mutlak bir zaman noktasıdır — zaman dilimi bilgisini saklamaz. Doğru görüntüleme için zaman dilimini ayrı olarak kaydedin veya doğru timeZone ile ISO8601DateFormatter kullanın.

Apple Forumuna (2024) göre, ISO8601DateFormatter ile ilgili soruların yaklaşık %20'si saniyelerin isteğe bağlı olduğu biçimle ilgilidir. ISO 8601 standardı saniyesiz bir biçime izin verir: 2024-07-21T14:30+03:00. .withInternetDateTime ile ISO8601DateFormatter bu biçimi desteklemez — ayrıştırmak için dateFormat = "yyyy-MM-dd'T'HH:mmZ" ile DateFormatter gerekir. Kısaltılmış saat biçimini kullanan API'lerle çalışırken bu sınırlamayı dikkate almak önemlidir.