モジュール java.base

パッケージ java.time.format

クラスDateTimeFormatterBuilder

java.lang.Object

java.time.format.DateTimeFormatterBuilder

public final class DateTimeFormatterBuilder extends Object

日付/時間フォーマッタを作成するためのビルダー。

これにより、DateTimeFormatterを作成できます。 すべての日付/時間フォーマッタは、最終的にこのビルダーを使用して作成されます。

日付/時間の基本要素はすべて追加できます。

• Value - 数値
• Fraction - 小数位を含む小数値。 小数部を出力するときは、小数部が正しく解析されるようにするために常にこれを使用してください。
• Text - 値のテキスト表現
• OffsetId/Offset - ゾーン・オフセット
• ZoneId - タイムゾーンのID
• ZoneText - タイムゾーンの名前
• ChronologyId - 暦のID
• ChronologyText - 暦の名前
• Literal - テキスト・リテラル
• Nested and Optional - フォーマットを入れ子にしたりオプションにしたりできます

また、いずれの要素も、スペースまたは他の任意の文字を使用したパディングによって装飾できます。

さらに、主にjava.text.SimpleDateFormat SimpleDateFormatと互換性のある簡易パターンを使用できます。appendPattern(String)を参照してください。 実際には、これは単にパターンを解析し、ビルダーの他のメソッドを呼び出します。

実装要件:

このクラスは、単一のスレッドから使用されることを想定した可変ビルダーです。

導入されたバージョン:

1.8

コンストラクタのサマリー

コンストラクタ

コンストラクタ	説明
DateTimeFormatterBuilder()	ビルダーの新しいインスタンスを構築します。

メソッドのサマリー

修飾子と型	メソッド	説明
DateTimeFormatterBuilder	append(DateTimeFormatter formatter)	フォーマッタのすべての要素をビルダーに追加します。
DateTimeFormatterBuilder	appendChronologyId()	「ISO」や「ThaiBuddhist」などの暦IDをフォーマッタに追加します。
DateTimeFormatterBuilder	appendChronologyText(TextStyle textStyle)	暦名をフォーマッタに追加します。
DateTimeFormatterBuilder	appendDayPeriodText(TextStyle style)	日期間テキストをフォーマッタに追加します。
DateTimeFormatterBuilder	appendFraction(TemporalField field, int minWidth, int maxWidth, boolean decimalPoint)	日付/時間フィールドの小数値をフォーマッタに追加します。
DateTimeFormatterBuilder	appendGenericZoneText(TextStyle textStyle)	「太平洋時間」などの一般的なタイムゾーン名をフォーマッタに追加します。
DateTimeFormatterBuilder	appendGenericZoneText(TextStyle textStyle, Set<ZoneId> preferredZones)	「太平洋時間」などの一般的なタイムゾーン名をフォーマッタに追加します。
DateTimeFormatterBuilder	appendInstant()	ISO-8601を使用してインスタントをフォーマッタに追加します。小数部は3桁ずつに書式設定します。
DateTimeFormatterBuilder	appendInstant(int fractionalDigits)	ISO-8601を使用してインスタントをフォーマッタに追加します。小数部の桁数は制御できます。
DateTimeFormatterBuilder	appendLiteral(char literal)	文字リテラルをフォーマッタに追加します。
DateTimeFormatterBuilder	appendLiteral(String literal)	文字列リテラルをフォーマッタに追加します。
DateTimeFormatterBuilder	appendLocalized(String requestedTemplate)	リクエストされたテンプレートを使用して、ローカライズされたパターンをフォーマッタに追加します。
DateTimeFormatterBuilder	appendLocalized(FormatStyle dateStyle, FormatStyle timeStyle)	ローカライズされた日付/時間パターンをフォーマッタに追加します。
DateTimeFormatterBuilder	appendLocalizedOffset(TextStyle style)	「GMT+01:00」などのローカライズされたゾーン・オフセットをフォーマッタに追加します。
DateTimeFormatterBuilder	appendOffset(String pattern, String noOffsetText)	「+01:00」などのゾーン・オフセットをフォーマッタに追加します。
DateTimeFormatterBuilder	appendOffsetId()	「+01:00」などのゾーン・オフセットをフォーマッタに追加します。
DateTimeFormatterBuilder	appendOptional(DateTimeFormatter formatter)	オプションで書式設定/解析を行うフォーマッタをビルダーに追加します。
DateTimeFormatterBuilder	appendPattern(String pattern)	指定されたパターンによって定義される要素をビルダーに追加します。
DateTimeFormatterBuilder	appendText(TemporalField field)	フルテキスト・スタイルを使用して、日付/時間フィールドのテキストをフォーマッタに追加します。
DateTimeFormatterBuilder	appendText(TemporalField field, TextStyle textStyle)	日付/時間フィールドのテキストをフォーマッタに追加します。
DateTimeFormatterBuilder	appendText(TemporalField field, Map<Long,String> textLookup)	指定されたマップを使用してテキストを提供することにより、日付/時間フィールドのテキストをフォーマッタに追加します。
DateTimeFormatterBuilder	appendValue(TemporalField field)	通常の出力スタイルを使用して、日付/時間フィールドの値をフォーマッタに追加します。
DateTimeFormatterBuilder	appendValue(TemporalField field, int width)	ゼロでパディングする固定幅方式を使用して、日付/時間フィールドの値をフォーマッタに追加します。
DateTimeFormatterBuilder	appendValue(TemporalField field, int minWidth, int maxWidth, SignStyle signStyle)	日付/時間フィールドの値をフォーマッタに追加します。フォーマットは完全に制御できます。
DateTimeFormatterBuilder	appendValueReduced(TemporalField field, int width, int maxWidth, int baseValue)	日付/時間フィールドのリデュースされた値をフォーマッタに追加します。
DateTimeFormatterBuilder	appendValueReduced(TemporalField field, int width, int maxWidth, ChronoLocalDate baseDate)	日付/時間フィールドのリデュースされた値をフォーマッタに追加します。
DateTimeFormatterBuilder	appendZoneId()	「ヨーロッパ/パリ」や「+02:00」などのタイムゾーンIDをフォーマッタに追加します。
DateTimeFormatterBuilder	appendZoneOrOffsetId()	「ヨーロッパ/パリ」や「+02:00」などのタイムゾーンIDをフォーマッタに追加します。利用可能な最良のゾーンIDを使用します。
DateTimeFormatterBuilder	appendZoneRegionId()	「ヨーロッパ/パリ」などのタイムゾーン地域IDをフォーマッタに追加します。ゾーンIDがZoneOffsetの場合は拒否します。
DateTimeFormatterBuilder	appendZoneText(TextStyle textStyle)	「英国夏時間」などのタイムゾーン名をフォーマッタに追加します。
DateTimeFormatterBuilder	appendZoneText(TextStyle textStyle, Set<ZoneId> preferredZones)	「英国夏時間」などのタイムゾーン名をフォーマッタに追加します。
static String	getLocalizedDateTimePattern(String requestedTemplate, Chronology chrono, Locale locale)	ロケールおよび時系列について、リクエストされたテンプレートのフォーマット・パターンを返します。
static String	getLocalizedDateTimePattern(FormatStyle dateStyle, FormatStyle timeStyle, Chronology chrono, Locale locale)	ロケールおよび暦の日付および時間のスタイルの書式設定パターンを取得します。
DateTimeFormatterBuilder	optionalEnd()	オプションのセクションを終了します。
DateTimeFormatterBuilder	optionalStart()	オプションのセクションの開始をマークします。
DateTimeFormatterBuilder	padNext(int padWidth)	次に追加されるプリンタまたはパーサーで、空白を使用して固定幅のパディングを行います。
DateTimeFormatterBuilder	padNext(int padWidth, char padChar)	次に追加されるプリンタまたはパーサーで、固定幅のパディングを行います。
DateTimeFormatterBuilder	parseCaseInsensitive()	フォーマッタの残りに対して、解析スタイルを大文字小文字の区別なしに変更します。
DateTimeFormatterBuilder	parseCaseSensitive()	フォーマッタの残りに対して、解析スタイルを大文字小文字の区別ありに変更します。
DateTimeFormatterBuilder	parseDefaulting(TemporalField field, long value)	解析に使用するフォーマッタに、フィールドのデフォルト値を追加します。
DateTimeFormatterBuilder	parseLenient()	フォーマッタの残りに対して、解析スタイルを寛大な方法に変更します。
DateTimeFormatterBuilder	parseStrict()	フォーマッタの残りに対して、解析スタイルを厳密な方法に変更します。
DateTimeFormatter	toFormatter()	デフォルト・ロケールを使用してDateTimeFormatterを作成することにより、このビルダーを完成します。
DateTimeFormatter	toFormatter(Locale locale)	指定されたロケールを使用してDateTimeFormatterを作成することにより、このビルダーを完成します。

クラスjava.lang.Objectで宣言されたメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

コンストラクタの詳細

DateTimeFormatterBuilder

public DateTimeFormatterBuilder()

ビルダーの新しいインスタンスを構築します。

メソッドの詳細

getLocalizedDateTimePattern

public static String getLocalizedDateTimePattern(FormatStyle dateStyle, FormatStyle timeStyle, Chronology chrono, Locale locale)

ロケールおよび暦の日付および時間のスタイルの書式設定パターンを取得します。 ロケールと暦は、要求されたdateStyleまたはtimeStyle、あるいはその両方に対するロケール固有のフォーマットを検索するために使用されます。

ロケールに"rg" (リージョン・オーバーライド) 「Unicode拡張」が含まれている場合、書式設定パターンは、リージョンに適したパターンでオーバーライドされます。

パラメータ:

dateStyle - 日付のFormatStyle、時間専用パターンの場合はnull

timeStyle - 時間のFormatStyle、日付専用パターンの場合はnull

chrono - 暦。null以外

locale - ロケール。null以外

戻り値:

ロケールおよび暦に固有の書式設定パターン

例外:

IllegalArgumentException - dateStyleとtimeStyleの両方がnullの場合

