- 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()
ビルダーの新しいインスタンスを構築します。
-
メソッドのサマリー
すべてのメソッド staticメソッド インスタンス・メソッド 具象メソッド 修飾子と型 メソッド 説明 DateTimeFormatterBuilder
append(DateTimeFormatter formatter)
フォーマッタのすべての要素をビルダーに追加します。DateTimeFormatterBuilder
appendChronologyId()
「ISO」や「ThaiBuddhist」などの暦IDをフォーマッタに追加します。DateTimeFormatterBuilder
appendChronologyText(TextStyle textStyle)
暦名をフォーマッタに追加します。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(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(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
を作成することにより、このビルダーを完成します。
-
-
-
メソッドの詳細
-
getLocalizedDateTimePattern
public static String getLocalizedDateTimePattern(FormatStyle dateStyle, FormatStyle timeStyle, Chronology chrono, Locale locale)
ロケールおよび暦の日付および時間のスタイルの書式設定パターンを取得します。 ロケールと暦は、要求されたdateStyleまたはtimeStyle、あるいはその両方に対するロケール固有のフォーマットを検索するために使用されます。ロケールに"rg" (リージョン・オーバーライド) 「Unicode拡張」が含まれている場合、フォーマット・パターンはそのリージョンに適したもので上書きされます。
- パラメータ:
dateStyle
- 日付のFormatStyle、時間専用パターンの場合はnulltimeStyle
- 時間のFormatStyle、日付専用パターンの場合はnullchrono
- 暦。null以外locale
- ロケール。null以外- 戻り値:
- ロケールおよび暦に固有の書式設定パターン
- 例外:
IllegalArgumentException
- dateStyleとtimeStyleの両方がnullの場合
-
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
と出力されます。出力される小数部の幅は制御できます。 最小幅をゼロに設定すると、出力は生成されません。 出力される小数部は、最小幅と最大幅の間で最小限必要な幅になり、末尾のゼロは省略されます。 最大幅のため、丸めは行われず、桁が単純に切り捨てられます。
厳密モードでの解析時、解析される桁数は最小幅と最大幅の間になければなりません。 strictモードでは、最小幅と最大幅が等しく、小数点がない場合、パーサーは隣接値解析に参加します(
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フォーマットを使用して書式設定されます。 このメソッドでは、必要に応じて秒、秒、秒、または秒をフォーマットします。 ローカライズされた10進スタイルは使用されません。
インスタントは、
INSTANT_SECONDS
とオプションでNANO_OF_SECOND
を使用して取得されます。INSTANT_SECONDS
の値は、LocalDateTime
の最大範囲外になることがあります。リゾルバ・スタイルはインスタントの解析には影響しません。 1日の終わりの時間「24:00」は、次の日の開始の深夜零時として処理されます。 うるう秒時間「23:59:59」はある程度まで処理されます。詳細は、
DateTimeFormatter.parsedLeapSecond()
を参照してください。このメソッドに代わる方法は、インスタントを単一のエポック秒値として書式設定/解析することです。 これは
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()
で照会する場合と同等のメカニズムを使用して、オフセットが取得されます。 これは、下記で定義されているフォーマットを使用して出力されます。 オフセットを取得できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。strictモードで解析する場合、入力には必須要素とオプション要素が含まれていなければならず、指定されたパターンで定義されます。 オフセットを解析できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。
寛大なモードで解析するときは、時間だけが必須です - 分と秒はオプションです。 コロンは、指定されたパターンにコロンが含まれている場合に必要です。 指定されたパターンが"+HH"の場合、コロンの有無は、時間桁の後の文字がコロンかどうかによって決まります。 オフセットを解析できない場合は、フォーマッタのそのセクションがオプションである場合を除き、例外がスローされます。
オフセットのフォーマットはパターンによって制御されます。パターンは次のいずれかでなければなりません。
+HH
- 分と秒は無視し、時のみ+HHmm
- 秒は無視し、時と分(ゼロでない場合)。コロンなし+HH:mm
- 秒は無視し、時と分(ゼロでない場合)。コロンあり+HHMM
- 秒は無視し、時と分。コロンなし+HH:MM
- 秒は無視し、時と分。コロンあり+HHMMss
- 時、分、および秒(ゼロでない場合)。コロンなし+HH:MM:ss
- 時、分、および秒(ゼロでない場合)。コロンあり+HHMMSS
- 時、分、および秒。コロンなし+HH:MM:SS
- 時、分、および秒。コロンあり+HHmmss
- 非ゼロの場合は分、分の場合は秒、非ゼロの場合は秒、コロンは使用できません+HH:mm:ss
- 非ゼロの場合は分、分の場合は秒、非ゼロの場合は秒、コロン+H
- 分、秒を無視して1時間だけ+Hmm
- 時があり、0以外の場合は分、秒は無視し、コロンは使用しない+H:mm
- 時があり、0以外の場合は分、コロンは秒を無視+HMM
- 時と分、秒を無視する、コロンなし+H:MM
- 時と分、秒を無視して、コロンで+HMMss
- 時と分、0以外の場合は2番目にコロンはありません+H:MM:ss
- 時と分、コロンで2番目にゼロでない場合+HMMSS
- 時、分、秒、コロンなし+H:MM:SS
- 時、分、秒、コロン+Hmmss
- 非ゼロの場合は分、分の場合は秒、非ゼロの場合は秒、コロンは使用できません+H:mm:ss
- 非ゼロの場合は分、分の場合は秒、非ゼロの場合は秒、コロン
- パラメータ:
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年を通して同じです。 たとえば、'太平洋時間'は総称名ですが、'太平洋標準時'と'太平洋夏時間'は固有の名前です(
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年を通して同じです。 たとえば、'太平洋時間'は総称名ですが、'太平洋標準時'と'太平洋夏時間'は固有の名前です(
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の場合
- このメソッドに指定された
-
appendLiteral
public DateTimeFormatterBuilder appendLiteral(char literal)
文字リテラルをフォーマッタに追加します。この文字は書式設定時に出力されます。
- パラメータ:
literal
- 追加するリテラル。null以外- 戻り値:
- this (連鎖のため)。null以外
-
appendLiteral
public DateTimeFormatterBuilder appendLiteral(String literal)
文字列リテラルをフォーマッタに追加します。この文字列は書式設定時に出力されます。
リテラルが空の場合、フォーマッタには何も追加されません。
- パラメータ:
literal
- 追加するリテラル。null以外- 戻り値:
- this (連鎖のため)。null以外
-
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 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, 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, 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_DAY_OF_WEEK_IN_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)
ゾーン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以外
-
-