ISO8601DateFormatter: əsas anlayışlar və ISO 8601 formatlaşdırma

ISO8601DateFormatter nədir?

ISO8601DateFormatter — Foundation-da Formatter-in ixtisaslaşdırılmış alt sinfi olub, Date və ISO 8601 formatlı sətir arasında ikitərəfli çevirmə həyata keçirir. ISO 8601 standartı (International Standard for the Representation of Dates and Times) tarix və vaxt mübadiləsi üçün beynəlxalq formatı müyən edir: 2024-07-21T14:30:00+00:00. DateFormatter-dən fərqli olaraq, bu sinif dateFormat təyin etməyi tələb etmir və verilmiş seçimlər əsasında sətrin strukturunu avtomatik müyən edir.

ISO8601DateFormatter-in DateFormatter qarşısında əsas üstünlükləri: locale-dən asılılığın olmaması (pars etmə istənilən cihazda eyni işləyir), saniyə kəsrlərinin daxili dəstəyi (vergüldən sonra istənilən sayda simvolla) və ötürülən seçimlər əsasında formatın avtomatik müyən edilməsi. Sinif həmçinin Z şəkilçisini (UTC təyini), +HH:mm formatında vaxt qurşaqlarını və azaldılmış dəqiqliyi (vaxtsız yalnız tarix) düzgün idarə edir.

ISO Specification (ISO 8601-1:2019)-a görə, standart dörd dəqiqlik səviyyəsini dəstəkləyir: il (2024), il-ay (2024-07), tam tarix (2024-07-21) və vaxt qurşağı ilə tarix-vaxt (2024-07-21T14:30:00+00:00). ISO8601DateFormatter format seçimlərinin kombinasiyası vasitəsilə bütün bu səviyyələri əhatə edir və proqramçını əl ilə dateFormat sətri yazmaqdan azad edir.

ISO8601DateFormatter Foundation-da necə işləyir?

İşləmə prinsipi ISO8601DateFormatter bit seçimlərinin (formatOptions) kombinasiyasına əsaslanır, onların hər biri çıxışda müəyyən tarix və ya vaxt komponentini aktivləşdirir. Məsələn, .withFullDate seçimi il, ay və günü aktivləşdirir; .withTime — saat, dəqiqə və saniyələri. Seçimləri birləşdirərək, proqramçı dateFormat sətri yazmadan lazımi dəqiqlik səviyyəsini əldə edir.

Daxili olaraq ISO8601DateFormatter pars etmə üçün ICU kitabxanasından istifadə edir, lakin sabit ISO 8601 qaydaları ilə. Bu o deməkdir ki, o, cihazda qurulmuş Locale və TimeZone tənzimləmələrini görməz—nəticə həmişə proqnozlaşdırıla biləndir. Vaxt qurşağını təyin etmək üçün timeZone xüsusiyyəti istifadə olunur, ilkin olaraq UTC-yə bərabərdir. timeZone nil olaraq təyin edilɐrsə, cihazın yerli vaxtı istifadə olunur.

Seçimlərin birləşdirilməsi: .withInternetDateTime .withFullDate, .withTime və .withTimeZone-un birləşməsinə bərabərdir. Milisaniyələrlə sətrləri pars etmək üçün .withFractionalSeconds əlavə edin. Yadda saxlamaq vacibdir ki, .withMilliseconds saniyə kəsrlərini üç simvolla məhdudlaşdırır, .withFractionalSeconds isə istənilən dəqiqliyi dəstəkləyir — vergüldən sonra birdən doqquz rəqəmə qədər.

ISO 8601 formatının tənzimləmələri

Format seçimləri ISO8601DateFormatter üç qrupa bölünür: tarix komponentləri (withFullDate, withYear, withMonth, withDay, withWeekOfYear), vaxt komponentləri (withTime, withHours, withMinutes, withSeconds) və əlavə tənzimləmələr (withMilliseconds, withFractionalSeconds, withTimeZone, withColonSeparatorInTimeZone, withDashSeparatorInDate, withFullTime). Onları birləşdirərək, ISO 8601-in demək olar ki, istənilən alt formatını əldə etmək olar.

Əsas seçim kombinasiyaları