getLocalizedDateTimePattern

public static String getLocalizedDateTimePattern(String requestedTemplate, Chronology chrono, Locale locale)

ロケールおよび時系列について、リクエストされたテンプレートのフォーマット・パターンを返します。 ロケールと時系列を使用して、リクエストされたテンプレートのロケール固有の形式をルックアップします。

ロケールに"rg" (リージョン・オーバーライド) 「Unicode拡張」が含まれている場合、書式設定パターンは、リージョンに適したパターンでオーバーライドされます。

requestedTemplate引数の詳細は、appendLocalized(String)を参照してください。

パラメータ:

requestedTemplate - リクエストされたテンプレート。nullではありません

chrono - 暦。null以外

locale - ロケール。null以外

戻り値:

ロケールおよび暦に固有の書式設定パターン

例外:

IllegalArgumentException - requestedTemplateがappendLocalized(String)で説明されている正規表現構文と一致しない場合。

DateTimeException - requestedTemplateのローカライズされたパターンの一致が使用できない場合

導入されたバージョン:

19

関連項目:

• appendLocalized(String)

parseCaseSensitive

public DateTimeFormatterBuilder parseCaseSensitive()

フォーマッタの残りに対して、解析スタイルを大文字小文字の区別ありに変更します。

解析では、大文字と小文字を区別することも区別しないこともでき、デフォルトでは大文字と小文字が区別されます。 このメソッドを使用すると、解析での大文字と小文字の区別の設定を変更できます。

このメソッドを呼び出すとビルダーの状態が変更され、後に行われるビルダー・メソッドの呼び出しすべてにおいて、大文字と小文字を区別するモードでテキストが解析されるようになります。 反対の設定については、parseCaseInsensitive()を参照してください。 解析での大文字と小文字を区別するメソッドと区別しないメソッドは、ビルダーの任意の点から呼び出すことができるため、解析での大文字と小文字の区別の有無を解析中に複数回切り替えることができます。

デフォルトでは大文字と小文字が区別されるため、前に#parseCaseInsensitiveを呼び出した場合のみ、このメソッドを使用するようにしてください。

戻り値:

this (連鎖のため)。null以外

parseCaseInsensitive

public DateTimeFormatterBuilder parseCaseInsensitive()

フォーマッタの残りに対して、解析スタイルを大文字小文字の区別なしに変更します。

解析では、大文字と小文字を区別することも区別しないこともでき、デフォルトでは大文字と小文字が区別されます。 このメソッドを使用すると、解析での大文字と小文字の区別の設定を変更できます。

このメソッドを呼び出すとビルダーの状態が変更され、後に行われるビルダー・メソッドの呼び出しすべてにおいて、大文字と小文字を区別しないモードでテキストが解析されるようになります。 反対の設定については、parseCaseSensitive()を参照してください。 解析での大文字と小文字を区別するメソッドと区別しないメソッドは、ビルダーの任意の点から呼び出すことができるため、解析での大文字と小文字の区別の有無を解析中に複数回切り替えることができます。

戻り値:

this (連鎖のため)。null以外

parseStrict

public DateTimeFormatterBuilder parseStrict()

フォーマッタの残りに対して、解析スタイルを厳密な方法に変更します。

解析は厳密であっても完全でなくてもかまいません - デフォルトでは厳密です。 これは、テキストおよび記号のスタイルをどの程度柔軟に比較するかを制御します。

このメソッドを使用すると、この時点以降は厳密な解析に変更されます。 デフォルトでは厳密なので、通常これが必要になるのは、前にparseLenient()を呼び出した場合のみです。 最終的に構築されたフォーマッタの終わりまで、あるいはparseLenientが呼び出されるまで、この変更は有効なままになります。

戻り値:

this (連鎖のため)。null以外

parseLenient

public DateTimeFormatterBuilder parseLenient()

フォーマッタの残りに対して、解析スタイルを寛大な方法に変更します。 大文字と小文字の区別は、このメソッドとは別に設定されることに注意してください。

解析は厳密であっても完全でなくてもかまいません - デフォルトでは厳密です。 これは、テキストおよび記号のスタイルをどの程度柔軟に比較するかを制御します。 アプリケーションでこのメソッドを呼び出す場合、通常はparseCaseInsensitive()も呼び出すようにしてください。

このメソッドを使用すると、この時点以降は厳密でない解析に変更されます。 最終的に構築されたフォーマッタの終わりまで、あるいはparseStrictが呼び出されるまで、この変更は有効なままになります。

戻り値:

this (連鎖のため)。null以外

parseDefaulting

public DateTimeFormatterBuilder parseDefaulting(TemporalField field, long value)

解析に使用するフォーマッタに、フィールドのデフォルト値を追加します。

これは、解析された結果にデフォルト値を注入する命令をビルダーに追加します。 これは特に、フォーマッタのオプション部分と組み合わせると役立ちます。

たとえば、年、それに続くオプションの月、さらにオプションの「月の日」を解析するフォーマッタがあるとします。 このようなフォーマッタを使用するには、完全な日付が解析されたのか、年と月、または年だけが解析されたのかを、呼出し元コードで確認する必要があります。 このメソッドを使用すると、月および「月の日」を適切な値(月の最初など)にデフォルト設定できるため、呼出し元コードは常に日付を取得できます。

書式設定時は、このメソッドは何の効果も持ちません。

解析時は、解析の現在の状態が検査されます。 指定されたフィールドがその時点で正常に解析されていないために、値が関連付けられていない場合は、指定された値が解析結果に注入されます。 注入は即時に行われるため、フィールドと値のペアは、フォーマッタの後続の要素すべてで可視になります。 したがって、通常このメソッドはビルダーの終わりで呼び出されます。

パラメータ:

field - 値をデフォルトで設定するフィールド。null以外

value - フィールドにデフォルトで設定する値

戻り値:

this (連鎖のため)。null以外

appendValue

public DateTimeFormatterBuilder appendValue(TemporalField field)

通常の出力スタイルを使用して、日付/時間フィールドの値をフォーマッタに追加します。

フィールドの値は書式設定時に出力されます。 値を取得できない場合は、例外がスローされます。

値は整数値の通常フォーマットに従って出力されます。 負の数値にのみ符号が付けられます。 パディングは行われません。

このパーサーのような可変幅の値のパーサーは、通常は貪欲に動作し、1桁が必要であってもできるだけ多くの桁を受け入れます。 この動作は「隣接値解析」の影響を受ける場合があります。 詳細は、appendValue(java.time.temporal.TemporalField, int)を参照してください。

パラメータ:

field - 追加するフィールド。null以外

戻り値:

this (連鎖のため)。null以外

appendValue

public DateTimeFormatterBuilder appendValue(TemporalField field, int width)

ゼロでパディングする固定幅方式を使用して、日付/時間フィールドの値をフォーマッタに追加します。

フィールドの値は書式設定時に出力されます。 値を取得できない場合は、例外がスローされます。

値は左側にゼロでパディングされます。 値を幅以内で出力できないことを値のサイズが示している場合は、例外がスローされます。 フィールドの値が負の場合は、書式設定時に例外がスローされます。

このメソッドは、「隣接値解析」と呼ばれる特殊な解析手法をサポートしています。 この手法は、可変幅または固定幅の値に固定長の値が1つ以上続いている場合の問題を解決します。 標準パーサーは貪欲なので、固定幅の値のパーサーに必要な、可変幅1に続く桁が、通常では盗まれることになります。

「隣接値解析」を開始するためにアクションは必要ありません。 appendValueの呼出しが行われると、ビルダーは隣接値解析の設定モードに入ります。 同じビルダーに対して直後に行われたメソッド呼出しが固定幅の値に対するものであれば、パーサーは固定幅の値を解析できるように領域を予約します。

たとえば、builder.appendValue(YEAR).appendValue(MONTH_OF_YEAR, 2);について考えてみます。年は1から19桁までの可変幅解析です。 月は2桁の固定幅解析です。 これらは同じビルダーに追加されて一方が他方の直後に続いているため、年のパーサーは月の解析のために2桁を予約します。 したがって、「201106」というテキストは正しく解析され、年が2011、月が6になります。 隣接値解析を使用しないと、6桁すべてが年によって貪欲に解析され、月には何も残らないことになります。

隣接値解析は、パーサー内で任意の種類の値(可変幅でも固定幅でも)の直後に続く、負でない固定幅値の各セットに適用されます。 他のいずれかのappendメソッドを呼び出すと、隣接値解析の設定は終了します。 たとえば、まれにでも隣接値解析の動作を回避する必要がある場合は、単純にappendValueを別のDateTimeFormatterBuilderに追加し、それをこのビルダーに追加してください。

隣接解析がアクティブな場合は、厳密モードと非厳密モードのどちらの解析でも、指定された正確な桁数を照合する必要があります。 また、正符号や負符号は許可されません。

パラメータ:

field - 追加するフィールド。null以外

width - 出力されるフィールドの幅。1から19まで

戻り値:

this (連鎖のため)。null以外

例外:

IllegalArgumentException - 幅が無効な場合

appendValue

public DateTimeFormatterBuilder appendValue(TemporalField field, int minWidth, int maxWidth, SignStyle signStyle)

日付/時間フィールドの値をフォーマッタに追加します。フォーマットは完全に制御できます。

フィールドの値は書式設定時に出力されます。 値を取得できない場合は、例外がスローされます。

このメソッドを使用すると、ゼロでのパディングや正/負符号など、数値の書式設定を完全に制御できます。

このパーサーのような可変幅の値のパーサーは、通常は貪欲に動作し、できるだけ多くの桁を受け入れます。 この動作は「隣接値解析」の影響を受ける場合があります。 詳細は、appendValue(java.time.temporal.TemporalField, int)を参照してください。

厳密解析モードでは、解析される桁数の最小はminWidth、最大はmaxWidthです。 非厳密解析モードでは、解析される桁数の最小は1、最大は19です(隣接値解析によって制限される場合を除く)。

