モジュール 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 AD; 西暦; 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 day-of-week-in-month number 3
a am-pm-of-day text PM
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
'' 一重引用符 literal '
[ オプションのセクション開始
] オプションのセクション終了
# 将来使用するための予約
{ 将来使用するための予約
} 将来使用するための予約

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

テキスト: テキスト・スタイルは、使用されるパターン文字の数に基づいて決まります。 パターン文字が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)の規則を使用してインスタントを形成します。

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

  • フィールド詳細

    • ISO_LOCAL_DATE

      public static final DateTimeFormatter ISO_LOCAL_DATE
      日付をオフセットなしで書式設定または解析するISO日付フォーマッタ(「2011-12-03」など)。

      これは、ISO-8601拡張のローカル日付フォーマットの書式設定および解析を行える不変のフォーマッタを返します。 フォーマットは次のもので構成されます。

      • 年を表す4つ以上の桁。 0000から9999の範囲内にある年は、必ず4桁になるように前にゼロが追加されます。 その範囲外の年には、先頭に正符号または負符号が追加されます。
      • ダッシュ
      • 月を表す2桁。 これは必ず2桁になるように前にゼロが追加されます。
      • ダッシュ
      • 「月の日」を表す2桁。 これは必ず2桁になるように前にゼロが追加されます。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、STRICTリゾルバ・スタイルを使用します。

    • ISO_OFFSET_DATE

      public static final DateTimeFormatter ISO_OFFSET_DATE
      日付をオフセット付きで書式設定または解析するISO日付フォーマッタ(「2011-12-03+01:00」など)。

      これは、ISO-8601拡張のオフセット日付フォーマットの書式設定および解析を行える不変のフォーマッタを返します。 フォーマットは次のもので構成されます。

      • ISO_LOCAL_DATE
      • オフセットID。 オフセットに秒が含まれている場合、ISO-8601標準には含まれていませんが秒も処理されます。 解析では大文字と小文字は区別されません。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、STRICTリゾルバ・スタイルを使用します。

    • ISO_DATE

      public static final DateTimeFormatter ISO_DATE
      使用可能な場合はオフセット付きで日付を書式設定または解析するISO日付フォーマッタ(「2011-12-03」、「2011-12-03+01:00」など)。

      これは、ISO-8601拡張の日付フォーマットの書式設定および解析を行える不変のフォーマッタを返します。 フォーマットは次のもので構成されます。

      • ISO_LOCAL_DATE
      • オフセットが使用不可の場合、書式設定は完了です。
      • オフセットID。 オフセットに秒が含まれている場合、ISO-8601標準には含まれていませんが秒も処理されます。 解析では大文字と小文字は区別されません。

      このフォーマッタにはオプション要素があるため、parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)を使用して解析する必要がある場合があります。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、STRICTリゾルバ・スタイルを使用します。

    • ISO_LOCAL_TIME

      public static final DateTimeFormatter ISO_LOCAL_TIME
      時間をオフセットなしで書式設定または解析するISO時間フォーマッタ(「10:15」、「10:15:30」など)。

      これは、ISO-8601拡張のローカル時間フォーマットの書式設定および解析を行える不変のフォーマッタを返します。 フォーマットは次のもので構成されます。

      • 時を表す2桁。 これは必ず2桁になるように前にゼロが追加されます。
      • コロン
      • 分を表す2桁。 これは必ず2桁になるように前にゼロが追加されます。
      • 秒が使用不可の場合、書式設定は完了です。
      • コロン
      • 秒を表す2桁。 これは必ず2桁になるように前にゼロが追加されます。
      • ナノ秒がゼロまたは使用不可の場合、書式設定は完了です。
      • 小数点
      • ナノ秒を表す1つから9つまでの桁。 桁数は必要なだけ出力されます。

      返されるフォーマッタは、オーバーライドする暦やゾーンを持ちません。 STRICTリゾルバ・スタイルを使用します。

    • ISO_OFFSET_TIME

      public static final DateTimeFormatter ISO_OFFSET_TIME
      時間をオフセット付きで書式設定または解析するISO時間フォーマッタ(「10:15+01:00」、「10:15:30+01:00」など)。

      これは、ISO-8601拡張のオフセット時間フォーマットの書式設定および解析を行える不変のフォーマッタを返します。 フォーマットは次のもので構成されます。

      • ISO_LOCAL_TIME
      • オフセットID。 オフセットに秒が含まれている場合、ISO-8601標準には含まれていませんが秒も処理されます。 解析では大文字と小文字は区別されません。

      返されるフォーマッタは、オーバーライドする暦やゾーンを持ちません。 STRICTリゾルバ・スタイルを使用します。

    • ISO_TIME

      public static final DateTimeFormatter ISO_TIME
      使用可能な場合はオフセット付きで時間を書式設定または解析するISO時間フォーマッタ(「10:15」、「10:15:30」、「10:15:30+01:00」など)。

      これは、ISO-8601拡張のオフセット時間フォーマットの書式設定および解析を行える不変のフォーマッタを返します。 フォーマットは次のもので構成されます。

      • ISO_LOCAL_TIME
      • オフセットが使用不可の場合、書式設定は完了です。
      • オフセットID。 オフセットに秒が含まれている場合、ISO-8601標準には含まれていませんが秒も処理されます。 解析では大文字と小文字は区別されません。

      このフォーマッタにはオプション要素があるため、parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)を使用して解析する必要がある場合があります。

      返されるフォーマッタは、オーバーライドする暦やゾーンを持ちません。 STRICTリゾルバ・スタイルを使用します。

    • ISO_LOCAL_DATE_TIME

      public static final DateTimeFormatter ISO_LOCAL_DATE_TIME
      日付/時間をオフセットなしで書式設定または解析するISO日付/時間フォーマッタ(「2011-12-03T10:15:30」など)。

      これは、ISO-8601拡張のオフセット日付/時間フォーマットの書式設定および解析を行える不変のフォーマッタを返します。 フォーマットは次のもので構成されます。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、STRICTリゾルバ・スタイルを使用します。

    • ISO_OFFSET_DATE_TIME

      public static final DateTimeFormatter ISO_OFFSET_DATE_TIME
      日付/時間をオフセット付きで書式設定または解析するISO日付/時間フォーマッタ(「2011-12-03T10:15:30+01:00」など)。

      これは、ISO-8601拡張のオフセット日付/時間フォーマットの書式設定および解析を行える不変のフォーマッタを返します。 フォーマットは次のもので構成されます。

      • ISO_LOCAL_DATE_TIME
      • オフセットID。 オフセットに秒が含まれている場合、ISO-8601標準には含まれていませんが秒も処理されます。 オフセット解析は寛大で、分と秒をオプションにすることができます。 解析では大文字と小文字は区別されません。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、STRICTリゾルバ・スタイルを使用します。

    • ISO_ZONED_DATE_TIME

      public static final DateTimeFormatter ISO_ZONED_DATE_TIME
      オフセットおよびゾーン付きで日付/時間を書式設定または解析する、ISOに似た日付/時間フォーマッタ(「2011-12-03T10:15:30+01:00[Europe/Paris]」など)。

      これは、ISO-8601拡張のオフセット日付/時間フォーマットを拡張してタイムゾーンを追加するフォーマットの書式設定および解析を行える不変のフォーマッタを返します。 角括弧内のセクションはISO-8601標準には含まれていません。 フォーマットは次のもので構成されます。

      • ISO_OFFSET_DATE_TIME
      • ゾーンIDが使用不可またはZoneOffsetである場合、書式設定は完了です。
      • 左角括弧'['。
      • ゾーンID。 これはISO-8601標準には含まれていません。 解析では大文字と小文字が区別されます。
      • 右角括弧']'。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、STRICTリゾルバ・スタイルを使用します。

    • ISO_DATE_TIME

      public static final DateTimeFormatter ISO_DATE_TIME
      使用可能な場合はオフセットおよびゾーン付きで日付/時間を書式設定または解析する、ISOに似た日付/時間フォーマッタ(「2011-12-03T10:15:30」、「2011-12-03T10:15:30+01:00」、「2011-12-03T10:15:30+01:00[Europe/Paris]」など)。

      これは、ISO-8601拡張のローカルまたはオフセット日付/時間フォーマット、およびタイムゾーンを指定するISO以外の拡張形式の、書式設定および解析を行える不変のフォーマッタを返します。 フォーマットは次のもので構成されます。

      • ISO_LOCAL_DATE_TIME
      • オフセットが書式設定または解析に使用できない場合、書式設定は完了です。
      • オフセットID。 オフセットに秒が含まれている場合、ISO-8601標準には含まれていませんが秒も処理されます。
      • ゾーンIDが使用不可またはZoneOffsetである場合、書式設定は完了です。
      • 左角括弧'['。
      • ゾーンID。 これはISO-8601標準には含まれていません。 解析では大文字と小文字が区別されます。
      • 右角括弧']'。

      このフォーマッタにはオプション要素があるため、parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)を使用して解析する必要がある場合があります。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、STRICTリゾルバ・スタイルを使用します。

    • ISO_ORDINAL_DATE

      public static final DateTimeFormatter ISO_ORDINAL_DATE
      序数形式の日付をオフセットなしで書式設定または解析するISO日付フォーマッタ(「2012-337」など)。

      これは、ISO-8601拡張の序数形式日付フォーマットの書式設定および解析を行える不変のフォーマッタを返します。 フォーマットは次のもので構成されます。

      • 年を表す4つ以上の桁。 0000から9999の範囲内にある年は、必ず4桁になるように前にゼロが追加されます。 その範囲外の年には、先頭に正符号または負符号が追加されます。
      • ダッシュ
      • 「年の日」を表す3桁。 これは必ず3桁になるように前にゼロが追加されます。
      • オフセットが書式設定または解析に使用できない場合、書式設定は完了です。
      • オフセットID。 オフセットに秒が含まれている場合、ISO-8601標準には含まれていませんが秒も処理されます。 解析では大文字と小文字は区別されません。

      このフォーマッタにはオプション要素があるため、parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)を使用して解析する必要がある場合があります。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、STRICTリゾルバ・スタイルを使用します。

    • ISO_WEEK_DATE

      public static final DateTimeFormatter ISO_WEEK_DATE
      週ベースの日付をオフセットなしで書式設定または解析するISO日付フォーマッタ(「2012-W48-6」など)。

      これは、ISO-8601拡張の週ベース日付フォーマットの書式設定および解析を行える不変のフォーマッタを返します。 フォーマットは次のもので構成されます。

      • 週ベースの年を表す4つ以上の桁。 0000から9999の範囲内にある年は、必ず4桁になるように前にゼロが追加されます。 その範囲外の年には、先頭に正符号または負符号が追加されます。
      • ダッシュ
      • 文字'W'。 解析では大文字と小文字は区別されません。
      • 週ベースの年の週を表す2桁。 これは必ず3桁になるように前にゼロが追加されます。
      • ダッシュ
      • 曜日を表す1桁。 値の範囲は月曜(1)から日曜(7)までです。
      • オフセットが書式設定または解析に使用できない場合、書式設定は完了です。
      • オフセットID。 オフセットに秒が含まれている場合、ISO-8601標準には含まれていませんが秒も処理されます。 解析では大文字と小文字は区別されません。

      このフォーマッタにはオプション要素があるため、parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)を使用して解析する必要がある場合があります。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、STRICTリゾルバ・スタイルを使用します。

    • ISO_INSTANT

      public static final DateTimeFormatter ISO_INSTANT
      UTCのインスタントを書式設定または解析するISOインスタント・フォーマッタ(「2011-12-03T10:15:30Z」など)。

      これは、ISO-8601インスタント・フォーマットの書式設定および解析を行える不変のフォーマッタを返します。 書式設定時、インスタントのサフィクスは常に'Z'で示され、UTCが示されます。 秒は常に出力されます。 ナノ秒は必要に応じてゼロ、3,6または9桁を出力します。 解析時には、DateTimeFormatterBuilder.appendOffsetId()の動作を使用してオフセットを解析し、必要に応じてインスタントをUTCに変換します。 少なくとも秒までの時間フィールドは必須です。 0から9までの小数点以下の秒が解析されます。 ローカライズされた10進スタイルは使用されません。

      これは、人間が読める形式のInstantを使用可能にするための特殊なフォーマッタです。 Instantクラスは、時間のある1点を表すためだけに設計されており、固定の元期1970-01-01Zからのナノ秒単位の値を内部に格納しています。 したがって、Instantを日付や時間として書式設定するには、なんらかの形式のタイムゾーンを指定する必要があります。 このフォーマッタでは、ZoneOffset.UTCを使用して適切な変換を提供することにより、Instantを書式設定できます。

      フォーマットは次のもので構成されます。

      返されるフォーマッタは、オーバーライドする暦やゾーンを持ちません。 STRICTリゾルバ・スタイルを使用します。

    • BASIC_ISO_DATE

      public static final DateTimeFormatter BASIC_ISO_DATE
      日付をオフセットなしで書式設定または解析するISO日付フォーマッタ(「20111203」など)。

      これは、ISO-8601基本のローカル日付フォーマットの書式設定および解析を行える不変のフォーマッタを返します。 フォーマットは次のもので構成されます。

      • 年を表す4桁。 0000から9999の範囲内にある年だけがサポートされます。
      • 月を表す2桁。 これは必ず2桁になるように前にゼロが追加されます。
      • 「月の日」を表す2桁。 これは必ず2桁になるように前にゼロが追加されます。
      • オフセットが書式設定または解析に使用できない場合、書式設定は完了です。
      • コロンを含まないオフセットID。 オフセットに秒が含まれている場合、ISO-8601標準には含まれていませんが秒も処理されます。 オフセット解析は寛大で、分と秒をオプションにすることができます。 解析では大文字と小文字は区別されません。

      このフォーマッタにはオプション要素があるため、parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)を使用して解析する必要がある場合があります。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、STRICTリゾルバ・スタイルを使用します。

    • RFC_1123_DATE_TIME

      public static final DateTimeFormatter RFC_1123_DATE_TIME
      RFC-1123日付/時間フォーマッタ(「Tue, 3 Jun 2008 11:05:30 GMT」など)。

      これは、ほとんどのRFC-1123フォーマットの書式設定および解析を行える不変のフォーマッタを返します。 RFC-1123は、年を2桁から4桁に変更するRFC-822の更新です。 この実装には4桁の年が必要です。 また、この実装では「GMT」とオフセット量だけが処理され、北米のゾーン名やミリタリー・ゾーン名は処理されません。

      フォーマットは次のもので構成されます。

      • 曜日が書式設定または解析に使用できない場合、「月の日」にジャンプします。
      • 曜日を英語で表す3文字。
      • カンマ
      • スペース
      • 「月の日」を表す1桁または2桁。
      • スペース
      • 月を英語で表す3文字。
      • スペース
      • 年を表す4桁。 0000から9999の範囲内にある年だけがサポートされます。
      • スペース
      • 時を表す2桁。 これは必ず2桁になるように前にゼロが追加されます。
      • コロン
      • 分を表す2桁。 これは必ず2桁になるように前にゼロが追加されます。
      • 秒が使用不可の場合、次のスペースにジャンプします。
      • コロン
      • 秒を表す2桁。 これは必ず2桁になるように前にゼロが追加されます。
      • スペース
      • コロンや秒を含まないオフセットID。 オフセットがゼロの場合は「GMT」が使用されます。 北米のゾーン名とミリタリー・ゾーン名は処理されません。

      解析では大文字と小文字は区別されません。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、SMARTリゾルバ・スタイルを使用します。

  • メソッドの詳細

    • ofPattern

      public static DateTimeFormatter ofPattern​(String pattern)
      指定されたパターンを使用してフォーマッタを作成します。

      このメソッドは、クラスのドキュメントに説明されている単純な文字と記号のパターンに基づくフォーマッタを作成します。 たとえば、d MMM uuuuを使用すると、2011-12-03は「3 Dec 2011」と書式設定されます。

      フォーマッタはデフォルトのFORMATロケールを使用します。 これを変更するには、返されたフォーマッタに対してwithLocale(Locale)を使用します あるいは、このメソッドのofPattern(String, Locale)バリアントを使用してください。

      返されるフォーマッタは、オーバーライドする暦やゾーンを持ちません。 SMARTリゾルバ・スタイルを使用します。

      パラメータ:
      pattern - 使用するパターン。null以外
      戻り値:
      パターンに基づくフォーマッタ。null以外
      例外:
      IllegalArgumentException - パターンが無効な場合
      関連項目:
      DateTimeFormatterBuilder.appendPattern(String)

    • ofPattern

      public static DateTimeFormatter ofPattern​(String pattern, Locale locale)
      指定されたパターンおよびロケールを使用してフォーマッタを作成します。

      このメソッドは、クラスのドキュメントに説明されている単純な文字と記号のパターンに基づくフォーマッタを作成します。 たとえば、d MMM uuuuを使用すると、2011-12-03は「3 Dec 2011」と書式設定されます。

      フォーマッタは指定されたロケールを使用します。 これを変更するには、返されたフォーマッタに対してwithLocale(Locale)を使用します

      返されるフォーマッタは、オーバーライドする暦やゾーンを持ちません。 SMARTリゾルバ・スタイルを使用します。

      パラメータ:
      pattern - 使用するパターン。null以外
      locale - 使用するロケール。null以外
      戻り値:
      パターンに基づくフォーマッタ。null以外
      例外:
      IllegalArgumentException - パターンが無効な場合
      関連項目:
      DateTimeFormatterBuilder.appendPattern(String)

    • ofLocalizedDate

      public static DateTimeFormatter ofLocalizedDate​(FormatStyle dateStyle)
      ISO暦に対するロケール固有の日付フォーマットを返します。

      これは、日付の書式設定または解析を行うフォーマッタを返します。 使用される正確なフォーマット・パターンはロケールによって異なります。

      ロケールはフォーマッタから判定されます。 直接このメソッドから返されたフォーマッタは、デフォルトのFORMATロケールを使用します。 このメソッドの結果に対してwithLocale(Locale)を使用することにより、ロケールを制御できます。

      ローカライズされたパターンの検索は遅延的に行われます。 このDateTimeFormatterは、要求されたスタイルとロケールを保持し、要求されたパターンをオン・デマンドで検索します。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、SMARTリゾルバ・スタイルを使用します。

      パラメータ:
      dateStyle - 取得するフォーマッタ・スタイル。null以外
      戻り値:
      日付フォーマッタ。null以外

    • ofLocalizedTime

      public static DateTimeFormatter ofLocalizedTime​(FormatStyle timeStyle)
      ISO暦に対するロケール固有の時間フォーマットを返します。

      これは、時間の書式設定または解析を行うフォーマッタを返します。 使用される正確なフォーマット・パターンはロケールによって異なります。

      ロケールはフォーマッタから判定されます。 直接このメソッドから返されたフォーマッタは、デフォルトのFORMATロケールを使用します。 このメソッドの結果に対してwithLocale(Locale)を使用することにより、ロケールを制御できます。

      ローカライズされたパターンの検索は遅延的に行われます。 このDateTimeFormatterは、要求されたスタイルとロケールを保持し、要求されたパターンをオン・デマンドで検索します。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、SMARTリゾルバ・スタイルを使用します。 FULLおよびLONGスタイルには通常、タイムゾーンが必要です。 これらのスタイルを使用してフォーマットする場合は、ZonedDateTimeまたはwithZone(java.time.ZoneId)を使用してZoneIdを使用可能にする必要があります。

      パラメータ:
      timeStyle - 取得するフォーマッタ・スタイル。null以外
      戻り値:
      時間フォーマッタ。null以外

    • ofLocalizedDateTime

      public static DateTimeFormatter ofLocalizedDateTime​(FormatStyle dateTimeStyle)
      ISO暦に対するロケール固有の日付/時間フォーマッタを返します。

      これは、日付/時間の書式設定または解析を行うフォーマッタを返します。 使用される正確なフォーマット・パターンはロケールによって異なります。

      ロケールはフォーマッタから判定されます。 直接このメソッドから返されたフォーマッタは、デフォルトのFORMATロケールを使用します。 このメソッドの結果に対してwithLocale(Locale)を使用することにより、ロケールを制御できます。

      ローカライズされたパターンの検索は遅延的に行われます。 このDateTimeFormatterは、要求されたスタイルとロケールを保持し、要求されたパターンをオン・デマンドで検索します。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、SMARTリゾルバ・スタイルを使用します。 FULLおよびLONGスタイルには通常、タイムゾーンが必要です。 これらのスタイルを使用してフォーマットする場合は、ZonedDateTimeまたはwithZone(java.time.ZoneId)を使用してZoneIdを使用可能にする必要があります。

      パラメータ:
      dateTimeStyle - 取得するフォーマッタ・スタイル。null以外
      戻り値:
      日付/時間フォーマッタ。null以外

    • ofLocalizedDateTime

      public static DateTimeFormatter ofLocalizedDateTime​(FormatStyle dateStyle, FormatStyle timeStyle)
      ISO暦に対するロケール固有の日付と時間のフォーマットを返します。

      これは、日付/時間の書式設定または解析を行うフォーマッタを返します。 使用される正確なフォーマット・パターンはロケールによって異なります。

      ロケールはフォーマッタから判定されます。 直接このメソッドから返されたフォーマッタは、デフォルトのFORMATロケールを使用します。 このメソッドの結果に対してwithLocale(Locale)を使用することにより、ロケールを制御できます。

      ローカライズされたパターンの検索は遅延的に行われます。 このDateTimeFormatterは、要求されたスタイルとロケールを保持し、要求されたパターンをオン・デマンドで検索します。

      他の暦体系の日付が正しく変換されるようにするために、返されるフォーマッタにはISO暦が設定されます。 オーバーライド・ゾーンを持たず、SMARTリゾルバ・スタイルを使用します。 FULLおよびLONGスタイルには通常、タイムゾーンが必要です。 これらのスタイルを使用してフォーマットする場合は、ZonedDateTimeまたはwithZone(java.time.ZoneId)を使用してZoneIdを使用可能にする必要があります。

      パラメータ:
      dateStyle - 取得する日付フォーマッタ・スタイル。null以外
      timeStyle - 取得する時間フォーマッタ・スタイル。null以外
      戻り値:
      日付、時間、または日付/時間フォーマッタ。null以外

    • parsedExcessDays

      public static final TemporalQuery<Period> parsedExcessDays()
      解析された超過日数へのアクセスを提供する問合せ。

      これは、解析からの追加情報へのアクセスを提供する単体問合わせを返します。 問合わせは常にnull以外の期間を返し、nullの代わりにゼロの期間を返します。

      この問合わせがゼロ以外の期間を返す状況は2つあります。

      • ResolverStyleがLENIENTの場合、日付を含まない時間が解析されると、完全な解析結果はLocalTimeと超過Period (日数)から構成されます。
      • ResolverStyleがSMARTの場合、日付を含まない時間が解析され、その時間が24:00:00であるとき、完全な解析結果はLocalTime 00:00:00と超過Period 1日から構成されます。

      どちらの場合も、完全なChronoLocalDateTimeまたはInstantが解析されると、日付部分に超過日数が加算されます。 結果として、この問合わせはゼロの期間を返します。

      SMART動作では、「1日の終わり」としてよく使用される値24:00が処理されます。 LENIENTモードで処理した場合も、同じ結果になります。 

        Text to parse        Parsed object                         Excess days
  "2012-12-03T00:00"   LocalDateTime.of(2012, 12, 3, 0, 0)   ZERO
  "2012-12-03T24:00"   LocalDateTime.of(2012, 12, 4, 0, 0)   ZERO
  "00:00"              LocalTime.of(0, 0)                    ZERO
  "24:00"              LocalTime.of(0, 0)                    Period.ofDays(1)
      問合わせは次のように使用できます。 
        TemporalAccessor parsed = formatter.parse(str);
  LocalTime time = parsed.query(LocalTime::from);
  Period extraDays = parsed.query(DateTimeFormatter.parsedExcessDays());

      戻り値:
      解析された超過日数へのアクセスを提供する問合わせ

    • parsedLeapSecond

      public static final TemporalQuery<Boolean> parsedLeapSecond()
      うるう秒を解析したかどうかへのアクセスを提供する問合せ。

      これは、解析からの追加情報へのアクセスを提供する単体問合わせを返します。 問合わせは常にnull以外のブール値を返します。うるう秒が解析された場合はtrue、それ以外の場合はfalseです。

      インスタントの解析では、特殊な「うるう秒」時間「23:59:60」が処理されます。 うるう秒は、UTCタイムゾーンでは「23:59:60」に発生しますが、タイムゾーンによっては他のローカル時間に発生します。 この潜在的なあいまいさを回避するために、うるう秒の処理はDateTimeFormatterBuilder.appendInstant()に限定されています。このメソッドは常にUTCゾーン・オフセットでインスタントを解析するからです。

      時間「23:59:60」が受け取られた場合は、秒60を59で置き換える単純な変換が適用されます。 この問合わせを解析結果に対して使用すると、うるう秒の調整が行われたかどうかを判定できます。 問合せは、うるう秒を削除する調整が行われた場合はtrueを返し、それ以外の場合はfalseを返します。 UTC-SLSといったうるう秒の平滑化メカニズムの適用は、次のようにアプリケーションで行う必要があります。 

        TemporalAccessor parsed = formatter.parse(str);
  Instant instant = parsed.query(Instant::from);
  if (parsed.query(DateTimeFormatter.parsedLeapSecond())) {
    // validate leap-second is correct and apply correct smoothing
  }

      戻り値:
      うるう秒が解析されたかどうかへのアクセスを提供する問合わせ

    • getLocale

      public Locale getLocale()
      書式設定時に使用されるロケールを取得します。

      これは、特定のローカリゼーションを必要とするフォーマッタの部分(テキストやローカライズされたパターンなど)を検索するために使用されます。

      戻り値:
      このフォーマッタのロケール。null以外

    • withLocale

      public DateTimeFormatter withLocale​(Locale locale)
      新しいロケールを使って、このフォーマッタのコピーを返します。

      これは、特定のローカリゼーションを必要とするフォーマッタの部分(テキストやローカライズされたパターンなど)を検索するために使用されます。

      ロケールは、そのまま処理されることなく渡された状態で保存されます。 ロケールに「Unicode拡張」がある場合は、後でテキスト処理で使用できます。 ユニコード拡張から年表、時間帯および小数点のスタイルを設定するには、localizedBy()を参照してください。

      このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

      パラメータ:
      locale - 新しいロケール。null以外
      戻り値:
      要求されたロケールを持つ、このフォーマッタに基づくフォーマッタ。null以外
      関連項目:
      localizedBy(Locale)

    • localizedBy

      public DateTimeFormatter localizedBy​(Locale locale)
      ロケール、カレンダ、リージョン、小数点以下のスタイルおよび/またはタイムゾーンのローカライズされた値を持つこのフォーマッタのコピーを返します。

      これは、特定のローカリゼーションを必要とするフォーマッタの部分(テキストやローカライズされたパターンなど)を検索するために使用されます。 ロケールに、"ca" (calendar)、"rg" (リージョン・オーバーライド)、および/または"tz" (timezone) 「Unicode拡張」が含まれている場合、カレンダ、国および/または書式設定のタイムゾーンがオーバーライドされます。 "ca"と"rg"の両方が指定されている場合、"ca"拡張子の年表は、"rg"拡張子の暗黙のものよりも優先されます。 "nu"拡張機能についても同じです。

      withLocaleメソッドとは異なり、このメソッドを呼び出すと、他のwithXXXX()メソッドとのメソッド連鎖の順序によって、異なるフォーマッタが生成されることがあります。

      このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

      パラメータ:
      locale - ロケール。null以外
      戻り値:
      このフォーマッタの値を置き換えるカレンダ、小数点のスタイルおよび/またはタイムゾーンのローカライズされた値を持つこのフォーマッタに基づくフォーマッタ。
      導入されたバージョン:
      10
      関連項目:
      withLocale(Locale)

    • getDecimalStyle

      public DecimalStyle getDecimalStyle()
      書式設定時に使用されるDecimalStyleを取得します。
      戻り値:
      このフォーマッタのロケール。null以外

    • withDecimalStyle

      public DateTimeFormatter withDecimalStyle​(DecimalStyle decimalStyle)
      新しいDecimalStyleを使って、このフォーマッタのコピーを返します。

      このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

      パラメータ:
      decimalStyle - 新しいDecimalStyle。null以外
      戻り値:
      要求されたDecimalStyleを持つ、このフォーマッタに基づくフォーマッタ。null以外

    • getChronology

      public Chronology getChronology()
      書式設定時に使用するオーバーライドする暦を取得します。

      これは、日付の変換に使用されるオーバーライド暦を返します。 デフォルトでは、フォーマッタはオーバーライド暦を持たないため、nullが返されます。 オーバーライドの詳細については、withChronology(Chronology)を参照してください。

      戻り値:
      このフォーマッタのオーバーライド暦。オーバーライドがない場合はnull

    • withChronology

      public DateTimeFormatter withChronology​(Chronology chrono)
      オーバーライドされた新しい暦を使って、このフォーマッタのコピーを返します。

      これは、このフォーマッタに似た状態のフォーマッタを返します。ただし、オーバーライド暦が設定されています。 デフォルトでは、フォーマッタはオーバーライド暦を持たないため、nullが返されます。

      オーバーライドが追加された場合、書式設定または解析される任意の日付が影響を受けます。

      書式設定時は、時間的オブジェクトに日付が含まれている場合、オーバーライド暦の日付に変換されます。 時間的オブジェクトに日付が含まれているかどうかは、EPOCH_DAYフィールドを照会することによって判定されます。 時間とゾーンは、オーバーライドされないかぎり変更されません。

      時間的オブジェクトに日付が含まれていないにもかかわらず、1つ以上のChronoField日付フィールドが含まれている場合は、DateTimeExceptionがスローされます。 その他の場合はすべて、オーバーライド暦が時間的オブジェクトに追加されます。それによって以前の暦は置き換えられますが、日付/時間は変更されません。

      解析時は、異なる2つの場合を考慮する必要があります。 おそらくDateTimeFormatterBuilder.appendChronologyId()が使用されたために、暦がテキストから直接解析された場合、このオーバーライド暦は何の効果も持ちません。 ゾーンが解析されなかった場合は、このオーバーライド暦を使用して、暦の日付解決ルールに従ってChronoField値が日付に解釈されます。

      このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

      パラメータ:
      chrono - 新しい暦。オーバーライドがない場合はnull
      戻り値:
      要求されたオーバーライド暦を持つ、このフォーマッタに基づくフォーマッタ。null以外

    • getZone

      public ZoneId getZone()
      書式設定時に使用されるオーバーライド・ゾーンを取得します。

      これは、インスタントの変換に使用されるオーバーライド・ゾーンを返します。 デフォルトでは、フォーマッタはオーバーライド・ゾーンを持たないため、nullが返されます。 オーバーライドの詳細については、withZone(ZoneId)を参照してください。

      戻り値:
      このフォーマッタのオーバーライド・ゾーン。オーバーライドがない場合はnull

    • withZone

      public DateTimeFormatter withZone​(ZoneId zone)
      新しいオーバーライドゾーンを使って、このフォーマッタのコピーを返します。

      これは、このフォーマッタに似た状態のフォーマッタを返します。ただし、オーバーライド・ゾーンが設定されています。 デフォルトでは、フォーマッタはオーバーライド・ゾーンを持たないため、nullが返されます。

      オーバーライドが追加された場合、書式設定または解析される任意のインスタントが影響を受けます。

      書式設定時は、時間的オブジェクトにインスタントが含まれている場合、オーバーライド・ゾーンを使用してゾーン指定の日付/時間に変換されます。 時間的オブジェクトがインスタントであるかどうかは、INSTANT_SECONDSフィールドを照会することによって判定されます。 入力に暦が含まれている場合は、それがオーバーライドされないかぎり維持されます。 Instantのように、入力に暦が含まれていない場合は、ISO暦が使用されます。

      時間的オブジェクトにインスタントが含まれていないにもかかわらず、オフセットが含まれている場合は、追加チェックが行われます。 正規化されたオーバーライド・ゾーンが、時間的オブジェクトのオフセットとは異なるオフセットである場合、DateTimeExceptionがスローされます。 その他の場合はすべて、オーバーライド・ゾーンが時間的オブジェクトに追加されます。それによって以前のゾーンは置き換えられますが、日付/時間は変更されません。

      解析時は、異なる2つの場合を考慮する必要があります。 おそらくDateTimeFormatterBuilder.appendZoneId()が使用されたために、ゾーンがテキストから直接解析された場合、このオーバーライド・ゾーンは何の効果も持ちません。 ゾーンが解析されなかった場合、このオーバーライド・ゾーンは解析結果に含められ、インスタントおよび日付/時間の構築に使用されます。

      このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

      パラメータ:
      zone - 新しいオーバーライド・ゾーン。オーバーライドがない場合はnull
      戻り値:
      要求されたオーバーライド・ゾーンを持つ、このフォーマッタに基づくフォーマッタ。null以外

    • getResolverStyle

      public ResolverStyle getResolverStyle()
      解析時に使用するリゾルバ・スタイルを取得します。

      これは、フィールドを日付と時間に解決する解析の第2フェーズで使用されるリゾルバ・スタイルを返します。 デフォルトでは、フォーマッタはSMARTリゾルバ・スタイルを持ちます。 詳細は、withResolverStyle(ResolverStyle)を参照してください。

      戻り値:
      このフォーマッタのリゾルバ・スタイル。null以外

    • withResolverStyle

      public DateTimeFormatter withResolverStyle​(ResolverStyle resolverStyle)
      新しいリゾルバ・スタイルを使って、このフォーマッタのコピーを返します。

      これは、このフォーマッタに似た状態のフォーマッタを返します。ただし、リゾルバ・スタイルが設定されています。 デフォルトでは、フォーマッタはSMARTリゾルバ・スタイルを持ちます。

      リゾルバ・スタイルの変更が効果を持つのは、解析時のみです。 テキスト文字列の解析は2段階で行われます。 フェーズ1は、ビルダーに追加されたフィールドに従って行われる基本的なテキスト解析です。 フェーズ2では、解析されたフィールドと値のペアが、日付または時間オブジェクト、あるいはその両方に解決されます。 リゾルバ・スタイルは、フェーズ2 (解決)をどのように行うかを制御するために使用されます。 使用可能なオプションの詳細については、ResolverStyleを参照してください。

      このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

      パラメータ:
      resolverStyle - 新しいリゾルバ・スタイル。null以外
      戻り値:
      要求されたリゾルバ・スタイルを持つ、このフォーマッタに基づくフォーマッタ。null以外

    • getResolverFields

      public Set<TemporalField> getResolverFields()
      解析時に使用するリゾルバ・フィールドを取得します。

      これは、フィールドを日付と時間に解決する解析の第2フェーズで使用されるリゾルバ・フィールドを返します。 デフォルトでは、フォーマッタはリゾルバ・フィールドを持たないため、nullが返されます。 詳細は、withResolverFields(Set)を参照してください。

      戻り値:
      このフォーマッタのリゾルバ・フィールドの不変セット。フィールドがない場合はnull

    • withResolverFields

      public DateTimeFormatter withResolverFields​(TemporalField... resolverFields)
      新しいリゾルバ・フィールドのセットを使って、このフォーマッタのコピーを返します。

      これは、このフォーマッタに似た状態のフォーマッタを返します。ただし、リゾルバ・フィールドが設定されています。 デフォルトでは、フォーマッタはリゾルバ・フィールドを持ちません。

      リゾルバ・フィールドの変更が効果を持つのは、解析時のみです。 テキスト文字列の解析は2段階で行われます。 フェーズ1は、ビルダーに追加されたフィールドに従って行われる基本的なテキスト解析です。 フェーズ2では、解析されたフィールドと値のペアが、日付または時間オブジェクト、あるいはその両方に解決されます。 リゾルバ・フィールドは、フェーズ1と2の間でフィールドと値のペアをフィルタリングするために使用されます。

      日付または時間の解決方法を2つ以上から選択する場合に使用できます。 たとえば、フォーマッタが年、月、「月の日」、および「年の日」から構成されている場合、日付を解決する方法は2つあります。 引数YEARおよびDAY_OF_YEARを指定してこのメソッドを呼び出すと、日付は必ず年と「年の日」を使用して解決されます。これは実質的に、解決フェーズで月と「月の日」は無視されることを意味します。

      同様に、このメソッドを使用すると、それ以外の場合には照合される2次的なフィールドを無視することができます。 たとえば、フォーマッタが年、月、「月の日」、および曜日から構成されている場合、日付を解決する方法は1つだけですが、解析された曜日の値が解決された日付と照合されます。 引数YEAR、MONTH_OF_YEAR、およびDAY_OF_MONTHを指定してこのメソッドを呼び出すと、日付は必ず正しく解決されます。ただし、曜日の照合は行われません。

      実装の観点からは、このメソッドは次のように動作します。 解析フェーズの結果は、フィールドから値へのマップとみなすことができます。 このメソッドは、フェーズ1と2の間でそのマップのフィルタリングを発生させて、このメソッドの引数として指定されたフィールド以外のフィールドをすべて削除します。

      このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

      パラメータ:
      resolverFields - リゾルバ・フィールドの新しいセット。フィールドがない場合はnull
      戻り値:
      要求されたリゾルバ・スタイルを持つ、このフォーマッタに基づくフォーマッタ。null以外

    • withResolverFields

      public DateTimeFormatter withResolverFields​(Set<TemporalField> resolverFields)
      新しいリゾルバ・フィールドのセットを使って、このフォーマッタのコピーを返します。

      これは、このフォーマッタに似た状態のフォーマッタを返します。ただし、リゾルバ・フィールドが設定されています。 デフォルトでは、フォーマッタはリゾルバ・フィールドを持ちません。

      リゾルバ・フィールドの変更が効果を持つのは、解析時のみです。 テキスト文字列の解析は2段階で行われます。 フェーズ1は、ビルダーに追加されたフィールドに従って行われる基本的なテキスト解析です。 フェーズ2では、解析されたフィールドと値のペアが、日付または時間オブジェクト、あるいはその両方に解決されます。 リゾルバ・フィールドは、フェーズ1と2の間でフィールドと値のペアをフィルタリングするために使用されます。

      日付または時間の解決方法を2つ以上から選択する場合に使用できます。 たとえば、フォーマッタが年、月、「月の日」、および「年の日」から構成されている場合、日付を解決する方法は2つあります。 引数YEARおよびDAY_OF_YEARを指定してこのメソッドを呼び出すと、日付は必ず年と「年の日」を使用して解決されます。これは実質的に、解決フェーズで月と「月の日」は無視されることを意味します。

      同様に、このメソッドを使用すると、それ以外の場合には照合される2次的なフィールドを無視することができます。 たとえば、フォーマッタが年、月、「月の日」、および曜日から構成されている場合、日付を解決する方法は1つだけですが、解析された曜日の値が解決された日付と照合されます。 引数YEAR、MONTH_OF_YEAR、およびDAY_OF_MONTHを指定してこのメソッドを呼び出すと、日付は必ず正しく解決されます。ただし、曜日の照合は行われません。

      実装の観点からは、このメソッドは次のように動作します。 解析フェーズの結果は、フィールドから値へのマップとみなすことができます。 このメソッドは、フェーズ1と2の間でそのマップのフィルタリングを発生させて、このメソッドの引数として指定されたフィールド以外のフィールドをすべて削除します。

      このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

      パラメータ:
      resolverFields - リゾルバ・フィールドの新しいセット。フィールドがない場合はnull
      戻り値:
      要求されたリゾルバ・スタイルを持つ、このフォーマッタに基づくフォーマッタ。null以外

    • format

      public String format​(TemporalAccessor temporal)
      このフォーマッタを使用して日付/時間オブジェクトを書式設定します。

      これは、フォーマッタのルールを使用して、日付/時間をStringに書式設定します。

      パラメータ:
      temporal - 書式設定する時間的オブジェクト。null以外
      戻り値:
      書式設定された文字列。null以外
      例外:
      DateTimeException - 書式設定中にエラーが発生した場合

    • formatTo

      public void formatTo​(TemporalAccessor temporal, Appendable appendable)
      このフォーマッタを使用して、日付/時間オブジェクトをAppendableに書式設定します。

      これは、書式設定された日付/時間を、指定された出力先に出力します。 Appendableは、すべての主要な文字出力クラス(StringBuffer、StringBuilder、PrintStream、Writerなど)によって実装される汎用インタフェースです。

      AppendableのメソッドはIOExceptionをスローしますが、このメソッドはスローしません。 かわりに、IOExceptionはすべて実行時例外にラップされます。

      パラメータ:
      temporal - 書式設定する時間的オブジェクト。null以外
      appendable - 書式設定後のAppendable。null以外
      例外:
      DateTimeException - 書式設定中にエラーが発生した場合

    • parse

      public TemporalAccessor parse​(CharSequence text)
      テキストを完全に解析して、時間的オブジェクトを生成します。

      これはテキストを完全に解析して、時間的オブジェクトを生成します。 通常は、parse(CharSequence, TemporalQuery)を使用するほうが便利です。 このメソッドの結果は、解決されたTemporalAccessorです。有効な日付/時間を保証するために基本的な検証チェックが適用されています。

      テキストの長さ全体を読み取ることなく解析が完了した場合や、解析中またはマージ中に問題が発生した場合は、例外がスローされます。

      パラメータ:
      text - 解析するテキスト。null以外
      戻り値:
      解析された時間的オブジェクト。null以外
      例外:
      DateTimeParseException - 要求された結果を解析できない場合

    • parse

      public TemporalAccessor parse​(CharSequence text, ParsePosition position)
      このフォーマッタを使用してテキストを解析し、テキスト位置に対する制御を提供します。

      これはテキストを解析しますが、文字列の先頭から解析を開始したり、末尾で終了したりする必要はありません。 このメソッドの結果は、解決されたTemporalAccessorです。有効な日付/時間を保証するために基本的な検証チェックが適用されています。

      テキストは、指定された開始位置ParsePositionから解析されます。 テキストの長さ全体を解析する必要はなく、ParsePositionは解析の終了位置のインデックスで更新されます。

      このメソッドの処理は、ParsePositionをjava.text.Formatに対して使用する類似のメソッドとは多少異なります。 そのクラスは、ParsePositionのエラー・インデックスを使用してエラーを返します。 一方、このメソッドはエラーが発生するとDateTimeParseExceptionをスローし、その例外にエラー・インデックスを含めます。 日付/時間の解析と解決がこのAPIではより複雑になったため、この動作変更が必要になりました。

      フォーマッタが同じフィールドを複数回解析し、値が異なっている場合、結果はエラーになります。

      パラメータ:
      text - 解析するテキスト。null以外
      position - 解析を開始する位置。解析された長さで更新され、エラーがあればそのインデックスで更新されます。null以外
      戻り値:
      解析された時間的オブジェクト。null以外
      例外:
      DateTimeParseException - 要求された結果を解析できない場合
      IndexOutOfBoundsException - 位置が無効な場合

    • parse

      public <T> T parse​(CharSequence text, TemporalQuery<T> query)
      テキストを完全に解析して、指定された型のオブジェクトを生成します。

      ほとんどのアプリケーションでは、解析にこのメソッドを使用するようにしてください。 これはテキストを完全を解析して、要求された日付/時間を生成します。 通常、問合わせはfrom(TemporalAccessor)メソッドへのメソッド参照です。 次に例を示します。 

        LocalDateTime dt = parser.parse(str, LocalDateTime::from);
      テキストの長さ全体を読み取ることなく解析が完了した場合や、解析中またはマージ中に問題が発生した場合は、例外がスローされます。

      型パラメータ:
      T - 解析された日付/時間の型
      パラメータ:
      text - 解析するテキスト。null以外
      query - 解析後の型を定義する問合わせ。null以外
      戻り値:
      解析された日付/時間。null以外
      例外:
      DateTimeParseException - 要求された結果を解析できない場合

    • parseBest

      public TemporalAccessor parseBest​(CharSequence text, TemporalQuery<?>... queries)
      テキストを完全に解析して、指定されたいずれかのタイプのオブジェクトを生成します。

      この解析メソッドは、パーサーがオプション要素を処理できる場合に使いやすいメソッドです。 たとえば、「uuuu-MM-dd HH.mm[ VV]」というパターンは、完全に解析してZonedDateTimeにすることも、部分的に解析してLocalDateTimeにすることもできます。 もっとも一致する完全解析オプションから始めて、もっとも一致の少ない最小解析オプションまで、問合わせを順に指定する必要があります。 通常、問合わせはfrom(TemporalAccessor)メソッドへのメソッド参照です。

      結果は、正常に解析された最初の型に関連付けられます。 通常、アプリケーションではinstanceofを使用して結果を確認します。 次に例を示します。 

        TemporalAccessor dt = parser.parseBest(str, ZonedDateTime::from, LocalDateTime::from);
  if (dt instanceof ZonedDateTime) {
   ...
  } else {
   ...
  }
      テキストの長さ全体を読み取ることなく解析が完了した場合や、解析中またはマージ中に問題が発生した場合は、例外がスローされます。

      パラメータ:
      text - 解析するテキスト。null以外
      queries - 試みる解析後の型を定義する問合わせ。TemporalAccessorを実装する必要があります。null以外
      戻り値:
      解析された日付/時間。null以外
      例外:
      IllegalArgumentException - 2つ未満の型が指定された場合
      DateTimeParseException - 要求された結果を解析できない場合

    • parseUnresolved

      public TemporalAccessor parseUnresolved​(CharSequence text, ParsePosition position)
      このフォーマッタを使用してテキストを解析しますが、高度なユース・ケース向けに、結果を解決しません。

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

      このメソッドの結果は、入力に現れたとおりにデータを表すTemporalAccessorです。 値は検証されないため、「2012-00-65」という日付文字列を解析すると、3つのフィールドを持つ時間的オブジェクトが得られ、年は「2012」、月は「0」、「月の日」は「65」になります。

      テキストは、指定された開始位置ParsePositionから解析されます。 テキストの長さ全体を解析する必要はなく、ParsePositionは解析の終了位置のインデックスで更新されます。

      エラーはParsePositionのエラー・インデックス・フィールドを使用して返され、DateTimeParseExceptionは使用されません。 返されるエラー・インデックスは、そのエラーを表すインデックスに設定されます。 呼出し元は、結果を使用する前に、エラーがないかどうかを確認する必要があります。

      フォーマッタが同じフィールドを複数回解析し、値が異なっている場合、結果はエラーになります。

      このメソッドは、解析中に内部状態にアクセスする必要のある高度なユース・ケース向けです。 通常、アプリケーション・コードでは、parse(CharSequence, TemporalQuery)を使用するか、ターゲットの型に対してこの解析メソッドを使用するようにしてください。

      パラメータ:
      text - 解析するテキスト。null以外
      position - 解析を開始する位置。解析された長さで更新され、エラーがあればそのインデックスで更新されます。null以外
      戻り値:
      解析されたテキスト。解析がエラーになった場合はnull
      例外:
      DateTimeException - 解析中になんらかの問題が発生した場合
      IndexOutOfBoundsException - 位置が無効な場合

    • toFormat

      public Format toFormat()
      このフォーマッタをjava.text.Formatインスタンスとして返します。

      返されたFormatインスタンスは、任意のTemporalAccessorを書式設定し、解決済のTemporalAccessorに解析されます。

      例外はFormatの定義に従います。書式設定時のIllegalArgumentException、および解析時のParseExceptionまたはnullの詳細については、それらのメソッドを参照してください。 書式設定では、返された書式設定文字列の属性設定はサポートされません。

      戻り値:
      従来のフォーマット・インスタンスとしての、このフォーマッタ。null以外

    • toFormat

      public Format toFormat​(TemporalQuery<?> parseQuery)
      このフォーマッタを、指定された問合わせを使用して解析するjava.text.Formatインスタンスとして返します。

      返されたFormatインスタンスは、任意のTemporalAccessorを書式設定し、指定された型に解析されます。 型は、parse(java.lang.CharSequence)でサポートされているものでなければなりません。

      例外はFormatの定義に従います。書式設定時のIllegalArgumentException、および解析時のParseExceptionまたはnullの詳細については、それらのメソッドを参照してください。 書式設定では、返された書式設定文字列の属性設定はサポートされません。

      パラメータ:
      parseQuery - 解析後の型を定義する問合わせ。null以外
      戻り値:
      従来のフォーマット・インスタンスとしての、このフォーマッタ。null以外

    • toString

      public String toString()
      ベースとなるフォーマッタの説明を返します。
      オーバーライド:
      toString 、クラス:  Object
      戻り値:
      このフォーマッタの説明。null以外