ISO8601DateFormatter: 主要概念とISO 8601 フォーマット

ISO8601DateFormatterとは？

ISO8601DateFormatterは、FoundationのFormatterの特殊なサブクラスで、DateとISO 8601形式の文字列間の双方向変換を実装します。ISO 8601規格（International Standard for the Representation of Dates and Times）は、日付と時刻を交換するための国際形式を定義しています：2024-07-21T14:30:00+00:00。DateFormatterとは異なり、このクラスはdateFormatを指定する必要がなく、指定されたオプションに基づいて文字列構造を自動的に決定します。

DateFormatterに対するISO8601DateFormatterの主な利点：ロケールへの依存がない（解析はどのデバイスでも同じように機能）、秒の小数部の組み込みサポート（任意の小数点以下の桁数）、渡されたオプションに基づく自動フォーマット検出。このクラスはZサフィックス（UTC指定）、+HH:mm形式のタイムゾーン、および精度の低い形式（時刻なしの日付のみ）も正しく処理します。

ISO仕様（ISO 8601-1:2019）によると、この規格は4つの精度レベルをサポートしています：年（2024）、年月（2024-07）、完全な日付（2024-07-21）、およびタイムゾーン付きの日時（2024-07-21T14:30:00+00:00）。ISO8601DateFormatterは、フォーマットオプションの組み合わせを通じてこれらのすべてのレベルをカバーし、開発者が手動でdateFormat文字列を構築する手間を省きます。

FoundationでのISO8601DateFormatterの仕組み

動作原理 ISO8601DateFormatterは、ビット単位のオプション（formatOptions）の組み合わせに基づいており、各オプションは出力に特定の日付または時刻コンポーネントを含めます。たとえば、.withFullDateオプションには年、月、日が含まれます。.withTimeには時、分、秒が含まれます。オプションを組み合わせることで、開発者はdateFormat文字列を記述せずに目的の精度レベルを取得できます。

内部的には、ISO8601DateFormatterは解析にICUライブラリを使用しますが、固定のISO 8601ルールに従います。つまり、デバイスのLocaleおよびTimeZone設定を無視し、結果は常に予測可能です。タイムゾーンの設定にはtimeZoneプロパティを使用し、デフォルトはUTCです。timeZoneがnilに設定されている場合、デバイスのローカル時間が使用されます。

オプションの組み合わせ： .withInternetDateTimeは、.withFullDate、.withTime、.withTimeZoneを組み合わせたものと同等です。ミリ秒を含む文字列を解析するには、.withFractionalSecondsを追加します。.withMillisecondsは秒の小数部を3桁に制限しますが、.withFractionalSecondsは任意の精度（小数点以下1〜9桁）をサポートすることに注意してください。

ISO 8601フォーマットオプション

フォーマットオプション ISO8601DateFormatterのオプションは3つのグループに分けられます：日付コンポーネント（withFullDate、withYear、withMonth、withDay、withWeekOfYear）、時刻コンポーネント（withTime、withHours、withMinutes、withSeconds）、および追加設定（withMilliseconds、withFractionalSeconds、withTimeZone、withColonSeparatorInTimeZone、withDashSeparatorInDate、withFullTime）。これらを組み合わせることで、ほぼすべてのISO 8601サブフォーマットを実現できます。

主なオプションの組み合わせ

• .withFullDate — 日付のみ：2024-07-21。YYYY-MM-DD形式の文字列解析用
• .withFullDate + .withTime — タイムゾーンなしの日付と時刻：2024-07-21T14:30:00
• .withInternetDateTime — 完全形式：2024-07-21T14:30:00Zまたは2024-07-21T14:30:00+03:00
• .withInternetDateTime + .withFractionalSeconds — 秒の小数部付き：2024-07-21T14:30:00.123456+00:00
• .withFullDate + .withTime + .withTimeZone — tzにコロンなしの完全形式：2024-07-21T14:30:00+0300

重要な注意点： .withFractionalSecondsと.withMillisecondsは相互排他的です。両方が設定されている場合、.withFractionalSecondsが適用されます。サーバーデータからのミリ秒解析には、.withFractionalSecondsが推奨されます。多くのサーバーは3桁、6桁、または9桁の秒の小数部を送信するため、.withFractionalSecondsは任意の長さを処理できます。

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でのISO8601DateFormatter: コード例