このメソッドは、等しい最小幅と最大幅、および符号スタイルNOT_NEGATIVEで呼び出された場合、appendValue(TemporalField,int)に委譲されます。 この場合、そこに記述されている書式設定および解析の動作が発生します。

パラメータ:

field - 追加するフィールド。null以外

minWidth - 出力されるフィールドの最小フィールド幅。1から19まで

maxWidth - 出力されるフィールドの最大フィールド幅。1から19まで

signStyle - 正/負の出力スタイル。null以外

戻り値:

this (連鎖のため)。null以外

例外:

IllegalArgumentException - 幅が無効な場合

appendValueReduced

public DateTimeFormatterBuilder appendValueReduced(TemporalField field, int width, int maxWidth, int baseValue)

日付/時間フィールドのリデュースされた値をフォーマッタに追加します。

年などのフィールドは暦によって異なるため、ほとんどの場合は、このメソッドの日付バリアントであるappendValueReduced(TemporalField, int, int, ChronoLocalDate)を使用することをお薦めします。 このバリアントは、単純なフィールドや、ISO暦だけを処理する場合に適しています。

書式設定の場合は、書式設定する文字数を決定するためにwidthとmaxWidthが使用されます。 これらが等しい場合、フォーマットは固定幅になります。 フィールドの値がbaseValueにwidth個の文字を使用した範囲内にある場合、リデュースされた値が書式設定されます。それ以外の場合、値はmaxWidthに合わせて切り捨てられます。 もっとも右側の文字が、幅に一致するように左側にゼロでパディングされて出力されます。

厳密解析の場合は、widthからmaxWidthまでによって許可される文字数が解析されます。 非厳密解析の場合、文字数は少なくとも1、かつ10未満でなければなりません。 解析された桁数がwidthと等しく、かつ値が正の場合は、baseValueに同じ最下位文字を使用した値以上となる最初の数値が、フィールドの値として計算されます。それ以外の場合は、解析された値がフィールドの値となります。 これにより、baseValueとwidthの範囲内にある値にはリデュースされた値を入力でき、範囲外の値には絶対値を入力することができます。

たとえば、ベース値が1980で幅が2の場合、有効な値は1980から2079までになります。 解析時は、テキスト"12"は結果として値2012になります。これが、範囲内で最後の2文字が「12」となる値だからです。 これに対し、テキスト"1915"は結果として値1915になります。

パラメータ:

field - 追加するフィールド。null以外

width - 出力および解析されるフィールドのフィールド幅。1から10まで

maxWidth - 出力されるフィールドの最大フィールド幅。1から10まで

baseValue - 有効な値の範囲のベース値

戻り値:

this (連鎖のため)。null以外

例外:

IllegalArgumentException - 幅またはベース値が無効な場合

appendValueReduced

public DateTimeFormatterBuilder appendValueReduced(TemporalField field, int width, int maxWidth, ChronoLocalDate baseDate)

日付/時間フィールドのリデュースされた値をフォーマッタに追加します。

通常、これは2桁の年の書式設定および解析に使用されます。

ベース日付は、解析時に完全な値を計算するために使用されます。 たとえば、ベース日付が1950-01-01の場合、2桁の年の解析で解析された値は、1950-01-01から2049-12-31の範囲になります。 日付から年だけが抽出されるため、ベース日付が1950-08-25の場合も、1950-01-01から2049-12-31の範囲に解析されます。 解析された値が標準のISOの年に揃わない、「暦週の基準年」などのフィールドや他の暦体系をサポートする場合に、この動作が必要です。

詳細な動作は次のとおりです。 完全なフィールド・セットを解析し、有効な暦を判定します。暦が複数回出現する場合は、最後のものを使用します。 次に、ベース日付を有効な暦に変換します。 次に、指定されたフィールドを暦固有のベース日付から抽出し、それを使用してbaseValueを判定します。これは下記で使用されます。

書式設定の場合は、書式設定する文字数を決定するためにwidthとmaxWidthが使用されます。 これらが等しい場合、フォーマットは固定幅になります。 フィールドの値がbaseValueにwidth個の文字を使用した範囲内にある場合、リデュースされた値が書式設定されます。それ以外の場合、値はmaxWidthに合わせて切り捨てられます。 もっとも右側の文字が、幅に一致するように左側にゼロでパディングされて出力されます。

厳密解析の場合は、widthからmaxWidthまでによって許可される文字数が解析されます。 非厳密解析の場合、文字数は少なくとも1、かつ10未満でなければなりません。 解析された桁数がwidthと等しく、かつ値が正の場合は、baseValueに同じ最下位文字を使用した値以上となる最初の数値が、フィールドの値として計算されます。それ以外の場合は、解析された値がフィールドの値となります。 これにより、baseValueとwidthの範囲内にある値にはリデュースされた値を入力でき、範囲外の値には絶対値を入力することができます。

たとえば、ベース値が1980で幅が2の場合、有効な値は1980から2079までになります。 解析時は、テキスト"12"は結果として値2012になります。これが、範囲内で最後の2文字が「12」となる値だからです。 これに対し、テキスト"1915"は結果として値1915になります。

パラメータ:

field - 追加するフィールド。null以外

width - 出力および解析されるフィールドのフィールド幅。1から10まで

maxWidth - 出力されるフィールドの最大フィールド幅。1から10まで

baseDate - 解析された暦で有効な値の範囲のベース値を計算するために使用されるベース日付。null以外

戻り値:

this (連鎖のため)。null以外

例外:

IllegalArgumentException - 幅またはベース値が無効な場合

appendFraction

public DateTimeFormatterBuilder appendFraction(TemporalField field, int minWidth, int maxWidth, boolean decimalPoint)

日付/時間フィールドの小数値をフォーマッタに追加します。

フィールドの小数値は、前にある小数点を含めて出力されます。 その前にある値は出力されません。 たとえば、秒の値が15の場合、これは.25と出力されます。

出力される小数部の幅は制御できます。 最小幅をゼロに設定すると、出力は生成されません。 出力される小数部は、最小幅と最大幅の間で最小限必要な幅になり、末尾のゼロは省略されます。 最大幅のため、丸めは行われず、桁が単純に切り捨てられます。

厳密モードでの解析時、解析される桁数は最小幅と最大幅の間になければなりません。 厳密モードでは、最小幅と最大幅が等しく、小数点がない場合、パーサーは隣接する値の解析に関与します。appendValue(java.time.temporal.TemporalField, int)を参照してください。 非厳密モードでの解析時、最小幅は0、最大幅は9と見なされます。

値を取得できない場合は、例外がスローされます。 値が負の場合は、例外がスローされます。 フィールドが有効な値の固定セットを持っていない場合は、例外がスローされます。 印刷する日時内のフィールド値が有効な値の範囲外である場合、例外がスローされます。

パラメータ:

field - 追加するフィールド。null以外

minWidth - 小数点を除く、フィールドの最小幅。0から9まで

maxWidth - 小数点を除く、フィールドの最大幅。1から9まで

decimalPoint - ローカライズされた小数点記号を出力するかどうか

戻り値:

this (連鎖のため)。null以外

例外:

IllegalArgumentException - フィールドが有効な値の可変セットを持っているか、どちらかの幅が無効な場合

appendText

public DateTimeFormatterBuilder appendText(TemporalField field)

フルテキスト・スタイルを使用して、日付/時間フィールドのテキストをフォーマッタに追加します。

フィールドのテキストは書式設定時に出力されます。 値はフィールドの有効範囲内になければなりません。 値を取得できない場合は、例外がスローされます。 フィールドがテキスト表現を持っていない場合は、数値が使用されます。

値は整数値の通常フォーマットに従って出力されます。 負の数値にのみ符号が付けられます。 パディングは行われません。

パラメータ:

field - 追加するフィールド。null以外

戻り値:

this (連鎖のため)。null以外

appendText

public DateTimeFormatterBuilder appendText(TemporalField field, TextStyle textStyle)

日付/時間フィールドのテキストをフォーマッタに追加します。

フィールドのテキストは書式設定時に出力されます。 値はフィールドの有効範囲内になければなりません。 値を取得できない場合は、例外がスローされます。 フィールドがテキスト表現を持っていない場合は、数値が使用されます。

値は整数値の通常フォーマットに従って出力されます。 負の数値にのみ符号が付けられます。 パディングは行われません。

パラメータ:

field - 追加するフィールド。null以外

textStyle - 使用するテキスト・スタイル。null以外

戻り値:

this (連鎖のため)。null以外

appendText

public DateTimeFormatterBuilder appendText(TemporalField field, Map<Long,String> textLookup)

指定されたマップを使用してテキストを提供することにより、日付/時間フィールドのテキストをフォーマッタに追加します。

標準のテキスト出力メソッドは、JDKのローカライズされたテキストを使用します。 このメソッドを使用すると、そのテキストを直接指定できます。 指定したマップはビルダーで検証されず、書式設定または解析が可能であることが保証されないため、無効なマップを指定すると後で使用中にエラーがスローされることがあります。

テキストのマップを指定することで、書式設定と解析にかなり柔軟性を持たせることができます。 たとえば、レガシー・アプリケーションで、年の月として「JNY」、「FBY」、「MCH」などを使用している場合があります。これらは、ローカライズされた月の名前を表す標準のテキスト・セットとは一致しません。 このメソッドを使用すると、各値とテキストの間の接続を定義するマップを作成できます。

 Map<Long, String> map = new HashMap<>();
 map.put(1L, "JNY");
 map.put(2L, "FBY");
 map.put(3L, "MCH");
 ...
 builder.appendText(MONTH_OF_YEAR, map);
 

値を出力するときに、「1st」、「2nd」、「3rd」などの接尾辞を付加したり、「I」、「II」、「III」、「IV」などのローマ数字で表したりする使用方法もあります。

書式設定時には、値が取得され、有効な範囲内にあるかどうかが確認されます。 値を表すテキストが使用不可の場合、値は数値として出力されます。 解析時には、テキスト値と数値のマップがパーサーによって照合されます。

