モジュール java.base
パッケージ java.time.format

クラスDateTimeFormatter

java.lang.Object
java.time.format.DateTimeFormatter
public final class DateTimeFormatter extends Object
日付/時間オブジェクトの出力および解析のためのフォーマッタ。

このクラスは、出力と解析を行うためのアプリケーションのメイン・エントリ・ポイントとなり、DateTimeFormatterの共通の実装を提供します。

  • 事前定義された定数を使用。ISO_LOCAL_DATEなど
  • パターン文字を使用。uuuu-MMM-ddなど
  • ローカライズされたスタイルを使用。longやmediumなど

より複雑なフォーマッタはDateTimeFormatterBuilderによって提供されます。

主要な日付/時間クラスには2つのメソッドが用意されています。1つは書式設定用のformat(DateTimeFormatter formatter)、もう1つは解析用のparse(CharSequence text, DateTimeFormatter formatter)です。

たとえば、 

  LocalDate date = LocalDate.now();
  String text = date.format(formatter);
  LocalDate parsedDate = LocalDate.parse(text, formatter);

このフォーマットに加え、必要なLocale、Chronology、ZoneId、およびDecimalStyleを持つフォーマッタを作成できます。

withLocaleメソッドは、ロケールをオーバーライドする新しいフォーマッタを返します。 ロケールは、書式設定と解析のいくつかの側面に影響します。 たとえば、ofLocalizedDateはロケール固有の日付フォーマットを使用するフォーマッタを提供します。

withChronologyメソッドは、暦をオーバーライドする新しいフォーマッタを返します。 オーバーライドされた場合、日付/時間の値は書式設定の前にその暦に変換されます。 解析時には、日付/時間の値はその暦に変換されてから返されます。

withZoneメソッドは、ゾーンをオーバーライドする新しいフォーマッタを返します。 オーバーライドされた場合、日付/時間の値は、要求されたZoneIdを持つZonedDateTimeに変換されてから書式設定されます。 解析時には、ZoneIdが適用された後で値が返されます。

withDecimalStyleメソッドは、DecimalStyleをオーバーライドする新しいフォーマッタを返します。 DecimalStyleの記号は、書式設定と解析に使用されます。

一部のアプリケーションでは、古いjava.text.Formatクラスを書式設定に使用しなければならない場合があります。 toFormat()メソッドは、java.text.Formatの実装を返します。

事前定義されたフォーマッタ

事前定義されたフォーマッタ
Formatter 説明 例
ofLocalizedDate(dateStyle) ロケールの日付スタイルを持つフォーマッタ '2011-12-03'
ofLocalizedTime(timeStyle) ロケールの時間スタイルを持つフォーマッタ '10:15:30'
ofLocalizedDateTime(dateTimeStyle) ロケールの日付と時間のスタイルを持つフォーマッタ '3 Jun 2008 11:05:30'
ofLocalizedDateTime(dateStyle,timeStyle) ロケールの日付スタイルおよび時間スタイルを持つフォーマッタ '3 Jun 2008 11:05'
BASIC_ISO_DATE 基本的なISO日付 '20111203'
ISO_LOCAL_DATE ISOローカル日付 '2011-12-03'
ISO_OFFSET_DATE オフセット付きのISO日付 '2011-12-03+01:00'
ISO_DATE オフセット付きまたはオフセットなしのISO日付 '2011-12-03+01:00'; '2011-12-03'
ISO_LOCAL_TIME オフセットなしの時間 '10:15:30'
ISO_OFFSET_TIME オフセット付きの時間 '10:15:30+01:00'
ISO_TIME オフセット付きまたはオフセットなしの時間 '10:15:30+01:00'; '10:15:30'
ISO_LOCAL_DATE_TIME ISOローカル日付および時間 '2011-12-03T10:15:30'
ISO_OFFSET_DATE_TIME オフセット付きの日付時間 '2011-12-03T10:15:30+01:00'
ISO_ZONED_DATE_TIME ゾーン指定の日付時間 '2011-12-03T10:15:30+01:00[Europe/Paris]'
ISO_DATE_TIME ゾーンID付きの日付および時間 '2011-12-03T10:15:30+01:00[Europe/Paris]'
ISO_ORDINAL_DATE 年および年の日付 '2012-337'
ISO_WEEK_DATE 年および週 '2012-W48-6'
ISO_INSTANT インスタントの日付および時間 '2011-12-03T10:15:30Z'
RFC_1123_DATE_TIME RFC 1123 / RFC 822 'Tue, 3 Jun 2008 11:05:30 GMT'