基本的な使用法 ISO8601DateFormatterの使用は、インスタンスの作成、timeZone（サーバーデータにはUTC推奨）とformatOptionsの設定に始まり、その後、フォーマットにはstring(from:)、解析にはdate(from:)を呼び出します。DateFormatterとは異なり、Localeを気にする必要はありません。このクラスは地域設定を無視します。

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)")

可変長の秒の小数部を含む日付の解析 — 多くの最新APIの特徴です。サーバーは2024-07-21T14:30:00.123Z（3桁）または2024-07-21T14:30:00.123456Z（6桁）のいずれかを送信できます。.withFractionalSecondsオプションを指定したISO8601DateFormatterは両方のバリアントを正しく処理しますが、dateFormat = "yyyy-MM-dd'T'HH:mm:ss.SSSZ"を使用したDateFormatterは3桁のミリ秒のみを処理します。

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)")

すべてのバリアントの解析テスト： 示されているコードは、.withFractionalSecondsを指定したISO8601DateFormatterが1〜9桁の任意の長さの秒の小数部を正常に処理することを示しています。これは、さまざまなサーバープラットフォームとの互換性にとって重要です。.NETは多くの場合7桁（100ナノ秒ティック）、Pythonは6桁、Javaはバージョンに応じて3桁または9桁を生成します。

ISO 8601のためのDateFormatterとの比較

DateFormatterもISO 8601を解析できますが、dateFormat、locale、timeZoneの手動設定が必要です。主な問題は、DateFormatterがLocaleに依存しており、en_US_POSIXを設定しないと、標準以外の日付形式を使用する地域のユーザーで解析が失敗する可能性があることです。ISO8601DateFormatterはアーキテクチャレベルでこの問題を解決します：Localeを使用しません。

DateFormatterを使用する場合： 日付をISO 8601以外の形式（UI用の「2024年7月21日」など）でフォーマットする必要がある場合、またはiOS 9以前をサポートする必要がある場合。サーバーとクライアント間の日付交換タスクには、ISO8601DateFormatterを使用してください。より安全で、効率的で、コードも少なくて済みます。ISO 8601のためのDateFormatterは、ロケールや地域設定に関連する潜在的なバグの原因です。

DateFormatterからISO8601DateFormatterへの移行： DateFormatter + dateFormat + locale + timeZoneの作成を、ISO8601DateFormatter + formatOptions + timeZoneに置き換えます。date(from:)による文字列解析は変更されません。後方互換性のために、#available(iOS 10, *)をDateFormatterへのフォールバックとともに使用できます。

ISO 8601解析時の一般的な落とし穴

formatOptionsの設定忘れ により、フォーマッターはデフォルト値の.withInternetDateTimeを使用します。サーバーが時刻なしの日付（2024-07-21）を送信すると、解析はnilを返します。formatOptionsがサーバーから送信される可能性のあるすべての形式をカバーしていることを常に確認してください。可変形式のAPIの場合は、異なるオプションの組み合わせでフォールバックを試行してください。

withMillisecondsとwithFractionalSecondsの混同 は、秒の小数部を含む日付を解析する際の一般的な誤りです。withMillisecondsは小数点以下を正確に3桁想定しています。サーバーが6桁（マイクロ秒）を送信すると、withMillisecondsでの解析は失敗します。任意の桁数に対応するには、.withFractionalSecondsを使用してください。.withFractionalSecondsはiOS 13で利用可能になりました。古いバージョンでは、dateFormatを使用したDateFormatterを使用してください。

タイムゾーンの無視 も一般的な問題です。サーバーがタイムゾーン（+03:00）付きの日付を送信し、フォーマッターがUTCに設定されている場合、解析は失敗しませんが、結果はUTCになります。開発者はDateがタイムゾーンを保持することを期待することがよくありますが、Dateは絶対的な時点であり、タイムゾーン情報を保存しません。正しく表示するには、タイムゾーンを別途保存するか、適切なtimeZoneを指定したISO8601DateFormatterを使用してください。

Appleフォーラム（2024）によると、ISO8601DateFormatterに関する質問の約20％は、秒がオプションの形式に関するものです。ISO 8601規格では秒なしの形式が許可されています：2024-07-21T14:30+03:00。.withInternetDateTimeを使用したISO8601DateFormatterはこの形式をサポートしていません。解析するには、dateFormat = "yyyy-MM-dd'T'HH:mmZ"を使用したDateFormatterが必要です。短縮された時刻形式を使用するAPIを扱う際には、この制限を考慮することが重要です。