パラメータ:

field - 追加するフィールド。null以外

textLookup - 値からテキストへのマップ

戻り値:

this (連鎖のため)。null以外

appendInstant

public DateTimeFormatterBuilder appendInstant()

ISO-8601を使用してインスタントをフォーマッタに追加します。小数部は3桁ずつに書式設定します。

インスタントには固定の出力フォーマットがあります。 これらは、UTCゾーン・オフセットで日付/時間に変換され、標準のISO-8601フォーマットを使用して書式設定されます。 このメソッドでは、nano-of-secondをフォーマットすると、必要に応じて0桁、3桁、6桁または9桁が出力されます。 ローカライズされた10進スタイルは使用されません。

インスタントは、INSTANT_SECONDSとオプションでNANO_OF_SECONDを使用して取得されます。 INSTANT_SECONDSの値は、LocalDateTimeの最大範囲外になることがあります。

リゾルバ・スタイルはインスタントの解析には影響しません。 1日の終わりの時間「24:00」は、次の日の開始の深夜零時として処理されます。 うるう秒時間「23:59:59」はある程度まで処理されます。詳細は、DateTimeFormatter.parsedLeapSecond()を参照してください。

書式設定時、インスタントのサフィクスは常に'Z'で示され、UTCが示されます。 解析時には、appendOffsetId()の動作を使用してオフセットを解析し、必要に応じてインスタントをUTCに変換します。

このメソッドに代わる方法は、インスタントを単一のエポック秒値として書式設定/解析することです。 これはappendValue(INSTANT_SECONDS)を使用して実現されます。

戻り値:

this (連鎖のため)。null以外

appendInstant

public DateTimeFormatterBuilder appendInstant(int fractionalDigits)

ISO-8601を使用してインスタントをフォーマッタに追加します。小数部の桁数は制御できます。

インスタントの出力フォーマットは固定ですが、このメソッドでは小数部の桁を多少制御できます。 これらは、UTCゾーン・オフセットで日付/時間に変換され、標準のISO-8601フォーマットを使用して出力されます。 ローカライズされた10進スタイルは使用されません。

fractionalDigitsパラメータを使用すると、小数秒の出力を制御できます。 ゼロを指定すると、小数部の桁は出力されません。 1から9を指定すると、出力される桁数が増え、必要に応じて右側にゼロでパディングされます。 特殊な値-1を使用すると、末尾のゼロをなくすように必要な数だけ桁が出力されます。

厳密モードでの解析時には、解析される桁数は小数部の桁と一致する必要があります。 非厳密モードでの解析時には、0から9までの任意の小数部桁数が受け入れられます。

インスタントは、INSTANT_SECONDSとオプションでNANO_OF_SECONDを使用して取得されます。 INSTANT_SECONDSの値は、LocalDateTimeの最大範囲外になることがあります。

リゾルバ・スタイルはインスタントの解析には影響しません。 1日の終わりの時間「24:00」は、次の日の開始の深夜零時として処理されます。 うるう秒時間「23:59:60」はある程度まで処理されます。詳細は、DateTimeFormatter.parsedLeapSecond()を参照してください。

このメソッドに代わる方法は、インスタントを単一のエポック秒値として書式設定/解析することです。 これはappendValue(INSTANT_SECONDS)を使用して実現されます。

パラメータ:

fractionalDigits - 小数部の桁数。0から9まで。または、必要なだけの桁数として-1を使用します

戻り値:

this (連鎖のため)。null以外

例外:

IllegalArgumentException - 小数点以下の桁数が無効な場合

appendOffsetId

public DateTimeFormatterBuilder appendOffsetId()

「+01:00」などのゾーン・オフセットをフォーマッタに追加します。

これは、オフセットIDを書式設定/解析する命令をビルダーに追加します。 これはappendOffset("+HH:mm:ss", "Z")を呼び出すのと同じです。 書式設定および解析の詳細は、appendOffset(String, String)を参照してください。

戻り値:

this (連鎖のため)。null以外

appendOffset

public DateTimeFormatterBuilder appendOffset(String pattern, String noOffsetText)

「+01:00」などのゾーン・オフセットをフォーマッタに追加します。

これは、オフセットIDを書式設定/解析する命令をビルダーに追加します。

書式設定時には、時間的オブジェクトをTemporalQueries.offset()で照会する場合と同等のメカニズムを使用して、オフセットが取得されます。 これは、下記で定義されているフォーマットを使用して出力されます。 オフセットを取得できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。

厳密モードで解析する場合、入力には必須要素とオプションの要素が指定のパターンで定義されている必要があります。 オフセットを解析できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。

一時モードで解析する場合、時間のみが必須です - 分と秒はオプションです。 指定されたパターンにコロンが含まれている場合は、コロンが必要です。 指定されたパターンが"+HH"の場合、コロンが存在するかどうかは、時間桁の後の文字がコロンかどうかによって決まります。 オフセットを解析できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。

オフセットのフォーマットはパターンによって制御されます。パターンは次のいずれかでなければなりません。

• +HH - 分と秒は無視し、時のみ
• +HHmm - 秒は無視し、時と分(ゼロでない場合)。コロンなし
• +HH:mm - 秒は無視し、時と分(ゼロでない場合)。コロンあり
• +HHMM - 秒は無視し、時と分。コロンなし
• +HH:MM - 秒は無視し、時と分。コロンあり
• +HHMMss - 時、分、および秒(ゼロでない場合)。コロンなし
• +HH:MM:ss - 時、分、および秒(ゼロでない場合)。コロンあり
• +HHMMSS - 時、分、および秒。コロンなし
• +HH:MM:SS - 時、分、および秒。コロンあり
• +HHmmss - 時(0以外の場合は分、0以外の場合は分、0以外の場合は秒)、コロンなし
• +HH:mm:ss - 時間。0以外の場合は分、0以外の場合は分、0以外の場合は秒、コロン付き
• +H - 時のみ、分と秒を無視
• +Hmm - 時間、0以外の場合は分、2番目を無視、コロンなし
• +H:mm - 時、0以外の場合は分、2番目を無視、コロン付き
• +HMM - 時間と分、秒を無視、コロンなし
• +H:MM - 時間と分、秒を無視、コロン付き
• +HMMss - 時と分、ゼロ以外の場合は秒、コロンなし
• +H:MM:ss - 時と分、ゼロ以外の場合は秒、コロン付き
• +HMMSS - 時間、分、秒、コロンなし
• +H:MM:SS - 時間、分、秒、コロン付き
• +Hmmss - 時(0以外の場合は分、0以外の場合は分、0以外の場合は秒)、コロンなし
• +H:mm:ss - 時間。0以外の場合は分、0以外の場合は分、0以外の場合は秒、コロン付き

"HH"を含むパターンは、必要に応じてゼロ埋めの2桁の時間をフォーマットおよび解析します。 "H"を含むパターンは、ゼロ埋込みなしで書式設定し、1桁または2桁のいずれかを解析します。 簡易モードでは、パーサーは最短一致になり、可能な最大桁数を解析します。 「オフセットなし」テキストは、出力されるオフセット・フィールドの合計量がゼロのときに、どのようなテキストを出力するかを制御します。 たとえば、「Z」、「+00:00」、「UTC」、「GMT」などの値です。 UTCの解析には3つのフォーマットが受け入れられます。「オフセットなし」テキストと、パターンで定義されている正および負のゼロです。

パラメータ:

pattern - 使用するパターン。null以外

noOffsetText - オフセットがゼロのときに使用するテキスト。null以外

戻り値:

this (連鎖のため)。null以外

例外:

IllegalArgumentException - パターンが無効な場合

appendLocalizedOffset

public DateTimeFormatterBuilder appendLocalizedOffset(TextStyle style)

「GMT+01:00」などのローカライズされたゾーン・オフセットをフォーマッタに追加します。

これは、ローカライズされたゾーン・オフセットをビルダーに追加します。ローカライズされたオフセットのフォーマットは、このメソッドに指定されたstyleによって制御されます。

• full - ローカライズされたオフセット・テキスト(「GMT」など)、2桁の時と分フィールド、オプションの秒フィールド(ゼロでない場合)、およびコロンを使用して書式設定します。
• short - ローカライズされたオフセット・テキスト(「GMT」など)、先頭のゼロを除く時、オプションの2桁の分と秒(ゼロでない場合)、およびコロンを使用して書式設定します。

書式設定時には、時間的オブジェクトをTemporalQueries.offset()で照会する場合と同等のメカニズムを使用して、オフセットが取得されます。 オフセットを取得できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。

解析時には、上記で定義されているフォーマットを使用してオフセットが解析されます。 オフセットを解析できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。

パラメータ:

style - 使用するフォーマット・スタイル。null以外

戻り値:

this (連鎖のため)。null以外

例外:

IllegalArgumentException - スタイルがfullでもshortでもない場合

appendZoneId

public DateTimeFormatterBuilder appendZoneId()

「ヨーロッパ/パリ」や「+02:00」などのタイムゾーンIDをフォーマッタに追加します。

これは、ゾーンIDを書式設定/解析する命令をビルダーに追加します。 ゾーンIDは、ZonedDateTimeに適した厳密な方法で取得されます。 これに対し、OffsetDateTimeには、このメソッドでの使用に適したゾーンIDはありません。appendZoneOrOffsetId()を参照してください。

書式設定時には、時間的オブジェクトをTemporalQueries.zoneId()で照会する場合と同等のメカニズムを使用して、ゾーンが取得されます。 これは、ZoneId.getId()の結果を使用して出力されます。 ゾーンを取得できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。