書式設定および解析用のパターン

パターンは、文字と記号の単純なシーケンスに基づいています。 パターンは、ofPattern(String)メソッドおよびofPattern(String, Locale)メソッドを使用してFormatterを作成する場合に使用されます。 たとえば、"d MMM uuuu"を使用すると、2011-12-03は「3 Dec 2011」と書式設定されます。 パターンから作成されたフォーマッタは、必要に応じて何度でも使用でき、不変でスレッドセーフです。

たとえば、 

  LocalDate date = LocalDate.now();
  DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");
  String text = date.format(formatter);
  LocalDate parsedDate = LocalDate.parse(text, formatter);

'A'から'Z'および'a'から'z'のすべての文字は、パターン文字として予約されています。 次のパターン文字が定義されています。

模様の文字と記号
記号 意味 表示 例
G 紀元 text 広告; 西暦; A
u year year 2004; 04
y 紀元年 year 2004; 04
D day-of-year number 189
M/L month-of-year number/text 7; 07; 7月。7月。J
d day-of-month number 10
g modified-julian-day number 2451334
Q/q quarter-of-year number/text 3; 03; Q3; 第3四半期
Y week-based-year year 1996; 96
w week-of-week-based-year number 27
W week-of-month number 4
E day-of-week text 火。火曜日; T
e/c ローカライズされた曜日 number/text 2; 02; 火。火曜日; T
F aligned-week-of-month number 3
a am-pm-of-day text PM
B period-of-day text 午前中
h clock-hour-of-am-pm (1-12) number 12
K hour-of-am-pm (0-11) number 0
k clock-hour-of-day (1-24) number 24
H hour-of-day (0-23) number 0
m minute-of-hour number 30
s second-of-minute number 55
S fraction-of-second fraction 978
A milli-of-day number 1234
n nano-of-second number 987654321
N nano-of-day number 1234000000
V タイムゾーンID zone-id America/Los_Angeles; Z; -08:30
v 一般的なタイムゾーン名 zone-name 太平洋時間; PT
z タイムゾーン名 zone-name 太平洋標準時PST
O ローカライズされたゾーン・オフセット offset-O GMT+8; GMT+08:00; UTC-08:00
X ゼロのゾーン・オフセット'Z' offset-X Z; -08; -0830; -08:30; -083015; -08:30:15
x zone-offset offset-x +0000; -08; -0830; -08:30; -083015; -08:30:15
Z zone-offset offset-Z +0000; -0800; -08:00
p 次のパッド パッド修飾子 1
' テキストのエスケープ delimiter
'' 一重引用符 リテラル '
[ オプションのセクション開始
] オプションのセクション終了
# 将来使用するための予約
{ 将来使用するための予約
} 将来使用するための予約

パターン文字の数によってフォーマットが決まります。

テキスト: テキスト・スタイルは、使用されるパターン文字の数に基づいて決まります。 パターン文字が4つ未満の場合は、短縮形式が使用されます。 パターン文字がちょうど4つの場合は、フル形式が使用されます。 パターン文字がちょうど5つの場合は、縮小形式が使用されます。 パターン文字'L'、'c'、および'q'は、スタンドアロン形式のテキスト・スタイルを指定します。

数値: 文字数が1の場合は、パディングを使用せず最小の桁数で値が出力されます。 それ以外の場合は、文字数が出力フィールドの幅として使用され、値は必要に応じてゼロでパディングされます。 次のパターン文字には、文字数に制約があります。 文字'c'および'F'は、1つだけ指定できます。 文字'd'、'H'、'h'、'K'、'k'、'm'、および's'は、2つまで指定できます。 文字'D'は、3つまで指定できます。

数値/テキスト: パターン文字の数が3以上の場合は、上記の「テキスト」のルールが使用されます。 それ以外の場合は、上記の「数値」のルールが使用されます。

小数: 秒の小数部としてナノ秒フィールドを出力します。 ナノ秒の値は9桁なので、パターン文字の数は1から9までです。 9未満の場合、ナノ秒の値は切り捨てられ、上位の桁だけが出力されます。