• .withFullDate — yalnız tarix: 2024-07-21. YYYY-MM-DD formatlı sətrləri pars etmək üçün
• .withFullDate + .withTime — vaxt qurşağı olmadan tarix və vaxt: 2024-07-21T14:30:00
• .withInternetDateTime — tam format: 2024-07-21T14:30:00Z və ya 2024-07-21T14:30:00+03:00
• .withInternetDateTime + .withFractionalSeconds — saniyə kəsrləri ilə: 2024-07-21T14:30:00.123456+00:00
• .withFullDate + .withTime + .withTimeZone — tz-də iki nöqtəsiz tam format: 2024-07-21T14:30:00+0300

Vacib nüans: .withFractionalSeconds və .withMilliseconds bir-birini istisna edir — hər ikisi qurulubsa, .withFractionalSeconds tətbiq olunur. Server məlumatlarından milisaniyələri pars etmək üçün .withFractionalSeconds tövsiyə olunur, çünki bir çox server üç, altı və ya doqquz simvolla saniyə kəsrləri göndərir və .withFractionalSeconds istənilən uzunluğu idarə edir.

import Foundation

// ISO8601DateFormatter-ı konfiqurasiya et
let formatter = ISO8601DateFormatter()
formatter.timeZone = TimeZone(secondsFromGMT: 0)

// Müxtəlif format seçim kombinasiyaları
formatter.formatOptions = [.withFullDate]
let dateOnly = formatter.string(from: Date())
print("Tarix: \(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("Tam: \(full)")

// Milisaniyələrlə sətri pars et
let serverString = "2024-07-21T14:30:00.123456+03:00"
if let parsed = formatter.date(from: serverString) {
    print("Pars edildi: \(parsed)")
}

Swift-də ISO8601DateFormatter: kod nümunələri

Əsas istifadə ISO8601DateFormatter-in istifadəsi nümunə yaratmaq, timeZone (server məlumatları üçün UTC tövsiyə olunur) və formatOptions təyin etməkdən ibarətdir, bundan sonra formatlaşdırma üçün string(from:) və pars etmə üçün date(from:) çağırıla bilər. DateFormatter-dən fərqli olaraq, Locale barədə narahat olmaq lazım deyil — sinif regional tənzimləmələri görməz.

import Foundation

let formatter = ISO8601DateFormatter()

// Müxtəlif ISO 8601 formatlarını pars et
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("Pars edildi '\(str)': \(autoParsed)")
    } else {
        // Yalnız tarix sətrləri üçün withFullDate istifadə et
        formatter.formatOptions = [.withFullDate]
        if let fallback = formatter.date(from: str) {
            print("Fallback pars edildi '\(str)': \(fallback)")
        }
        formatter.formatOptions = [.withInternetDateTime]
    }
}

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

Dəyişən uzunluqlu kəsr saniyələrlə tarixlərin pars edilməsi — bir çox müasir API-lərin xüsusiyyəti. Server həm 2024-07-21T14:30:00.123Z (3 simvol), həm də 2024-07-21T14:30:00.123456Z (6 simvol) göndərə bilər. .withFractionalSeconds seçimi ilə ISO8601DateFormatter hər iki variantı düzgün idarə edəcək, DateFormatter isə dateFormat = “yyyy-MM-dd’T’HH:mm:ss.SSSZ” ilə yalnız üçrəqəmli milisaniyələri idarə edəcək.

import Foundation

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

// Müxtəlif kəsr saniyə dəqiqliyi
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)")
    }
}

// WithMilliseconds istifadə et (yalnız 3 rəqəm)
variantFormatter.formatOptions = [
    .withInternetDateTime,
    .withMilliseconds
]
let milliParsed = variantFormatter.string(from: Date())
print("Milisaniyələrlə: \(milliParsed)")

Bütün variantların pars edilməsinin sınaqdan keçirilməsi: yuxarıdakı kod göstərir ki, .withFractionalSeconds ilə ISO8601DateFormatter 1-dən 9-a qədər istənilən uzunluqdakı saniyə kəsrlərini uğurlu şəkildə emal edir. Bu, müxtəlif server platformaları ilə uyğunluq üçün vacibdir: .NET tez-tez 7 simvol (100 nanosaniyəlik tik), Python — 6, Java isə versiyadan asılı olaraq 3 və ya 9 simvol yaradır.