解析時には、テキストは既存のゾーンまたはオフセットと一致する必要があります。 ゾーンIDには、オフセット・ベース(「+01:30」など)と地域ベース(「Europe/London」など)の2種類があります。 これらは異なる方法で解析されます。 解析が「+」、「-」、「UT」、「UTC」、または「GMT」で始まる場合、パーサーはオフセット・ベースのゾーンを想定するため、地域ベースのゾーンは照合しません。 「+02:30」などのオフセットIDは、解析の最初に現れるか、接頭辞「UT」、「UTC」、または「GMT」が付いている場合があります。 オフセットIDの解析は、appendOffset(String, String)に引数「HH:MM:ss」およびオフセットなし文字列「0」を使用することと等価です。 解析が「UT」、「UTC」、または「GMT」で始まり、それに続くオフセットIDをパーサーが照合できない場合は、ZoneOffset.UTCが選択されます。 その他の場合はすべて、既知の地域ベース・ゾーンのリストを使用して、もっとも長く一致するものが検索されます。 一致するものが見つからない場合、解析が「Z」で始まるときは、ZoneOffset.UTCが選択されます。 パーサーでは、大文字と小文字を区別する設定が使用されます。

たとえば、次のように解析されます。

   "Europe/London"           -- ZoneId.of("Europe/London")
   "Z"                       -- ZoneOffset.UTC
   "UT"                      -- ZoneId.of("UT")
   "UTC"                     -- ZoneId.of("UTC")
   "GMT"                     -- ZoneId.of("GMT")
   "+01:30"                  -- ZoneOffset.of("+01:30")
   "UT+01:30"                -- ZoneOffset.of("+01:30")
   "UTC+01:30"               -- ZoneOffset.of("+01:30")
   "GMT+01:30"               -- ZoneOffset.of("+01:30")
 

戻り値:

this (連鎖のため)。null以外

関連項目:

• appendZoneRegionId()

appendZoneRegionId

public DateTimeFormatterBuilder appendZoneRegionId()

「ヨーロッパ/パリ」などのタイムゾーン地域IDをフォーマッタに追加します。ゾーンIDがZoneOffsetの場合は拒否します。

これは、ゾーンIDが地域ベースのIDである場合のみ、それを書式設定/解析する命令をビルダーに追加します。

書式設定時には、時間的オブジェクトをTemporalQueries.zoneId()で照会する場合と同等のメカニズムを使用して、ゾーンが取得されます。 ゾーンがZoneOffsetであるかゾーンを取得できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。 ゾーンがオフセットでない場合は、ZoneId.getId()からのゾーンIDを使用してゾーンが出力されます。

解析時には、テキストは既存のゾーンまたはオフセットと一致する必要があります。 ゾーンIDには、オフセット・ベース(「+01:30」など)と地域ベース(「Europe/London」など)の2種類があります。 これらは異なる方法で解析されます。 解析が「+」、「-」、「UT」、「UTC」、または「GMT」で始まる場合、パーサーはオフセット・ベースのゾーンを想定するため、地域ベースのゾーンは照合しません。 「+02:30」などのオフセットIDは、解析の最初に現れるか、接頭辞「UT」、「UTC」、または「GMT」が付いている場合があります。 オフセットIDの解析は、appendOffset(String, String)に引数「HH:MM:ss」およびオフセットなし文字列「0」を使用することと等価です。 解析が「UT」、「UTC」、または「GMT」で始まり、それに続くオフセットIDをパーサーが照合できない場合は、ZoneOffset.UTCが選択されます。 その他の場合はすべて、既知の地域ベース・ゾーンのリストを使用して、もっとも長く一致するものが検索されます。 一致するものが見つからない場合、解析が「Z」で始まるときは、ZoneOffset.UTCが選択されます。 パーサーでは、大文字と小文字を区別する設定が使用されます。

たとえば、次のように解析されます。

   "Europe/London"           -- ZoneId.of("Europe/London")
   "Z"                       -- ZoneOffset.UTC
   "UT"                      -- ZoneId.of("UT")
   "UTC"                     -- ZoneId.of("UTC")
   "GMT"                     -- ZoneId.of("GMT")
   "+01:30"                  -- ZoneOffset.of("+01:30")
   "UT+01:30"                -- ZoneOffset.of("+01:30")
   "UTC+01:30"               -- ZoneOffset.of("+01:30")
   "GMT+01:30"               -- ZoneOffset.of("+01:30")
 

このメソッドは、ゾーンを取得するメカニズムを除けば、appendZoneId()と同一です。 また、解析ではオフセットが受け入れられますが、書式設定でオフセットが生成されることはありません。

戻り値:

this (連鎖のため)。null以外

関連項目:

• appendZoneId()

appendZoneOrOffsetId

public DateTimeFormatterBuilder appendZoneOrOffsetId()

「ヨーロッパ/パリ」や「+02:00」などのタイムゾーンIDをフォーマッタに追加します。利用可能な最良のゾーンIDを使用します。

これは、利用可能な最良のゾーンIDまたはオフセットIDを書式設定/解析する命令をビルダーに追加します。 ゾーンIDは厳密でない方法で取得されます。つまり、まずZonedDateTimeのような真のゾーンIDの検索が試みられ、次にOffsetDateTimeのようなオフセットの検索が検索が試みられます。

書式設定時には、時間的オブジェクトをTemporalQueries.zone()で照会する場合と同等のメカニズムを使用して、ゾーンが取得されます。 これは、ZoneId.getId()の結果を使用して出力されます。 ゾーンを取得できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。

解析時には、テキストは既存のゾーンまたはオフセットと一致する必要があります。 ゾーンIDには、オフセット・ベース(「+01:30」など)と地域ベース(「Europe/London」など)の2種類があります。 これらは異なる方法で解析されます。 解析が「+」、「-」、「UT」、「UTC」、または「GMT」で始まる場合、パーサーはオフセット・ベースのゾーンを想定するため、地域ベースのゾーンは照合しません。 「+02:30」などのオフセットIDは、解析の最初に現れるか、接頭辞「UT」、「UTC」、または「GMT」が付いている場合があります。 オフセットIDの解析は、appendOffset(String, String)に引数「HH:MM:ss」およびオフセットなし文字列「0」を使用することと等価です。 解析が「UT」、「UTC」、または「GMT」で始まり、それに続くオフセットIDをパーサーが照合できない場合は、ZoneOffset.UTCが選択されます。 その他の場合はすべて、既知の地域ベース・ゾーンのリストを使用して、もっとも長く一致するものが検索されます。 一致するものが見つからない場合、解析が「Z」で始まるときは、ZoneOffset.UTCが選択されます。 パーサーでは、大文字と小文字を区別する設定が使用されます。

たとえば、次のように解析されます。

   "Europe/London"           -- ZoneId.of("Europe/London")
   "Z"                       -- ZoneOffset.UTC
   "UT"                      -- ZoneId.of("UT")
   "UTC"                     -- ZoneId.of("UTC")
   "GMT"                     -- ZoneId.of("GMT")
   "+01:30"                  -- ZoneOffset.of("+01:30")
   "UT+01:30"                -- ZoneOffset.of("UT+01:30")
   "UTC+01:30"               -- ZoneOffset.of("UTC+01:30")
   "GMT+01:30"               -- ZoneOffset.of("GMT+01:30")
 

このメソッドは、ゾーンを取得するメカニズムを除けば、appendZoneId()と同一です。

戻り値:

this (連鎖のため)。null以外

関連項目:

• appendZoneId()

appendZoneText

public DateTimeFormatterBuilder appendZoneText(TextStyle textStyle)

「英国夏時間」などのタイムゾーン名をフォーマッタに追加します。

これは、テキストでのゾーン名を書式設定/解析する命令をビルダーに追加します。

書式設定時には、時間的オブジェクトをTemporalQueries.zoneId()で照会する場合と同等のメカニズムを使用して、ゾーンが取得されます。 ゾーンがZoneOffsetの場合は、ZoneOffset.getId()の結果を使用して出力されます。 ゾーンがオフセットでない場合は、DateTimeFormatterに設定されているロケールに対してテキストでの名前が検索されます。 印刷される時間的オブジェクトがインスタントを表す場合、またはそれが夏時間ギャップまたは重複しないローカル日時である場合、テキストは必要に応じて夏時間または冬時間のテキストになります。 テキストの検索で適切な結果が見つからない場合は、IDが出力されます。 ゾーンを取得できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。

解析時には、テキストでのゾーン名、ゾーンID、またはオフセットが受け入れられます。 テキストでのゾーン名には、一意でないものが多くあります。たとえば、CSTは「Central Standard Time (中部標準時)」と「China Standard Time (中国標準時)」の両方に使用されます。 この状況では、フォーマッタのlocaleから得られる地域情報と、その地域の標準ゾーンID (たとえば、America Easternゾーンの場合はAmerica/New_York)により、ゾーンIDが決定されます。 appendZoneText(TextStyle, Set)を使用すると、この状況で優先するZoneIdのセットを指定できます。

パラメータ:

textStyle - 使用するテキスト・スタイル。null以外

戻り値:

this (連鎖のため)。null以外

appendZoneText

public DateTimeFormatterBuilder appendZoneText(TextStyle textStyle, Set<ZoneId> preferredZones)

「英国夏時間」などのタイムゾーン名をフォーマッタに追加します。

これは、テキストでのゾーン名を書式設定/解析する命令をビルダーに追加します。

書式設定時には、時間的オブジェクトをTemporalQueries.zoneId()で照会する場合と同等のメカニズムを使用して、ゾーンが取得されます。 ゾーンがZoneOffsetの場合は、ZoneOffset.getId()の結果を使用して出力されます。 ゾーンがオフセットでない場合は、DateTimeFormatterに設定されているロケールに対してテキストでの名前が検索されます。 印刷する時間的オブジェクトがインスタントを表す場合、またはそれがサマー・タイムのギャップまたはオー・バー・ラップにないローカルの日時である場合、テキストは必要に応じて夏時間または冬時間のテキストになります。 テキストの検索で適切な結果が見つからない場合は、IDが出力されます。 ゾーンを取得できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。