年: パターン文字の数によって最小のフィールド幅が決まり、その幅に満たない場合はパディングが使用されます。 文字数が2の場合は、2桁の縮小形式が使用されます。 出力の場合は、右2桁が出力されます。 解析の場合は、ベース値として2000が使用されるため、年の範囲は2000から2099までになります。 文字数が4未満(ただし2以外)の場合は、SignStyle.NORMALのように、負の年に対してのみ符号が出力されます。 それ以外の場合は、SignStyle.EXCEEDS_PADのように、パディング幅を超える場合に符号が出力されます。

ゾーンID: 「Europe/Paris」などのタイムゾーンIDを出力します。 文字数が2の場合は、タイムゾーンIDが出力されます。 それ以外の文字数では、IllegalArgumentExceptionがスローされます。

ゾーン名: タイムゾーンIDの表示名を出力します。 パターン文字が'z'の場合、出力は夏時間対応ゾーン名です。 DSTが適用されるかどうかを判断するのに十分な情報がない場合、夏時間を無視する名前が使用されます。 文字数が1、2、または3の場合は、短い名前が出力されます。 文字数が4の場合は、完全な名前が出力されます。 5文字以上の場合は、IllegalArgumentExceptionがスローされます。

パターン文字が'v'の場合、出力は夏時間を無視するゾーン名を提供します。 文字数が1の場合、短縮名が出力されます。 文字数が4の場合は、完全な名前が出力されます。 2文字、3文字、5文字以上の文字がIllegalArgumentExceptionをスローします。

オフセットXおよびx: パターン文字の数に基づいてオフセットを書式設定します。 1文字の場合、分がゼロのときは時だけが出力されて「+01」のようになり、分がゼロでないときは分も出力されて「+0130」のようになります。 2文字の場合は、時と分がコロンなしで出力され、「+0130」のようになります。 3文字の場合は、時と分がコロン付きで出力され、「+01:30」のようになります。 4文字の場合は、時と分、およびオプションの秒がコロンなしで出力され、「+013015」のようになります。 5文字の場合は、時と分、およびオプションの秒がコロン付きで出力され、「+01:30:15」のようになります。 6文字以上の場合は、IllegalArgumentExceptionがスローされます。 出力されるオフセットがゼロになるときは、パターン文字'X' (大文字)の場合は「Z」が出力され、パターン文字'x' (小文字)の場合は「+00」、「+0000」、または「+00:00」が出力されます。

オフセットO: ゼロ以外のオフセットでは、パターン文字の数に基づいてローカライズされたオフセットがフォーマットされます。 1文字の場合は、ローカライズされたオフセットの短縮形式が出力されます。これはローカライズされたオフセットのテキスト(「GMT」など)、時(先頭のゼロを含まない)、オプションの2桁の分と秒(ゼロでない場合)、およびコロンからなり、たとえば「GMT+8」となります。 4文字の場合は、フル形式が出力されます。これはローカライズされたオフセットのテキスト(「GMT」など)、2桁の時と分のフィールド、オプションの秒フィールド(ゼロでない場合)、およびコロンからなり、たとえば「GMT+08:00」となります。 オフセットが0の場合、ローカライズされたテキストのみが出力されます。 それ以外の文字数では、IllegalArgumentExceptionがスローされます。

オフセットZ: パターン文字の数に基づいてオフセットを書式設定します。 1、2、または3文字の場合は、時と分がコロンなしで出力され、「+0130」のようになります。 オフセットがゼロの場合、出力は「+0000」になります。 4文字の場合は、ローカライズされたオフセットのフル形式が出力されます。これはオフセットOの4文字と等価です。 オフセットがゼロのときは、対応するローカライズされたオフセットのテキストが出力されます。 5文字の場合は、時と分、およびオプションの秒(ゼロでない場合)がコロン付きで出力されます。 オフセットがゼロの場合は「Z」が出力されます。 6文字以上の場合は、IllegalArgumentExceptionがスローされます。

オプションのセクション: オプションのセクションのマーカーは、DateTimeFormatterBuilder.optionalStart()およびDateTimeFormatterBuilder.optionalEnd()の呼出しとまったく同様に機能します。

パディング修飾子: 直後のパターンがスペースでパディングされるように変更します。 パディング幅は、パターン文字の数によって決まります。 これは、DateTimeFormatterBuilder.padNext(int)を呼び出すのと同じです。

たとえば「ppH」を使用すると、時は、幅が2になるまで左にスペースが追加されて出力されます。