ISO 8601 üçün DateFormatter ilə müqayisə

DateFormatter də ISO 8601-i pars edə bilər, lakin dateFormat, locale və timeZone-un əl ilə təyin edilməsini tələb edir. Əsas problem DateFormatter-in Locale-dən asılı olmasıdır və en_US_POSIX qurulmazsa, qeyri-standart tarix formatları olan regionlardakı istifadəçilərdə pars etmə pozula bilər. ISO8601DateFormatter bu problemi memarlıq səviyyəsində həll edir: o, Locale istifadə etmir.

DateFormatter nə vaxt istifadə edilməli: tarixi ISO 8601 olmayan formatda formatlaşdırmaq lazımdırsa (məsələn, UI üçün „21 iyul 2024”) və ya iOS 9 və köhnə versiyaları dəstəklənməlidirsə. Serverlə tarix mübadiləsi ilə bağlı bütün tapşırıqlar üçün ISO8601DateFormatter istifadə edin — o, daha təhlükəsiz, daha məhsuldar və daha az kod tələb edir. ISO 8601 üçün DateFormatter locale və regional tənzimləmələrlə bağlı potensial səhvlər mənbəyidir.

DateFormatter-dən ISO8601DateFormatter-ə miqrasiya: DateFormatter yaratma + dateFormat + locale + timeZone qurma əvəzinə ISO8601DateFormatter yarat + formatOptions + timeZone qurun. Sətrin pars edilməsi date(from:) vasitəsilə dəyişməz qalır. Geriyə uyğunluq üçün DateFormatter-ə fallback ilə #available(iOS 10, *) istifadə edilə bilər.

ISO 8601 pars edərkən tipik səhvlər

Unudulmuş formatOptions qurulması formatter-in ilkin dəyər olan .withInternetDateTime istifadə etməsinə səbəb olur. Server vaxtsız yalnız tarix göndərɐrsə (2024-07-21), pars etmə nil qaytaracaq. Həmişə formatOptions-un serverdən gələ biləcək bütün mümkün formatları əhatə etdiyini yoxlayın. Dəyişən formatlı API-lər üçün müxtəlif seçim kombinasiyaları ilə fallback cəhdlərindən istifadə edin.

withMilliseconds və withFractionalSeconds arasında qarışıqlıq — saniyə kəsrləri ilə tarixləri pars edərkən tez-tez rast gəlinən səhv. withMilliseconds vergüldən sonra dəqiq 3 rəqəm gözləyir. Server 6 rəqəm göndərɐrsə (mikrosaniyələr), withMilliseconds ilə pars etmə səhvlə başa çatacaq. İstənilən sayda simvolla uyğunluq üçün .withFractionalSeconds istifadə edin. .withFractionalSeconds iOS 13-də ortaya çıxdı; köhnə versiyalar üçün dateFormat ilə DateFormatter istifadə edin.

Vaxt qurşağının görməməzlikdən gəlinməsi — digər geniş yayılmış problem. Server vaxt qurşağı ilə tarix göndərɐrsə (+03:00), formatter isə UTC-yə qurulubsa, pars etmə pozulmayacaq, lakin nəticə UTC-də olacaq. Tərtibatçılar tez-tez Date-in vaxt qurşağını saxlayacağını gözləyirlər, lakin Date mütləq zaman anıdır və vaxt qurşağı məlumatını saxlamır. Düzgün göstərmə üçün vaxt qurşağını ayrıca saxlayın və ya düzgün timeZone ilə ISO8601DateFormatter istifadə edin.

Apple Forum (2024)-a görə, ISO8601DateFormatter ilə bağlı sualların təxminən 20%-i saniyələrin isteğə bağlı olduğu formatla bağlıdır. ISO 8601 standartı saniyəsiz formatı icazə verir: 2024-07-21T14:30+03:00. .withInternetDateTime ilə ISO8601DateFormatter bu formatı dəstəkləmir — onu pars etmək üçün dateFormat = “yyyy-MM-dd’T’HH:mmZ” ilə DateFormatter tələb olunacaq. Bu məhdudiyyət qısaltılmış vaxt formatından istifadə edən API-lərlə işləyərkən nəzərə alınmalıdır.