解析時には、テキストでのゾーン名、ゾーンID、またはオフセットが受け入れられます。 テキストでのゾーン名には、一意でないものが多くあります。たとえば、CSTは「Central Standard Time (中部標準時)」と「China Standard Time (中国標準時)」の両方に使用されます。 この状況では、フォーマッタのlocaleから得られる地域情報と、その地域の標準ゾーンID (たとえば、America Easternゾーンの場合はAmerica/New_York)により、ゾーンIDが決定されます。 このメソッドでは、解析で優先するZoneIdのセットを指定することもできます。 解析されたテキストでのゾーン名が一意でない場合は、一致する優先ゾーンIDが使用されます。

ゾーンを解析できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。

パラメータ:

textStyle - 使用するテキスト・スタイル。null以外

preferredZones - 優先ゾーンIDのセット。null以外

戻り値:

this (連鎖のため)。null以外

appendGenericZoneText

public DateTimeFormatterBuilder appendGenericZoneText(TextStyle textStyle)

「太平洋時間」などの一般的なタイムゾーン名をフォーマッタに追加します。

これにより、ゾーンの汎用テキスト名をビルダーに書式設定/解析する命令が追加されます。 汎用名は、夏時間の変更を無視して、1年を通して同じです。 たとえば、'Pacific Time'は一般的な名前ですが、'Pacific Standard Time'および'Pacific Daylight Time'は特定の名前です。appendZoneText(TextStyle)を参照してください。

書式設定時には、時間的オブジェクトをTemporalQueries.zoneId()で照会する場合と同等のメカニズムを使用して、ゾーンが取得されます。 ゾーンがZoneOffsetの場合は、ZoneOffset.getId()の結果を使用して出力されます。 ゾーンがオフセットでない場合は、DateTimeFormatterに設定されているロケールに対してテキストでの名前が検索されます。 テキストの検索で適切な結果が見つからない場合は、IDが出力されます。 ゾーンを取得できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。

解析時には、テキストでのゾーン名、ゾーンID、またはオフセットが受け入れられます。 テキストでのゾーン名には、一意でないものが多くあります。たとえば、CSTは「Central Standard Time (中部標準時)」と「China Standard Time (中国標準時)」の両方に使用されます。 この状況では、フォーマッタのlocaleから得られる地域情報と、その地域の標準ゾーンID (たとえば、America Easternゾーンの場合はAmerica/New_York)により、ゾーンIDが決定されます。 この状況では、appendGenericZoneText(TextStyle, Set)を使用して一連の優先ZoneIdを指定できます。

パラメータ:

textStyle - 使用するテキスト・スタイル。null以外

戻り値:

this (連鎖のため)。null以外

導入されたバージョン:

9

appendGenericZoneText

public DateTimeFormatterBuilder appendGenericZoneText(TextStyle textStyle, Set<ZoneId> preferredZones)

「太平洋時間」などの一般的なタイムゾーン名をフォーマッタに追加します。

これにより、ゾーンの汎用テキスト名をビルダーに書式設定/解析する命令が追加されます。 汎用名は、夏時間の変更を無視して、1年を通して同じです。 たとえば、'Pacific Time'は一般的な名前ですが、'Pacific Standard Time'および'Pacific Daylight Time'は特定の名前です。appendZoneText(TextStyle)を参照してください。

このメソッドでは、解析で優先するZoneIdのセットを指定することもできます。 解析されたテキストでのゾーン名が一意でない場合は、一致する優先ゾーンIDが使用されます。

書式設定および解析の詳細は、appendGenericZoneText(TextStyle)を参照してください。

パラメータ:

textStyle - 使用するテキスト・スタイル。null以外

preferredZones - 優先ゾーンIDのセット。null以外

戻り値:

this (連鎖のため)。null以外

導入されたバージョン:

9

appendChronologyId

public DateTimeFormatterBuilder appendChronologyId()

「ISO」や「ThaiBuddhist」などの暦IDをフォーマッタに追加します。

これは、暦IDを書式設定/解析する命令をビルダーに追加します。

書式設定時には、時間的オブジェクトをTemporalQueries.chronology()で照会する場合と同等のメカニズムを使用して、暦が取得されます。 これは、Chronology.getId()の結果を使用して出力されます。 暦を取得できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。

解析時には、暦が解析され、それがChronology.getAvailableChronologies()の暦のいずれかと一致する必要があります。 暦を解析できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。 パーサーでは、大文字と小文字を区別する設定が使用されます。

戻り値:

this (連鎖のため)。null以外

appendChronologyText

public DateTimeFormatterBuilder appendChronologyText(TextStyle textStyle)

暦名をフォーマッタに追加します。

暦体系の名前は書式設定時に出力されます。 暦を取得できない場合は、例外がスローされます。

パラメータ:

textStyle - 使用するテキスト・スタイル。null以外

戻り値:

this (連鎖のため)。null以外

appendLocalized

public DateTimeFormatterBuilder appendLocalized(FormatStyle dateStyle, FormatStyle timeStyle)

ローカライズされた日付/時間パターンをフォーマッタに追加します。

これは、日付、時間、または日付/時間の組合わせを出力するのに適した、ローカライズされたセクションをビルダーに追加します。 ローカライズされたセクションのフォーマットは、4つの項目に基づいて遅延検索されます。

• このメソッドに指定されたdateStyle
• このメソッドに指定されたtimeStyle
• DateTimeFormatterのLocale
• Chronology。利用可能な最良のものが選択されます

書式設定時には、書式設定される時間的オブジェクトから暦が取得されます。これはDateTimeFormatter.withChronology(Chronology)によってオーバーライドされている場合があります。 FULLおよびLONGスタイルには、通常、タイムゾーンが必要です。 これらのスタイルを使用して書式設定する場合、ZonedDateTimeまたはDateTimeFormatter.withZone(java.time.ZoneId)を使用して、ZoneIdが使用可能である必要があります。

解析時には、すでに暦が解析されていれば、それが使用されます。 それ以外の場合は、DateTimeFormatter.withChronology(Chronology)からのデフォルトが使用され、フォールバックとしてIsoChronologyが使用されます。

このメソッドは、DateFormat.getDateTimeInstance(int, int)といったDateFormatのメソッドに似た機能を提供します。

パラメータ:

dateStyle - 使用する日付スタイル。nullは日付が不要であることを示します

timeStyle - 使用する時間スタイル。nullは時間が不要であることを示します

戻り値:

this (連鎖のため)。null以外

例外:

IllegalArgumentException - 日付スタイルと時間スタイルの両方がnullの場合

appendLocalized

public DateTimeFormatterBuilder appendLocalized(String requestedTemplate)

リクエストされたテンプレートを使用して、ローカライズされたパターンをフォーマッタに追加します。

これは、日付、時間、または日付/時間の組合わせを出力するのに適した、ローカライズされたセクションをビルダーに追加します。 ローカライズされたセクションの形式は、次の3つのアイテムに基づいて遅延検索されます:

• このメソッドに指定されたrequestedTemplate
• DateTimeFormatterのLocale
• オーバーライドされないかぎり、DateTimeFormatterのChronology

書式設定時には、書式設定される時間的オブジェクトから暦が取得されます。これはDateTimeFormatter.withChronology(Chronology)によってオーバーライドされている場合があります。

解析時には、すでに暦が解析されていれば、それが使用されます。 それ以外の場合は、DateTimeFormatter.withChronology(Chronology)からのデフォルトが使用され、フォールバックとしてIsoChronologyが使用されます。

リクエストされたテンプレートは、日付または時間単位の最大値から最小値までの正規順の一連の典型的なパターン記号であり、次の正規表現で表すことができます:

     "G{0,5}" +        // Era
     "y*" +            // Year
     "Q{0,5}" +        // Quarter
     "M{0,5}" +        // Month
     "w*" +            // Week of Week Based Year
     "E{0,5}" +        // Day of Week
     "d{0,2}" +        // Day of Month
     "B{0,5}" +        // Period/AmPm of Day
     "[hHjC]{0,2}" +   // Hour of Day/AmPm (refer to LDML for 'j' and 'C')
     "m{0,2}" +        // Minute of Hour
     "s{0,2}" +        // Second of Minute
     "[vz]{0,4}"       // Zone

すべてのパターン記号はオプションであり、各パターン記号はフィールドを表します。たとえば、'M'は月フィールドを表します。 パターン記号の数は、"number"や"text"のように、「書式設定および解析のパターン」セクションと同じ表現に従います。 リクエストされたテンプレートのその他のパターン記号が無効です。

リクエストされたテンプレートを使用可能なローカライズされた形式の最も近い形式にマッピングするには、「Unicode LDMLの指定」で定義します。 たとえば、リクエストされたテンプレートyMMMから作成されたフォーマッタは、US localeの日付'2020-06-16'を'2020年6月'にフォーマットします。

パラメータ:

requestedTemplate - 使用するようにリクエストされたテンプレート (null以外)

戻り値:

this (連鎖のため)。null以外

例外:

IllegalArgumentException - requestedTemplateが無効な場合

導入されたバージョン:

19

外部仕様

• Unicodeロケール・データ・マークアップ言語(LDML)

関連項目:

• appendPattern(String)

appendLiteral

public DateTimeFormatterBuilder appendLiteral(char literal)

文字リテラルをフォーマッタに追加します。

この文字は書式設定時に出力されます。

パラメータ:

literal - 追加するリテラル。null以外

戻り値:

this (連鎖のため)。null以外

appendLiteral

public DateTimeFormatterBuilder appendLiteral(String literal)

文字列リテラルをフォーマッタに追加します。

この文字列は書式設定時に出力されます。

リテラルが空の場合、フォーマッタには何も追加されません。

パラメータ:

literal - 追加するリテラル。null以外

戻り値:

this (連鎖のため)。null以外

appendDayPeriodText

public DateTimeFormatterBuilder appendDayPeriodText(TextStyle style)

日期間テキストをフォーマッタに追加します。

これにより、日期間のテキスト名を書式設定/解析する命令がビルダーに追加されます。 日の期間はLDML "日期間"要素で定義されます。

書式設定中に、日の期間がHOUR_OF_DAYから取得され、オプションでMINUTE_OF_HOUR(存在する場合)から取得されます。 LDMLで定義された日期間タイプ("morning1"など)にマップされ、その後テキストに変換されます。 日期間タイプとその換算の両方へのマッピングは、フォーマッタのロケールによって異なります。