認識されない文字はエラーです。 英文字でない文字は、'['、']'、'{'、'}'、'#'、および一重引用符を除き、直接出力されます。 ただし、将来の変更によってアプリケーションが破壊されないようにするには、直接出力したいすべての文字を一重引用符で囲むことをお薦めします。

解決

解析は2段階の処理として実装されています。 まず、フォーマッタで定義されたレイアウトを使用してテキストが解析され、フィールドから値へのMap、ZoneId、およびChronologyが生成されます。 次に、さまざまなフィールドの検証、結合、簡素化を行ってより有用なフィールドを得ることにより、解析されたデータが解決されます。

このクラスには5つの解析メソッドが用意されています。 これらのうち4つは、解析フェーズと解決フェーズの両方を実行します。 5番目のメソッドparseUnresolved(CharSequence, ParsePosition)は最初のフェーズだけを実行し、その結果は未解決のままになります。 したがって、これは本質的に低レベルの処理です。

解決フェーズは、このクラスに設定される2つのパラメータによって制御されます。

ResolverStyleは、厳密、スマート、および非厳密という異なる3つの方法を提供する列挙です。 スマート・オプションがデフォルトです。 withResolverStyle(ResolverStyle)を使用して設定できます。

withResolverFields(TemporalField...)パラメータを使用すると、解決するフィールドのセットをフィルタリングしてから解決を開始できます。 たとえば、フォーマッタが年、月、「月の日」、および「年の日」を解析した場合、日付を解決する方法には、(年+月+「月の日」)と(年+「年の日」)の2つがあります。 リゾルバ・フィールドを使用して、2つの方法のいずれかを選択できます。 リゾルバ・フィールドが設定されていない場合、両方の方法の結果は同じ日付になるはずです。

個別のフィールドを解決して完全な日付と時間を構築することは、多数のクラスに動作が分散された複雑な処理です。 次のステップに従って行われます。

  1. 暦が判定されます。 結果の暦は、解析された暦になります。あるいは、暦の解決が行われなかった場合は、このクラスに設定された暦になり、それがnullのときはIsoChronologyになります。
  2. ChronoField日付フィールドが解決されます。 これはChronology.resolveDate(Map, ResolverStyle)を使用して実現されます。 フィールド解決に関するドキュメントは、Chronologyの実装内にあります。
  3. ChronoField時間フィールドが解決されます。 このドキュメントはChronoField上にあり、すべての時刻系に対して同じになります。
  4. ChronoFieldではない任意のフィールドが処理されます。 これはTemporalField.resolve(Map, TemporalAccessor, ResolverStyle)を使用して実現されます。 フィールド解決に関するドキュメントは、TemporalFieldの実装内にあります。
  5. ChronoField日付フィールドおよび時間フィールドが再度解決されます。 これにより、ステップ4のフィールドからChronoField値を生成し、それらを処理して日付と時間にすることができます。
  6. 少なくとも時が使用可能な場合は、LocalTimeが構築されます。 このとき、分、秒、および秒の小数部のデフォルト値が使用されます。
  7. 残っている未解決のフィールドが、解決された日付または時間、あるいはその両方と照合されます。 したがって、これより前の段階では(年+月+「月の日」)が日付に解決され、この段階ではその日付に対して曜日が有効かどうかが確認されます。
  8. 超過日数が解析された場合は、日付が使用可能であれば日付に加算されます。
  9. 2番目のベース・フィールドが存在するが、LocalTimeが解析されなかった場合、リゾルバは、ChronoFieldの契約を満たすためにミリ、マイクロおよびナノ秒の値が使用可能であることを保証します。 これらは、欠落している場合はゼロに設定されます。
  10. 日付と時間の両方が解析され、オフセットまたはゾーンのいずれかが存在する場合は、フィールドChronoField.INSTANT_SECONDSが作成されます。 オフセットが解析された場合、オフセットはLocalDateTimeと組み合されてインスタントを形成し、ゾーンは無視されます。 ZoneIdがオフセットなしで解析された場合、ゾーンはLocalDateTimeと組み合わされてChronoLocalDateTime.atZone(ZoneId)の規則を使用してインスタントを形成します。 サマー・タイムが稼働中かどうかを示すゾーン名からZoneIdが解析された場合、そのファクトはローカル・タイムラインのオー・バー・ラップで正しいオフセットを選択するために使用されます。

実装要件:
このクラスは不変でスレッドセーフです。
導入されたバージョン:
1.8