解析中、テキストは最初に日期間タイプに解析されます。 次に、解析された日期間が他のフィールドと組み合され、解決フェーズでLocalTimeが作成されます。 HOUR_OF_AMPMフィールドが存在する場合、MINUTE_OF_HOUR値を考慮してHOUR_OF_DAYを実行するために、HOUR_OF_AMPMフィールドが日期間と組み合されます。 HOUR_OF_DAYが存在する場合は、任意のMINUTE_OF_HOUR値を考慮して日期間に対して検証されます。 HOUR_OF_DAY, MINUTE_OF_HOUR, SECOND_OF_MINUTEおよびNANO_OF_SECONDなしで日中期間が存在する場合、その日中期間はSMARTおよびLENIENTモードで時間として設定されます。 たとえば、解析された日期間タイプが"night1"で、フォーマッタ・ロケールで定義された期間が21:00から06:00の場合、LocalTimeは01:30になります。 解決された時間が日中と競合する場合、STRICTおよびSMARTモードでDateTimeExceptionがスローされます。 LENIENTモードでは、例外はスローされず、解析された日の期間は無視されます。

"真夜中"タイプでは、解決済時間フィールドで有効であるかぎり、"00:00"を日末として使用し、"24:00"を日末として使用できます。

パラメータ:

style - 使用するテキスト・スタイル。null以外

戻り値:

this (連鎖のため)。null以外

導入されたバージョン:

16

外部仕様

• Unicodeロケール・データ・マークアップ言語(LDML)

append

public DateTimeFormatterBuilder append(DateTimeFormatter formatter)

フォーマッタのすべての要素をビルダーに追加します。

このメソッドの効果は、フォーマッタの構成要素をそれぞれ直接このビルダーに追加することと同じです。

パラメータ:

formatter - 追加するフォーマッタ。null以外

戻り値:

this (連鎖のため)。null以外

appendOptional

public DateTimeFormatterBuilder appendOptional(DateTimeFormatter formatter)

オプションで書式設定/解析を行うフォーマッタをビルダーに追加します。

このメソッドの効果は、optionalStart()とoptionalEnd()で囲まれた構成要素をそれぞれ直接このビルダーに追加することと同じです。

フォーマッタは、その中に含まれているすべてのフィールドのデータが使用可能な場合は書式設定を行います。 フォーマッタは、文字列が一致する場合は解析を行い、それ以外の場合はエラーを返しません。

パラメータ:

formatter - 追加するフォーマッタ。null以外

戻り値:

this (連鎖のため)。null以外

appendPattern

public DateTimeFormatterBuilder appendPattern(String pattern)

指定されたパターンによって定義される要素をビルダーに追加します。

'A'から'Z'および'a'から'z'のすべての文字は、パターン文字として予約されています。 文字'#'、'{'、および'}'は、将来使用するために予約されています。 文字'['および']'は、オプションのパターンを示します。 次のパターン文字が定義されています。

  Symbol  Meaning                     Presentation      Examples
  ------  -------                     ------------      -------
   G       era                         text              AD; Anno Domini; A
   u       year                        year              2004; 04
   y       year-of-era                 year              2004; 04
   D       day-of-year                 number            189
   M/L     month-of-year               number/text       7; 07; Jul; July; J
   d       day-of-month                number            10
   g       modified-julian-day         number            2451334

   Q/q     quarter-of-year             number/text       3; 03; Q3; 3rd quarter
   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              Tue; Tuesday; T
   e/c     localized day-of-week       number/text       2; 02; Tue; Tuesday; T
   F       day-of-week-in-month        number            3

   a       am-pm-of-day                text              PM
   B       period-of-day               text              in the morning
   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       time-zone ID                zone-id           America/Los_Angeles; Z; -08:30
   v       generic time-zone name      zone-name         PT, Pacific Time
   z       time-zone name              zone-name         Pacific Standard Time; PST
   O       localized zone-offset       offset-O          GMT+8; GMT+08:00; UTC-08:00;
   X       zone-offset 'Z' for zero    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       pad next                    pad modifier      1

   '       escape for text             delimiter
   ''      single quote                literal           '
   [       optional section start
   ]       optional section end
   #       reserved for future use
   {       reserved for future use
   }       reserved for future use
 

パターン文字の数によってフォーマットが決まります。 ユーザーに焦点を合わせたパターンの説明については、DateTimeFormatterを参照してください。 次の表は、パターン文字がどのようにビルダーにマップされるかを定義しています。

日付フィールド: 日付を出力するパターン文字。

  Pattern  Count  Equivalent builder methods
  -------  -----  --------------------------
    G       1      appendText(ChronoField.ERA, TextStyle.SHORT)
    GG      2      appendText(ChronoField.ERA, TextStyle.SHORT)
    GGG     3      appendText(ChronoField.ERA, TextStyle.SHORT)
    GGGG    4      appendText(ChronoField.ERA, TextStyle.FULL)
    GGGGG   5      appendText(ChronoField.ERA, TextStyle.NARROW)

    u       1      appendValue(ChronoField.YEAR, 1, 19, SignStyle.NORMAL)
    uu      2      appendValueReduced(ChronoField.YEAR, 2, 2, 2000)
    uuu     3      appendValue(ChronoField.YEAR, 3, 19, SignStyle.NORMAL)
    u..u    4..n   appendValue(ChronoField.YEAR, n, 19, SignStyle.EXCEEDS_PAD)
    y       1      appendValue(ChronoField.YEAR_OF_ERA, 1, 19, SignStyle.NORMAL)
    yy      2      appendValueReduced(ChronoField.YEAR_OF_ERA, 2, 2, 2000)
    yyy     3      appendValue(ChronoField.YEAR_OF_ERA, 3, 19, SignStyle.NORMAL)
    y..y    4..n   appendValue(ChronoField.YEAR_OF_ERA, n, 19, SignStyle.EXCEEDS_PAD)
    Y       1      append special localized WeekFields element for numeric week-based-year
    YY      2      append special localized WeekFields element for reduced numeric week-based-year 2 digits
    YYY     3      append special localized WeekFields element for numeric week-based-year (3, 19, SignStyle.NORMAL)
    Y..Y    4..n   append special localized WeekFields element for numeric week-based-year (n, 19, SignStyle.EXCEEDS_PAD)

    Q       1      appendValue(IsoFields.QUARTER_OF_YEAR)
    QQ      2      appendValue(IsoFields.QUARTER_OF_YEAR, 2)
    QQQ     3      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.SHORT)
    QQQQ    4      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.FULL)
    QQQQQ   5      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.NARROW)
    q       1      appendValue(IsoFields.QUARTER_OF_YEAR)
    qq      2      appendValue(IsoFields.QUARTER_OF_YEAR, 2)
    qqq     3      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.SHORT_STANDALONE)
    qqqq    4      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.FULL_STANDALONE)
    qqqqq   5      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.NARROW_STANDALONE)

    M       1      appendValue(ChronoField.MONTH_OF_YEAR)
    MM      2      appendValue(ChronoField.MONTH_OF_YEAR, 2)
    MMM     3      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.SHORT)
    MMMM    4      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.FULL)
    MMMMM   5      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.NARROW)
    L       1      appendValue(ChronoField.MONTH_OF_YEAR)
    LL      2      appendValue(ChronoField.MONTH_OF_YEAR, 2)
    LLL     3      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.SHORT_STANDALONE)
    LLLL    4      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.FULL_STANDALONE)
    LLLLL   5      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.NARROW_STANDALONE)

    w       1      append special localized WeekFields element for numeric week-of-year
    ww      2      append special localized WeekFields element for numeric week-of-year, zero-padded
    W       1      append special localized WeekFields element for numeric week-of-month
    d       1      appendValue(ChronoField.DAY_OF_MONTH)
    dd      2      appendValue(ChronoField.DAY_OF_MONTH, 2)
    D       1      appendValue(ChronoField.DAY_OF_YEAR)
    DD      2      appendValue(ChronoField.DAY_OF_YEAR, 2, 3, SignStyle.NOT_NEGATIVE)
    DDD     3      appendValue(ChronoField.DAY_OF_YEAR, 3)
    F       1      appendValue(ChronoField.ALIGNED_WEEK_OF_MONTH)
    g..g    1..n   appendValue(JulianFields.MODIFIED_JULIAN_DAY, n, 19, SignStyle.NORMAL)
    E       1      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
    EE      2      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
    EEE     3      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
    EEEE    4      appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL)
    EEEEE   5      appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW)
    e       1      append special localized WeekFields element for numeric day-of-week
    ee      2      append special localized WeekFields element for numeric day-of-week, zero-padded
    eee     3      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
    eeee    4      appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL)
    eeeee   5      appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW)
    c       1      append special localized WeekFields element for numeric day-of-week
    ccc     3      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT_STANDALONE)
    cccc    4      appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL_STANDALONE)
    ccccc   5      appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW_STANDALONE)
 

時間フィールド: 時間を出力するパターン文字。

  Pattern  Count  Equivalent builder methods
  -------  -----  --------------------------
    a       1      appendText(ChronoField.AMPM_OF_DAY, TextStyle.SHORT)
    h       1      appendValue(ChronoField.CLOCK_HOUR_OF_AMPM)
    hh      2      appendValue(ChronoField.CLOCK_HOUR_OF_AMPM, 2)
    H       1      appendValue(ChronoField.HOUR_OF_DAY)
    HH      2      appendValue(ChronoField.HOUR_OF_DAY, 2)
    k       1      appendValue(ChronoField.CLOCK_HOUR_OF_DAY)
    kk      2      appendValue(ChronoField.CLOCK_HOUR_OF_DAY, 2)
    K       1      appendValue(ChronoField.HOUR_OF_AMPM)
    KK      2      appendValue(ChronoField.HOUR_OF_AMPM, 2)
    m       1      appendValue(ChronoField.MINUTE_OF_HOUR)
    mm      2      appendValue(ChronoField.MINUTE_OF_HOUR, 2)
    s       1      appendValue(ChronoField.SECOND_OF_MINUTE)
    ss      2      appendValue(ChronoField.SECOND_OF_MINUTE, 2)

    S..S    1..n   appendFraction(ChronoField.NANO_OF_SECOND, n, n, false)
    A..A    1..n   appendValue(ChronoField.MILLI_OF_DAY, n, 19, SignStyle.NOT_NEGATIVE)
    n..n    1..n   appendValue(ChronoField.NANO_OF_SECOND, n, 19, SignStyle.NOT_NEGATIVE)
    N..N    1..n   appendValue(ChronoField.NANO_OF_DAY, n, 19, SignStyle.NOT_NEGATIVE)
 

日期間: 日の期間を出力するパターン文字。

  Pattern  Count  Equivalent builder methods
  -------  -----  --------------------------
    B       1      appendDayPeriodText(TextStyle.SHORT)
    BBBB    4      appendDayPeriodText(TextStyle.FULL)
    BBBBB   5      appendDayPeriodText(TextStyle.NARROW)
 

ゾーンID: ZoneIdを出力するパターン文字。

  Pattern  Count  Equivalent builder methods
  -------  -----  --------------------------
    VV      2      appendZoneId()
    v       1      appendGenericZoneText(TextStyle.SHORT)
    vvvv    4      appendGenericZoneText(TextStyle.FULL)
    z       1      appendZoneText(TextStyle.SHORT)
    zz      2      appendZoneText(TextStyle.SHORT)
    zzz     3      appendZoneText(TextStyle.SHORT)
    zzzz    4      appendZoneText(TextStyle.FULL)
 

ゾーン・オフセット: ZoneOffsetを出力するパターン文字。

  Pattern  Count  Equivalent builder methods
  -------  -----  --------------------------
    O       1      appendLocalizedOffset(TextStyle.SHORT)
    OOOO    4      appendLocalizedOffset(TextStyle.FULL)
    X       1      appendOffset("+HHmm","Z")
    XX      2      appendOffset("+HHMM","Z")
    XXX     3      appendOffset("+HH:MM","Z")
    XXXX    4      appendOffset("+HHMMss","Z")
    XXXXX   5      appendOffset("+HH:MM:ss","Z")
    x       1      appendOffset("+HHmm","+00")
    xx      2      appendOffset("+HHMM","+0000")
    xxx     3      appendOffset("+HH:MM","+00:00")
    xxxx    4      appendOffset("+HHMMss","+0000")
    xxxxx   5      appendOffset("+HH:MM:ss","+00:00")
    Z       1      appendOffset("+HHMM","+0000")
    ZZ      2      appendOffset("+HHMM","+0000")
    ZZZ     3      appendOffset("+HHMM","+0000")
    ZZZZ    4      appendLocalizedOffset(TextStyle.FULL)
    ZZZZZ   5      appendOffset("+HH:MM:ss","Z")
 

修飾子: パターンの残り部分を変更するパターン文字。

  Pattern  Count  Equivalent builder methods
  -------  -----  --------------------------
    [       1      optionalStart()
    ]       1      optionalEnd()
    p..p    1..n   padNext(n)
 

上記に指定されていない文字シーケンス、認識されない文字、または予約済の文字を使用すると、例外がスローされます。 将来のバージョンではパターン・セットが増える可能性があります。 将来の変更によってアプリケーションが破壊されないようにするには、直接出力したいすべての文字を一重引用符で囲むことをお薦めします。

パターン文字列はSimpleDateFormatに似ていますが、同一ではありません。 パターン文字列は、Unicode共通ロケールデータリポジトリ(CLDR/LDML)で定義されているものにも似ていますが、同一ではありません。 パターン文字'X'および'u'は、Unicode CLDR/LDMLと揃っています。 これに対し、SimpleDateFormatでは、'u'は数値による曜日に使用されます。 パターン文字'y'および'Y'は、2桁の年と4桁超の年を異なる方法で解析します。 パターン文字'n'、'A'、'N'、および'p'が追加されています。 数値型では、大きい数値は拒否されます。

パラメータ:

pattern - 追加するパターン。null以外

戻り値:

this (連鎖のため)。null以外

例外:

IllegalArgumentException - パターンが無効な場合

padNext

public DateTimeFormatterBuilder padNext(int padWidth)

次に追加されるプリンタまたはパーサーで、空白を使用して固定幅のパディングを行います。

このパディングは、スペースを使用して固定幅までパディングします。

書式設定時は、装飾された要素が出力された後、指定された幅までパディングされます。 書式設定時にパディング幅を超えると、例外がスローされます。

解析時は、パディングと装飾された要素が解析されます。 厳密でない解析の場合、パディング幅は最大幅として扱われます。 パディングは貪欲に解析されます。 したがって、装飾された要素がパディング文字で始まっている場合、その要素は解析されません。

パラメータ:

padWidth - パディング幅。1以上

戻り値:

this (連鎖のため)。null以外

例外:

IllegalArgumentException - パディング幅が小さすぎる場合

padNext

public DateTimeFormatterBuilder padNext(int padWidth, char padChar)

次に追加されるプリンタまたはパーサーで、固定幅のパディングを行います。

このパディングは、ゼロによるパディングとは異なるパディングに使用することを想定しています。 ゼロによるパディングは、appendValueメソッドを使用して実現するようにしてください。

書式設定時は、装飾された要素が出力された後、指定された幅までパディングされます。 書式設定時にパディング幅を超えると、例外がスローされます。

解析時は、パディングと装飾された要素が解析されます。 厳密でない解析の場合、パディング幅は最大幅として扱われます。 大文字と小文字を区別しない解析の場合、パディング文字は大文字と小文字の区別を無視して照合されます。 パディングは貪欲に解析されます。 したがって、装飾された要素がパディング文字で始まっている場合、その要素は解析されません。

パラメータ:

padWidth - パディング幅。1以上

padChar - パディング文字

戻り値:

this (連鎖のため)。null以外

例外:

IllegalArgumentException - パディング幅が小さすぎる場合

optionalStart

public DateTimeFormatterBuilder optionalStart()

オプションのセクションの開始をマークします。

書式設定の出力には、オプションのセクションを含めることができ、それらは入れ子にすることができます。 オプションのセクションは、このメソッドの呼出しによって始まり、optionalEnd()の呼出しかビルダー・プロセスの終了によって終わります。

オプションのセクションに含まれるすべての要素は、オプションとして扱われます。 書式設定時は、セクション内のすべての要素に関するデータがTemporalAccessorで使用可能な場合のみ、セクションが出力されます。 解析時は、解析された文字列からセクション全体が欠けている場合があります。

たとえば、builder.appendValue(HOUR_OF_DAY,2).optionalStart().appendValue(MINUTE_OF_HOUR,2)として設定されたビルダーについて考えてみます。 オプションのセクションは、ビルダーの終わりで自動的に終了します。 書式設定時は、日付/時間から分の値を取得できる場合のみ、分が出力されます。 解析時は、分が存在するかどうかにかかわらず、入力は正常に解析されます。

戻り値:

this (連鎖のため)。null以外

optionalEnd

public DateTimeFormatterBuilder optionalEnd()

オプションのセクションを終了します。

書式設定の出力には、オプションのセクションを含めることができ、それらは入れ子にすることができます。 オプションのセクションは、optionalStart()の呼出しによって始まり、このメソッドを使用することで(またはビルダーの終了で)終わります。

前にoptionalStartを呼び出していない場合、このメソッドを呼び出すと例外がスローされます。 optionalStartを呼び出した直後にこのメソッドを呼び出すと、(空の)オプションのセクションが終了するだけで、フォーマッタに他の影響はありません。

オプションのセクションに含まれるすべての要素は、オプションとして扱われます。 書式設定時は、セクション内のすべての要素に関するデータがTemporalAccessorで使用可能な場合のみ、セクションが出力されます。 解析時は、解析された文字列からセクション全体が欠けている場合があります。

たとえば、builder.appendValue(HOUR_OF_DAY,2).optionalStart().appendValue(MINUTE_OF_HOUR,2).optionalEnd()として設定されたビルダーについて考えてみます。 書式設定時は、日付/時間から分の値を取得できる場合のみ、分が出力されます。 解析時は、分が存在するかどうかにかかわらず、入力は正常に解析されます。

戻り値:

this (連鎖のため)。null以外

例外:

IllegalStateException - 前にoptionalStartが呼び出されていない場合

toFormatter

public DateTimeFormatter toFormatter()

デフォルト・ロケールを使用してDateTimeFormatterを作成することにより、このビルダーを完成します。

これは、デフォルトのFORMATロケールを持つフォーマッタを作成します。 数値は標準のDecimalStyleを使用して出力および解析されます。 リゾルバ・スタイルはSMARTになります。

このメソッドを呼び出すと、開いているオプションのセクションがあればoptionalEnd()呼出しの繰返しによってすべて終了され、その後でフォーマッタが作成されます。

フォーマッタの作成後も、必要に応じてこのビルダーを使用できますが、optionalEndの呼出しによって状態は変更されている可能性があります。

戻り値:

作成されたフォーマッタ。null以外

toFormatter

public DateTimeFormatter toFormatter(Locale locale)

指定されたロケールを使用してDateTimeFormatterを作成することにより、このビルダーを完成します。

これは、指定されたロケールを持つフォーマッタを作成します。 数値は標準のDecimalStyleを使用して出力および解析されます。 リゾルバ・スタイルはSMARTになります。

このメソッドを呼び出すと、開いているオプションのセクションがあればoptionalEnd()呼出しの繰返しによってすべて終了され、その後でフォーマッタが作成されます。

フォーマッタの作成後も、必要に応じてこのビルダーを使用できますが、optionalEndの呼出しによって状態は変更されている可能性があります。

パラメータ:

locale - 書式設定に使用するロケール。null以外

戻り値:

作成されたフォーマッタ。null以外