Класс DateTimeFormatterBuilder

java.lang.Object

java.time.format.DateTimeFormatterBuilder

public final class DateTimeFormatterBuilder extends Object

Построитель для создания форматировщиков даты и времени.

Он позволяет создать DateTimeFormatter. В конечном итоге все форматировщики даты и времени создаются с помощью этого построителя.

Можно добавлять все основные элементы даты и времени:

Значение — числовое значение
Дробная часть — дробное значение, включающее десятичный разделитель. При выводе дробных значений всегда используйте этот элемент, чтобы обеспечить правильный разбор дробной части
Текст — текстовое представление значения
OffsetId/Offset — смещение часового пояса
ZoneId — идентификатор часового пояса
ZoneText — название часового пояса
ChronologyId — идентификатор хронологии
ChronologyText — название хронологии
Литерал — буквальный текст
Вложенные и необязательные элементы — форматы могут быть вложенными или необязательными

Кроме того, любой элемент можно дополнить отступом, используя пробелы или любой другой символ.

Наконец, можно использовать сокращенный шаблон, в основном совместимый с java.text.SimpleDateFormat SimpleDateFormat; см. appendPattern(String). На практике это просто разбирает шаблон и вызывает другие методы построителя.

Требования к реализации:: Этот класс является изменяемым построителем, предназначенным для использования в одном потоке.
С версии:: 1.8

Краткое описание конструкторов

Конструктор	Описание
`DateTimeFormatterBuilder()`	Создает новый экземпляр построителя.

Краткое описание методов

Модификатор и тип	Метод	Описание
`DateTimeFormatterBuilder`	`append(DateTimeFormatter formatter)`	Добавляет в построитель все элементы форматировщика.
`DateTimeFormatterBuilder`	`appendChronologyId()`	Добавляет в форматировщик идентификатор хронологии, например 'ISO' или 'ThaiBuddhist'.
`DateTimeFormatterBuilder`	`appendChronologyText(TextStyle textStyle)`	Добавляет в форматировщик название хронологии.
`DateTimeFormatterBuilder`	`appendDayPeriodText(TextStyle style)`	Добавляет в форматировщик текст обозначения времени суток.
`DateTimeFormatterBuilder`	`appendFraction(TemporalField field, int minWidth, int maxWidth, boolean decimalPoint)`	Добавляет в форматировщик дробное значение поля даты и времени.
`DateTimeFormatterBuilder`	`appendGenericZoneText(TextStyle textStyle)`	Добавляет в форматировщик общее название часового пояса, например 'Pacific Time'.
`DateTimeFormatterBuilder`	`appendGenericZoneText(TextStyle textStyle, Set<ZoneId> preferredZones)`	Добавляет в форматировщик общее название часового пояса, например 'Pacific Time'.
`DateTimeFormatterBuilder`	`appendInstant()`	Добавляет в форматировщик момент времени в формате ISO-8601, форматируя дробные разряды группами по три.
`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()`	Добавляет в форматировщик идентификатор часового пояса, например 'Europe/Paris' или '+02:00'.
`DateTimeFormatterBuilder`	`appendZoneOrOffsetId()`	Добавляет в форматировщик идентификатор часового пояса, например 'Europe/Paris' или '+02:00', используя наиболее подходящий идентификатор часового пояса.
`DateTimeFormatterBuilder`	`appendZoneRegionId()`	Добавляет в форматировщик идентификатор региона часового пояса, например 'Europe/Paris', отклоняя идентификатор, если он является `ZoneOffset`.
`DateTimeFormatterBuilder`	`appendZoneText(TextStyle textStyle)`	Добавляет в форматировщик название часового пояса, например 'British Summer Time'.
`DateTimeFormatterBuilder`	`appendZoneText(TextStyle textStyle, Set<ZoneId> preferredZones)`	Добавляет в форматировщик название часового пояса, например 'British Summer Time'.
`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` с указанной локалью.

Методы, объявленные в классе Object

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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создает и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Указывает, равен ли другой объект этому объекту.
`protected void`	`finalize()`	Устарел, будет удален: этот элемент API может быть удален в будущей версии. Финализация объявлена устаревшей и будет удалена в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Приостанавливает выполнение текущего потока до его пробуждения, обычно в результате вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Приостанавливает выполнение текущего потока до его пробуждения, обычно в результате вызова notify или interrupt, либо до истечения заданного интервала реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Приостанавливает выполнение текущего потока до его пробуждения, обычно в результате вызова notify или interrupt, либо до истечения заданного интервала реального времени.

Подробное описание конструкторов

DateTimeFormatterBuilder

public DateTimeFormatterBuilder()

Создает новый экземпляр построителя.

Подробное описание методов

getLocalizedDateTimePattern

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

Возвращает шаблон форматирования для стилей даты и времени с учетом локали и хронологии. Локаль и хронология используются для поиска формата, специфичного для локали, для запрошенного dateStyle и/или timeStyle.

Если локаль содержит расширения Unicode "rg" (переопределение региона), шаблон форматирования заменяется шаблоном, подходящим для этого региона.

Параметры:: 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)

Возвращает шаблон форматирования для запрошенного шаблона с учетом локали и хронологии. Локаль и хронология используются для поиска формата, специфичного для локали, для запрошенного шаблона.

Подробное описание аргумента requestedTemplate см. в appendLocalized(String).

Параметры:

requestedTemplate — запрошенный шаблон, не null

chrono — хронология, не null

locale — локаль, не null

Возвращает:

шаблон форматирования, специфичный для локали и хронологии

Вызывает исключение:

IllegalArgumentException — если requestedTemplate не соответствует синтаксису регулярных выражений, описанному в appendLocalized(String).

DateTimeException — если шаблон локализованного формата для requestedTemplate недоступен

Начиная с версии:

См. также:

parseCaseSensitive

public DateTimeFormatterBuilder parseCaseSensitive()

Устанавливает чувствительный к регистру режим разбора для оставшейся части форматтера.

Разбор может учитывать или не учитывать регистр; по умолчанию регистр учитывается. Этот метод позволяет изменить параметр учета регистра при разборе.

Вызов этого метода изменяет состояние построителя так, что все последующие вызовы методов построителя будут разбирать текст в режиме с учетом регистра. Противоположный параметр задается методом parseCaseInsensitive(). Методы управления учетом регистра при разборе можно вызывать в любой точке построителя, поэтому анализатор может многократно переключаться между режимами разбора с учетом и без учета регистра.

Поскольку по умолчанию регистр учитывается, этот метод следует использовать только после вызова #parseCaseInsensitive.

Возвращает:: этот объект для цепочки вызовов, не null

parseCaseInsensitive

public DateTimeFormatterBuilder parseCaseInsensitive()

Устанавливает нечувствительный к регистру режим разбора для оставшейся части форматтера.

Вызов этого метода изменяет состояние построителя так, что все последующие вызовы методов построителя будут разбирать текст в режиме без учета регистра. Противоположный параметр задается методом parseCaseSensitive(). Методы управления учетом регистра при разборе можно вызывать в любой точке построителя, поэтому анализатор может многократно переключаться между режимами разбора с учетом и без учета регистра.

Возвращает:: этот объект для цепочки вызовов, не null

parseStrict

public DateTimeFormatterBuilder parseStrict()

Устанавливает строгий режим разбора для оставшейся части форматтера.

Разбор может быть строгим или нестрогим; по умолчанию он строгий. Этот параметр определяет степень гибкости при сопоставлении текста и знаков.

При вызове этого метода разбор с этого момента становится строгим. Поскольку строгий режим используется по умолчанию, обычно этот метод нужен только после вызова parseLenient(). Изменение будет действовать до конца созданного форматтера или до вызова parseLenient.

Требования к реализации:: В строгом режиме разбора SPACE_SEPARATOR во входном тексте не будет соответствовать никаким другим SPACE_SEPARATOR в шаблоне.
Возвращает:: этот объект для цепочки вызовов, не null

parseLenient

public DateTimeFormatterBuilder parseLenient()

Устанавливает нестрогий режим разбора для оставшейся части форматтера. Обратите внимание, что чувствительность к регистру настраивается отдельно от этого метода.

Разбор может быть строгим или нестрогим; по умолчанию он строгий. Этот параметр определяет степень гибкости при сопоставлении текста и знаков. Обычно приложениям, вызывающим этот метод, также следует вызвать parseCaseInsensitive().

При вызове этого метода разбор с этого момента становится нестрогим. Изменение будет действовать до конца созданного форматтера или до вызова parseStrict.

Требования к реализации:: В нестрогом режиме разбора SPACE_SEPARATOR во входном тексте будет соответствовать любым другим SPACE_SEPARATOR в шаблоне.
Возвращает:: этот объект для цепочки вызовов, не null

parseDefaulting

public DateTimeFormatterBuilder parseDefaulting(TemporalField field, long value)

Добавляет в форматтер значение поля по умолчанию для использования при разборе.

Этот метод добавляет в построитель инструкцию, которая подставляет значение по умолчанию в результат разбора. Это особенно полезно в сочетании с необязательными частями форматтера.

Например, рассмотрим форматтер, который разбирает год, за которым следует необязательный месяц, а затем еще один необязательный день месяца. При использовании такого форматтера вызывающий код должен проверять, была ли разобрана полная дата, год и месяц или только год. Этот метод позволяет задать для месяца и дня месяца разумные значения по умолчанию, например первое число месяца, чтобы вызывающий код всегда получал дату.

При форматировании этот метод не действует.

При разборе проверяется текущее состояние разбора. Если указанное поле не имеет связанного значения, поскольку к этому моменту оно не было успешно разобрано, указанное значение подставляется в результат разбора. Подстановка выполняется немедленно, поэтому пара «поле — значение» будет видна всем последующим элементам форматтера. Поэтому обычно этот метод вызывается в конце построителя.

Параметры:: field — поле, для которого задается значение по умолчанию, не null; value — значение по умолчанию для поля
Возвращает:: этот объект для цепочки вызовов, не null

appendValue

public DateTimeFormatterBuilder appendValue(TemporalField field)

Добавляет значение поля даты и времени в форматтер, используя обычный способ вывода.

Значение поля будет выведено при форматировании. Если получить значение невозможно, будет выброшено исключение.

Значение будет напечатано в обычном формате целого числа. Знак ставится только перед отрицательными числами. Дополнение не выполняется.

Анализатор для значения переменной ширины, такого как это, обычно работает жадно: требует одну цифру, но принимает столько цифр, сколько возможно. На это поведение может влиять «разбор соседних значений». Полное описание см. в appendValue(java.time.temporal.TemporalField, int).

Параметры:: field — добавляемое поле, не null
Возвращает:: этот объект для цепочки вызовов, не null

appendValue

public DateTimeFormatterBuilder appendValue(TemporalField field, int width)

Добавляет значение поля даты и времени в форматтер с фиксированной шириной и дополнением нулями.

Значение дополняется нулями слева. Если ширина недостаточна для вывода значения, выбрасывается исключение. Если значение поля отрицательное, при форматировании выбрасывается исключение.

Этот метод поддерживает специальный прием разбора, известный как «разбор соседних значений». Этот прием решает проблему, возникающую, когда за значением переменной или фиксированной ширины следует одно или несколько значений фиксированной длины. Стандартный анализатор работает жадно и поэтому обычно забирает цифры, необходимые следующим за ним анализаторам значений фиксированной ширины.

Для запуска «разбора соседних значений» не требуется никаких действий. При вызове appendValue построитель переходит в режим настройки разбора соседних значений. Если непосредственно следующие вызовы метода или методов того же построителя добавляют значения фиксированной ширины, анализатор резервирует место, чтобы их можно было разобрать.

Например, рассмотрим builder.appendValue(YEAR).appendValue(MONTH_OF_YEAR, 2); Год разбирается с переменной шириной от 1 до 19 цифр. Месяц разбирается с фиксированной шириной в 2 цифры. Поскольку эти элементы добавлены в один и тот же построитель непосредственно друг за другом, анализатор года зарезервирует две цифры для разбора месяца. Таким образом, текст '201106' будет правильно разобран как 2011 год и 6-й месяц. Без разбора соседних значений анализатор года жадно разобрал бы все шесть цифр, и для месяца ничего бы не осталось.

Разбор соседних значений применяется к каждому набору значений неотрицательных чисел фиксированной ширины в анализаторе, которые непосредственно следуют за значением любого типа — переменной или фиксированной ширины. Вызов любого другого метода добавления завершает настройку разбора соседних значений. Поэтому, если вам по какой-либо причине нужно избежать такого поведения, просто добавьте appendValue в другой DateTimeFormatterBuilder и добавьте его в этот построитель.

Если разбор соседних значений активен, и в строгом, и в нестрогом режиме должно совпадать в точности указанное количество цифр. Кроме того, знак «плюс» или «минус» не допускается.

Параметры:: field — добавляемое поле, не null; width — ширина печатаемого поля, от 1 до 19
Возвращает:: этот объект для цепочки вызовов, не null
Вызывает исключение:: IllegalArgumentException — если ширина недопустима

appendValue

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

Добавляет значение поля даты и времени в форматтер, обеспечивая полный контроль над форматированием.

Этот метод обеспечивает полный контроль над форматированием чисел, включая дополнение нулями и вывод знака «плюс» или «минус».

Анализатор для значения переменной ширины, такого как это, обычно работает жадно, принимая столько цифр, сколько возможно. На это поведение может влиять «разбор соседних значений». Полное описание см. в appendValue(java.time.temporal.TemporalField, int).

В строгом режиме разбора минимальное число разбираемых цифр равно minWidth, а максимальное — maxWidth. В нестрогом режиме разбора минимальное число разбираемых цифр равно единице, а максимальное — 19 (с учетом ограничений разбора соседних значений).

Если этот метод вызван с одинаковыми минимальной и максимальной шириной и стилем знака NOT_NEGATIVE, он делегирует вызов appendValue(TemporalField,int). В этом случае применяется описанное там поведение форматирования и разбора.

Параметры:: field — добавляемое поле, не null; minWidth — минимальная ширина печатаемого поля, от 1 до 19; maxWidth — максимальная ширина печатаемого поля, от 1 до 19; signStyle — стиль вывода положительного/отрицательного значения, не null
Возвращает:: этот объект для цепочки вызовов, не 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, поскольку это значение находится в диапазоне и заканчивается символами "12". Напротив, разбор текста "1915" даст значение 1915.

Параметры:: field — добавляемое поле, не null; width — ширина печатаемого и разбираемого поля, от 1 до 10; maxWidth — максимальная ширина печатаемого поля, от 1 до 10; baseValue — базовое значение диапазона допустимых значений
Возвращает:: этот объект для цепочки вызовов, не null
Вызывает исключение:: IllegalArgumentException — если ширина или базовое значение недопустимы

appendValueReduced

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

Добавляет сокращенное значение поля даты и времени в форматтер.

Обычно этот метод используется для форматирования и разбора года, представленного двумя цифрами.

Базовая дата используется для вычисления полного значения при разборе. Например, если базовая дата — 1950-01-01, разобранные значения двухзначного года будут находиться в диапазоне от 1950-01-01 до 2049-12-31. Из даты извлекается только год, поэтому базовая дата 1950-08-25 также задаст диапазон разбора от 1950-01-01 до 2049-12-31. Такое поведение необходимо для поддержки таких полей, как год на основе недель, или других календарных систем, в которых разобранное значение не соответствует стандартным годам ISO.

Точный алгоритм следующий. Разберите полный набор полей и определите эффективную хронологию, используя последнюю из хронологий, если она встречается несколько раз. Затем преобразуйте базовую дату в эффективную хронологию. После этого извлеките указанное поле из базовой даты для этой хронологии и используйте его для определения baseValue, применяемого ниже.

Параметры:: field — добавляемое поле, не null; width — ширина печатаемого и разбираемого поля, от 1 до 10; maxWidth — максимальная ширина печатаемого поля, от 1 до 10; baseDate — базовая дата, используемая для вычисления базового значения диапазона допустимых значений в разбираемой хронологии, не null
Возвращает:: этот объект для цепочки вызовов, не null
Вызывает исключение:: IllegalArgumentException — если ширина или базовое значение недопустимы

appendFraction

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

Добавляет дробное значение поля даты и времени в форматтер.

Дробное значение поля выводится вместе с предшествующим десятичным разделителем. Предшествующее значение не выводится. Например, значение секунд в минуте, равное 15, будет выведено как .25.

Можно задать ширину выводимой дробной части. Если минимальная ширина равна нулю, вывод не выполняется. Дробная часть выводится с минимально необходимой шириной в заданном диапазоне от минимальной до максимальной ширины; конечные нули опускаются. При достижении максимальной ширины округление не выполняется — лишние цифры просто отбрасываются.

При разборе в строгом режиме число разбираемых цифр должно находиться в диапазоне от минимальной до максимальной ширины. В строгом режиме, если минимальная и максимальная ширина равны и десятичный разделитель отсутствует, анализатор будет участвовать в разборе соседних значений; см. appendValue(java.time.temporal.TemporalField, int). При разборе в нестрогом режиме минимальная ширина считается равной нулю, а максимальная — девяти.

Если получить значение невозможно, будет выброшено исключение. Если значение отрицательное, будет выброшено исключение. Если поле не имеет фиксированного набора допустимых значений, будет выброшено исключение. Если значение поля в форматируемых дате и времени выходит за пределы допустимого диапазона, будет выброшено исключение.

Параметры:: field — добавляемое поле, не null; minWidth — минимальная ширина поля без десятичного разделителя, от 0 до 9; maxWidth — максимальная ширина поля без десятичного разделителя, от 1 до 9; decimalPoint — указывает, следует ли выводить локализованный символ десятичного разделителя
Возвращает:: этот объект для цепочки вызовов, не null
Вызывает исключение:: IllegalArgumentException — если поле имеет переменный набор допустимых значений или одна из ширин недопустима

appendText

public DateTimeFormatterBuilder appendText(TemporalField field)

Добавляет текстовое представление поля даты и времени в форматтер, используя полный текстовый стиль.

Текстовое представление поля будет выведено при форматировании. Значение должно находиться в допустимом диапазоне поля. Если получить значение невозможно, будет выброшено исключение. Если у поля нет текстового представления, будет использовано числовое значение.

Значение будет выведено в обычном формате целого числа. Знак ставится только перед отрицательными числами. Дополнение не выполняется.

Параметры:: field — добавляемое поле, не null
Возвращает:: этот объект для цепочки вызовов, не null

appendText

public DateTimeFormatterBuilder appendText(TemporalField field, TextStyle textStyle)

Добавляет текстовое представление поля даты и времени в форматтер.

Параметры:: field — добавляемое поле, не null; textStyle — используемый текстовый стиль, не null
Возвращает:: этот объект для цепочки вызовов, не 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 — карта соответствий между значениями и текстом
Возвращает:: этот объект для цепочки вызовов, не null

appendInstant

public DateTimeFormatterBuilder appendInstant()

Добавляет в форматтер момент времени в формате ISO-8601, группируя дробные цифры по три.

Моменты времени имеют фиксированный формат вывода. Они преобразуются в дату и время со смещением часового пояса UTC и форматируются в стандартном формате ISO-8601. При использовании этого метода наносекунды выводятся с нулем, тремя, шестью или девятью цифрами по мере необходимости. Локализованный десятичный формат не используется.

Момент времени извлекается с помощью INSTANT_SECONDS и, при необходимости, NANO_OF_SECOND. Значение INSTANT_SECONDS может выходить за пределы максимального диапазона LocalDateTime.

Стиль разрешения не влияет на разбор момента времени. Время конца дня '24:00' обрабатывается как полночь в начале следующего дня. Время високосной секунды '23:59:59' обрабатывается определенным образом; подробности см. в DateTimeFormatter.parsedLeapSecond().

При форматировании к моменту времени всегда добавляется суффикс 'Z', обозначающий UTC. При разборе для разбора смещения используется поведение нестрогого режима метода appendOffset("+HH", "Z"); при необходимости момент времени преобразуется в UTC.

Альтернативой этому методу является форматирование/разбор момента времени как единственного значения секунд от начала эпохи. Это выполняется с помощью appendValue(INSTANT_SECONDS).

Возвращает:: этот объект для цепочки вызовов, не null

appendInstant

public DateTimeFormatterBuilder appendInstant(int fractionalDigits)

Добавляет в форматтер момент времени в формате ISO-8601 с возможностью задать количество дробных цифр.

Моменты времени имеют фиксированный формат вывода, однако этот метод позволяет управлять количеством дробных цифр. Они преобразуются в дату и время со смещением часового пояса UTC и выводятся в стандартном формате ISO-8601. Локализованный десятичный формат не используется.

Параметр fractionalDigits позволяет управлять выводом дробной части секунды. Значение ноль означает, что дробные цифры не выводятся. Значения от 1 до 9 задают возрастающее количество цифр; при необходимости справа добавляются нули. Специальное значение -1 используется для вывода необходимого количества цифр без конечных нулей.

При разборе в строгом режиме число разобранных цифр должно совпадать с количеством дробных цифр. При разборе в нестрогом режиме допускается любое количество дробных цифр от нуля до девяти.

Стиль разрешения не влияет на разбор момента времени. Время конца дня '24:00' обрабатывается как полночь в начале следующего дня. Время високосной секунды '23:59:60' обрабатывается определенным образом; подробности см. в DateTimeFormatter.parsedLeapSecond().

Параметры:: fractionalDigits — количество выводимых дробных цифр секунды, от 0 до 9, или -1 для вывода необходимого количества цифр
Возвращает:: этот объект для цепочки вызовов, не null
Вызывает исключение:: IllegalArgumentException — если количество дробных цифр недопустимо

appendOffsetId

public DateTimeFormatterBuilder appendOffsetId()

Добавляет в форматтер смещение часового пояса, например '+01:00'.

Этот метод добавляет в построитель инструкцию для форматирования/разбора идентификатора смещения. Он эквивалентен вызову appendOffset("+HH:MM:ss", "Z"). Подробные сведения о форматировании и разборе см. в appendOffset(String, String).

Возвращает:: этот объект для цепочки вызовов, не null

appendOffset

public DateTimeFormatterBuilder appendOffset(String pattern, String noOffsetText)

Добавляет к форматтеру смещение часового пояса, например '+01:00'.

Добавляет построителю инструкцию для форматирования/разбора идентификатора смещения.

При форматировании смещение получается с помощью механизма, эквивалентного запросу к временному объекту с помощью TemporalQueries.offset(). Оно выводится в формате, определённом ниже. Если получить смещение невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным.

При разборе в строгом режиме входные данные должны содержать обязательные и необязательные элементы, определённые указанным шаблоном. Если разобрать смещение невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным.

При разборе в нестрогом режиме обязательны только часы — минуты и секунды необязательны. Двоеточия требуются, если указанный шаблон содержит двоеточие. Если указанный шаблон — "+HH", наличие двоеточий определяется тем, является ли символ после цифр часов двоеточием. Если разобрать смещение невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным.

Формат смещения задаётся шаблоном, который должен быть одним из следующих:

+HH — только часы, минуты и секунды игнорируются
+HHmm — часы, минуты при ненулевом значении; секунды игнорируются, без двоеточия
+HH:mm — часы, минуты при ненулевом значении; секунды игнорируются, с двоеточием
+HHMM — часы и минуты, секунды игнорируются, без двоеточия
+HH:MM — часы и минуты, секунды игнорируются, с двоеточием
+HHMMss — часы и минуты, секунды добавляются при ненулевом значении, без двоеточия
+HH:MM:ss — часы и минуты, секунды добавляются при ненулевом значении, с двоеточием
+HHMMSS — часы, минуты и секунды, без двоеточия
+HH:MM:SS — часы, минуты и секунды, с двоеточием
+HHmmss — часы, минуты при ненулевом значении либо минуты и секунды при ненулевых значениях, без двоеточия
+HH:mm:ss — часы, минуты при ненулевом значении либо минуты и секунды при ненулевых значениях, с двоеточием
+H — только часы, минуты и секунды игнорируются
+Hmm — часы, минуты при ненулевом значении; секунды игнорируются, без двоеточия
+H:mm — часы, минуты при ненулевом значении; секунды игнорируются, с двоеточием
+HMM — часы и минуты, секунды игнорируются, без двоеточия
+H:MM — часы и минуты, секунды игнорируются, с двоеточием
+HMMss — часы и минуты, секунды добавляются при ненулевом значении, без двоеточия
+H:MM:ss — часы и минуты, секунды добавляются при ненулевом значении, с двоеточием
+HMMSS — часы, минуты и секунды, без двоеточия
+H:MM:SS — часы, минуты и секунды, с двоеточием
+Hmmss — часы, минуты при ненулевом значении либо минуты и секунды при ненулевых значениях, без двоеточия
+H:mm:ss — часы, минуты при ненулевом значении либо минуты и секунды при ненулевых значениях, с двоеточием

Шаблоны, содержащие "HH", форматируют и разбирают двузначное значение часов, при необходимости дополняя его нулём слева. Шаблоны, содержащие "H", форматируют значение без дополнения нулём и разбирают одну или две цифры. В нестрогом режиме анализатор будет использовать жадный алгоритм и разберёт максимально возможное количество цифр. Текст «нет смещения» определяет, какой текст выводится, если суммарное значение выводимых полей смещения равно нулю. Примерами могут служить 'Z', '+00:00', 'UTC' или 'GMT'. При разборе UTC принимаются три формата: текст «нет смещения», а также варианты со знаком плюс и минус для нуля, определённые шаблоном.

Параметры:: pattern — используемый шаблон, не null; noOffsetText — текст, используемый при нулевом смещении, не null
Возвращает:: этот объект для цепочки вызовов, не null
Выбрасывает:: IllegalArgumentException — если шаблон недопустим

appendLocalizedOffset

public DateTimeFormatterBuilder appendLocalizedOffset(TextStyle style)

Добавляет к форматтеру локализованное смещение часового пояса, например 'GMT+01:00'.

Добавляет построителю локализованное смещение часового пояса; формат локализованного смещения определяется указанным для этого метода значением style:

full — форматирует с локализованным текстом смещения, например 'GMT', двузначным значением часов и минут, необязательным значением секунд при ненулевом значении и двоеточием.
short — форматирует с локализованным текстом смещения, например 'GMT', значением часов без ведущего нуля, необязательными двузначными значениями минут и секунд при ненулевом значении и двоеточием.

При форматировании смещение получается с помощью механизма, эквивалентного запросу к временному объекту с помощью TemporalQueries.offset(). Если получить смещение невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным.

При разборе смещение разбирается в формате, определённом выше. Если разобрать смещение невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным.

Параметры:: style — используемый стиль формата, не null
Возвращает:: этот объект для цепочки вызовов, не null
Выбрасывает:: IllegalArgumentException — если стиль не является ни full, ни short

appendZoneId

public DateTimeFormatterBuilder appendZoneId()

Добавляет к форматтеру идентификатор часового пояса, например 'Europe/Paris' или '+02:00'.

Добавляет построителю инструкцию для форматирования/разбора идентификатора часового пояса. Идентификатор часового пояса получается в строгом режиме, подходящем для ZonedDateTime. В отличие от него, OffsetDateTime не имеет идентификатора часового пояса, подходящего для использования с этим методом; см. appendZoneOrOffsetId().

При форматировании часовой пояс получается с помощью механизма, эквивалентного запросу к временному объекту с помощью TemporalQueries.zoneId(). Он выводится с использованием результата ZoneId.getId(). Если получить часовой пояс невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным.

При разборе текст должен соответствовать известному часовому поясу или смещению. Существует два типа идентификаторов часового пояса: основанные на смещении, например '+01:30', и региональные, например 'Europe/London'. Они разбираются по-разному. Если разбор начинается с '+' или '-', анализатор ожидает часовой пояс, основанный на смещении, и не будет сопоставлять региональные часовые пояса. Разбор идентификатора смещения эквивалентен использованию appendOffset(String, String) с аргументами 'HH:MM:ss' и строкой «нет смещения» '0'. Если разбор начинается с 'UT', 'UTC' или 'GMT' и анализатор может сопоставить следующее за ними смещение, будет возвращён региональный часовой пояс с разобранным смещением; если же анализатор не может сопоставить следующее смещение, выбирается 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"                -- ZoneId.of("UT+01:30")
  "UTC+01:30"               -- ZoneId.of("UTC+01:30")
  "GMT+01:30"               -- ZoneId.of("GMT+01:30")

Возвращает:

этот объект для цепочки вызовов, не null

См. также:

appendZoneRegionId

public DateTimeFormatterBuilder appendZoneRegionId()

Добавляет к форматтеру идентификатор региона часового пояса, например 'Europe/Paris', отклоняя идентификатор часового пояса, если он является ZoneOffset.

Добавляет построителю инструкцию для форматирования только региональных идентификаторов часовых поясов.

При форматировании часовой пояс получается с помощью механизма, эквивалентного запросу к временному объекту с помощью TemporalQueries.zoneId(). Если часовой пояс является ZoneOffset или получить его невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным. Если часовой пояс не является смещением, он выводится с использованием идентификатора часового пояса из ZoneId.getId().

Например, будет выполнен разбор следующих значений:

  "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"                -- ZoneId.of("UT+01:30")
  "UTC+01:30"               -- ZoneId.of("UTC+01:30")
  "GMT+01:30"               -- ZoneId.of("GMT+01:30")

Обратите внимание, что этот метод идентичен appendZoneId(), за исключением механизма получения часового пояса. Также обратите внимание, что при разборе принимаются смещения, тогда как при форматировании они никогда не выводятся.

Возвращает:

этот объект для цепочки вызовов, не null

См. также:

appendZoneOrOffsetId

public DateTimeFormatterBuilder appendZoneOrOffsetId()

Добавляет к форматтеру идентификатор часового пояса, например 'Europe/Paris' или '+02:00', используя наилучший доступный идентификатор часового пояса.

Добавляет построителю инструкцию для форматирования/разбора наилучшего доступного идентификатора часового пояса или смещения. Идентификатор часового пояса получается в нестрогом режиме: сначала выполняется попытка найти настоящий идентификатор часового пояса, например в ZonedDateTime, а затем — смещение, например в OffsetDateTime.

При форматировании часовой пояс получается с помощью механизма, эквивалентного запросу к временному объекту с помощью TemporalQueries.zone(). Он выводится с использованием результата ZoneId.getId(). Если получить часовой пояс невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным.

Например, будет выполнен разбор следующих значений:

  "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"                -- ZoneId.of("UT+01:30")
  "UTC+01:30"               -- ZoneId.of("UTC+01:30")
  "GMT+01:30"               -- ZoneId.of("GMT+01:30")

Обратите внимание, что этот метод идентичен appendZoneId(), за исключением механизма получения часового пояса.

Возвращает:

этот объект для цепочки вызовов, не null

См. также:

appendZoneText

public DateTimeFormatterBuilder appendZoneText(TextStyle textStyle)

Добавляет к форматтеру название часового пояса, например 'British Summer Time'.

Добавляет построителю инструкцию для форматирования/разбора текстового названия часового пояса.

При форматировании часовой пояс получается с помощью механизма, эквивалентного запросу к временному объекту с помощью TemporalQueries.zoneId(). Если часовой пояс является ZoneOffset, он выводится с использованием результата ZoneOffset.getId(). Если часовой пояс не является смещением, текстовое название ищется для локали, заданной в DateTimeFormatter. Если печатаемый временной объект представляет момент времени или локальную дату-время, не попадающую в разрыв или перекрытие при переходе на летнее время, текст будет соответствовать летнему или зимнему времени. Если поиск текста не даст подходящего результата, будет выведен ID. Если получить часовой пояс невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным.

При разборе принимается текстовое название часового пояса, его идентификатор или смещение. Многие текстовые названия часовых поясов неоднозначны: например, CST может обозначать как "Central Standard Time", так и "China Standard Time". В этом случае идентификатор часового пояса определяется региональной информацией из locale форматтера и стандартным идентификатором часового пояса для этой области, например America/New_York для восточного часового пояса США. В этом случае для указания набора предпочтительных ZoneId можно использовать appendZoneText(TextStyle, Set).

Параметры:: textStyle — используемый текстовый стиль, не null
Возвращает:: этот объект для цепочки вызовов, не null

appendZoneText

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

Добавляет к форматтеру название часового пояса, например 'British Summer Time'.

Добавляет построителю инструкцию для форматирования/разбора текстового названия часового пояса.

При форматировании часовой пояс получается с помощью механизма, эквивалентного запросу к временному объекту с помощью TemporalQueries.zoneId(). Если часовой пояс является ZoneOffset, он выводится с использованием результата ZoneOffset.getId(). Если часовой пояс не является смещением, текстовое название ищется для локали, заданной в DateTimeFormatter. Если печатаемый временной объект представляет момент времени или локальную дату-время, не попадающую в разрыв или перекрытие при переходе на летнее время, текст будет соответствовать летнему или зимнему времени. Если поиск текста не даст подходящего результата, будет выведен ID. Если получить часовой пояс невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным.

При разборе принимается текстовое название часового пояса, его идентификатор или смещение. Многие текстовые названия часовых поясов неоднозначны: например, CST может обозначать как "Central Standard Time", так и "China Standard Time". В этом случае идентификатор часового пояса определяется региональной информацией из locale форматтера и стандартным идентификатором часового пояса для этой области, например America/New_York для восточного часового пояса США. Этот метод также позволяет указать набор предпочтительных ZoneId для разбора. Сопоставленный предпочтительный идентификатор часового пояса будет использован, если разбираемое текстовое название часового пояса неоднозначно.

Если разобрать часовой пояс невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным.

Параметры:: textStyle — используемый текстовый стиль, не null; preferredZones — набор предпочтительных идентификаторов часовых поясов, не null
Возвращает:: этот объект для цепочки вызовов, не null

appendGenericZoneText

public DateTimeFormatterBuilder appendGenericZoneText(TextStyle textStyle)

Добавляет к форматтеру общее название часового пояса, например 'Pacific Time'.

Добавляет построителю инструкцию для форматирования/разбора общего текстового названия часового пояса. Общее название не меняется в течение года и не учитывает переходы на летнее время. Например, 'Pacific Time' — общее название, тогда как 'Pacific Standard Time' и 'Pacific Daylight Time' — конкретные названия; см. appendZoneText(TextStyle).

При форматировании часовой пояс получается с помощью механизма, эквивалентного запросу к временному объекту с помощью TemporalQueries.zoneId(). Если часовой пояс является ZoneOffset, он выводится с использованием результата ZoneOffset.getId(). Если часовой пояс не является смещением, текстовое название ищется для локали, заданной в DateTimeFormatter. Если поиск текста не даст подходящего результата, будет выведен ID. Если получить часовой пояс невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным.

Параметры:: textStyle — используемый текстовый стиль, не null
Возвращает:: этот объект для цепочки вызовов, не null
Начиная с версии:: 9

appendGenericZoneText

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

Добавляет к форматтеру общее название часового пояса, например 'Pacific Time'.

Этот метод также позволяет указать набор предпочтительных ZoneId для разбора. Сопоставленный предпочтительный идентификатор часового пояса будет использован, если разбираемое текстовое название часового пояса неоднозначно.

Подробные сведения о форматировании и разборе см. в разделе appendGenericZoneText(TextStyle).

Параметры:: textStyle — используемый текстовый стиль, не null; preferredZones — набор предпочтительных идентификаторов часовых поясов, не null
Возвращает:: этот объект для цепочки вызовов, не null
Начиная с версии:: 9

appendChronologyId

public DateTimeFormatterBuilder appendChronologyId()

Добавляет к форматтеру идентификатор хронологии, например 'ISO' или 'ThaiBuddhist'.

Добавляет построителю инструкцию для форматирования/разбора идентификатора хронологии.

При форматировании хронология получается с помощью механизма, эквивалентного запросу к временному объекту с помощью TemporalQueries.chronology(). Она выводится с использованием результата Chronology.getId(). Если получить хронологию невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным.

При разборе хронология разбирается и должна соответствовать одной из хронологий, перечисленных в Chronology.getAvailableChronologies(). Если разобрать хронологию невозможно, выбрасывается исключение, если только раздел форматтера не является необязательным. Анализатор использует настройку учёта регистра.

Возвращает:: этот объект для цепочки вызовов, не null

appendChronologyText

public DateTimeFormatterBuilder appendChronologyText(TextStyle textStyle)

Добавляет к форматтеру название хронологии.

При форматировании выводится название календарной системы. Если получить хронологию невозможно, будет выброшено исключение.

Параметры:: textStyle — используемый текстовый стиль, не null
Возвращает:: этот объект для цепочки вызовов, не null

appendLocalized

public DateTimeFormatterBuilder appendLocalized(FormatStyle dateStyle, FormatStyle timeStyle)

Добавляет к форматтеру локализованный шаблон даты и времени.

Добавляет построителю локализованный раздел, подходящий для вывода даты, времени или их сочетания. Формат локализованного раздела лениво определяется на основе четырёх элементов:

значения dateStyle, указанного для этого метода
значения timeStyle, указанного для этого метода
значения Locale из DateTimeFormatter
значения Chronology, выбирающего наилучший доступный вариант

При форматировании хронология получается из форматируемого временного объекта; её значение могло быть переопределено с помощью DateTimeFormatter.withChronology(Chronology). Для стилей FULL и LONG обычно требуется часовой пояс. При форматировании с использованием этих стилей должен быть доступен ZoneId — либо благодаря использованию ZonedDateTime, либо через DateTimeFormatter.withZone(ZoneId).

При разборе, если хронология уже разобрана, используется она. В противном случае используется значение по умолчанию из DateTimeFormatter.withChronology(Chronology), а при его отсутствии — IsoChronology.

Обратите внимание, что этот метод предоставляет функциональность, схожую с методами DateFormat, такими как DateFormat.getDateTimeInstance(int, int).

Параметры:: dateStyle — используемый стиль даты; null означает, что дата не требуется; timeStyle — используемый стиль времени; null означает, что время не требуется
Возвращает:: этот объект для цепочки вызовов, не null
Выбрасывает:: IllegalArgumentException — если оба стиля — даты и времени — равны null

appendLocalized

public DateTimeFormatterBuilder appendLocalized(String requestedTemplate)

Добавляет к форматтеру локализованный шаблон, используя запрошенный образец.

Добавляет построителю локализованный раздел, подходящий для вывода даты, времени или их сочетания. Формат локализованного раздела лениво определяется на основе трёх элементов:

значения requestedTemplate, указанного для этого метода
значения Locale из DateTimeFormatter
значения Chronology из DateTimeFormatter, если оно не переопределено

Запрошенный образец представляет собой последовательность типичных символов шаблона в каноническом порядке — от самой крупной единицы даты или времени к самой мелкой. Её можно выразить следующим регулярным выражением:

     "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' представляет поле месяца. Количество букв символа шаблона соответствует тем же правилам представления, например «число» или «текст», что и в разделе Шаблоны для форматирования и разбора. Другие символы шаблона в запрошенном образце недопустимы.

Сопоставление запрошенного образца с наиболее близким из доступных локализованных форматов определяется спецификацией Unicode LDML. Например, форматтер, созданный для запрошенного образца yMMM, отформатирует дату '2020-06-16' как 'Jun 2020' в локали US locale.

Параметры:

requestedTemplate — используемый запрошенный образец, не null

Возвращает:

этот объект для цепочки вызовов, не null

Выбрасывает:

IllegalArgumentException — если requestedTemplate недопустим

Начиная с версии:

Внешние спецификации

См. также:

appendLiteral

public DateTimeFormatterBuilder appendLiteral(char literal)

Добавляет в форматтер буквенный символ.

Этот символ будет выведен при форматировании.

Параметры:: literal — добавляемый буквенный символ, не null
Возвращает:: этот объект для цепочки вызовов, не null

appendLiteral

public DateTimeFormatterBuilder appendLiteral(String literal)

Добавляет в форматтер буквенную строку.

Эта строка будет выведена при форматировании.

Если буквенная строка пуста, в форматтер ничего не добавляется.

Параметры:: literal — добавляемая буквенная строка, не null
Возвращает:: этот объект для цепочки вызовов, не null

appendDayPeriodText

public DateTimeFormatterBuilder appendDayPeriodText(TextStyle style)

Добавляет текст периода суток в форматтер.

Этот метод добавляет в построитель инструкцию для форматирования/разбора текстового названия периода суток. Периоды суток определены в элементе «периоды суток» LDML.

При форматировании период суток получается из HOUR_OF_DAY и, если они существуют, дополнительно из MINUTE_OF_HOUR. Он сопоставляется с типом периода суток, определённым в LDML, например «morning1», а затем преобразуется в текст. И сопоставление с типом периода суток, и его перевод зависят от локали форматтера.

При разборе сначала текст разбирается в тип периода суток. Затем разобранный период суток объединяется с другими полями для создания LocalTime на этапе разрешения. Если присутствует поле HOUR_OF_AMPM, оно объединяется с периодом суток для создания HOUR_OF_DAY с учётом любого значения MINUTE_OF_HOUR. Если присутствует 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 исключение не выбрасывается, а разобранный период суток игнорируется.

Тип «midnight» допускает как «00:00» в качестве начала суток, так и «24:00» в качестве конца суток, если они допустимы для разрешённого поля часа.

Параметры:

style — используемый стиль текста, не null

Возвращает:

этот объект для цепочки вызовов, не null

С версии:

Внешние спецификации

append

public DateTimeFormatterBuilder append(DateTimeFormatter formatter)

Добавляет все элементы форматтера в построитель.

Этот метод имеет тот же эффект, что и добавление каждой составной части форматтера непосредственно в этот построитель.

Параметры:: formatter — добавляемый форматтер, не null
Возвращает:: этот объект для цепочки вызовов, не null

appendOptional

public DateTimeFormatterBuilder appendOptional(DateTimeFormatter formatter)

Добавляет в построитель форматтер для необязательного форматирования/разбора.

Этот метод имеет тот же эффект, что и добавление каждой составной части непосредственно в этот построитель, окружённой вызовами optionalStart() и optionalEnd().

Форматтер выполняет форматирование, если доступны данные для всех содержащихся в нём полей. Форматтер выполняет разбор, если строка соответствует шаблону; в противном случае ошибка не возвращается.

Параметры:: formatter — добавляемый форматтер, не null
Возвращает:: этот объект для цепочки вызовов, не 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)

Идентификатор часового пояса: буквы шаблона для вывода 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» по-разному разбирают годы из двух цифр и годы более чем из 4 цифр. Добавлены буквы шаблона «n», «A», «N» и «p». Числовые типы отклоняют слишком большие числа.

Параметры:: pattern — добавляемый шаблон, не null
Возвращает:: этот объект для цепочки вызовов, не null
Выбрасывает:: IllegalArgumentException — если шаблон недопустим

padNext

public DateTimeFormatterBuilder padNext(int padWidth)

Указывает, что следующий добавленный механизм вывода/разбора должен дополняться пробелами до фиксированной ширины.

Для дополнения до фиксированной ширины используются пробелы.

При форматировании оформленный элемент выводится, а затем дополняется до указанной ширины. Если ширина дополнения превышена, при форматировании будет выброшено исключение.

При разборе выполняется разбор дополнения и оформленного элемента. Если разбор выполняется в нестрогом режиме, ширина дополнения считается максимальной. Дополнение разбирается жадно. Поэтому, если оформленный элемент начинается с символа дополнения, он не будет разобран.

Параметры:: padWidth — ширина дополнения, не менее 1
Возвращает:: этот объект для цепочки вызовов, не null
Выбрасывает:: IllegalArgumentException — если ширина дополнения слишком мала

padNext

public DateTimeFormatterBuilder padNext(int padWidth, char padChar)

Указывает, что следующий добавленный механизм вывода/разбора должен дополняться до фиксированной ширины.

Это дополнение предназначено для вариантов, отличных от дополнения нулями. Дополнение нулями следует выполнять с помощью методов appendValue.

При разборе выполняется разбор дополнения и оформленного элемента. Если разбор выполняется в нестрогом режиме, ширина дополнения считается максимальной. Если разбор выполняется без учёта регистра, символ дополнения сопоставляется без учёта регистра. Дополнение разбирается жадно. Поэтому, если оформленный элемент начинается с символа дополнения, он не будет разобран.

Параметры:: padWidth — ширина дополнения, не менее 1; padChar — символ дополнения
Возвращает:: этот объект для цепочки вызовов, не null
Выбрасывает:: IllegalArgumentException — если ширина дополнения слишком мала

optionalStart

public DateTimeFormatterBuilder optionalStart()

Отмечает начало необязательной секции.

Форматируемый вывод может включать необязательные секции, в том числе вложенные. Необязательная секция начинается вызовом этого метода и заканчивается вызовом optionalEnd() либо завершением процесса построения.

Все элементы необязательной секции считаются необязательными. При форматировании секция выводится, только если в TemporalAccessor доступны данные для всех элементов секции. При разборе вся секция может отсутствовать в разбираемой строке.

Например, рассмотрим построитель, настроенный как builder.appendValue(HOUR_OF_DAY,2).optionalStart().appendValue(MINUTE_OF_HOUR,2). Необязательная секция автоматически завершается в конце построителя. При форматировании минуты выводятся только в том случае, если их значение можно получить из даты и времени. При разборе входные данные будут успешно разобраны независимо от того, присутствуют ли минуты.

Возвращает:: этот объект для цепочки вызовов, не null

optionalEnd

public DateTimeFormatterBuilder optionalEnd()

Завершает необязательную секцию.

Форматируемый вывод может включать необязательные секции, в том числе вложенные. Необязательная секция начинается вызовом optionalStart() и завершается этим методом (либо в конце построителя).

Вызов этого метода, если ранее не вызывался optionalStart, приведёт к исключению. Вызов этого метода сразу после вызова optionalStart никак не повлияет на форматтер, кроме завершения (пустой) необязательной секции.

Например, рассмотрим построитель, настроенный как builder.appendValue(HOUR_OF_DAY,2).optionalStart().appendValue(MINUTE_OF_HOUR,2).optionalEnd(). При форматировании минуты выводятся только в том случае, если их значение можно получить из даты и времени. При разборе входные данные будут успешно разобраны независимо от того, присутствуют ли минуты.

Возвращает:: этот объект для цепочки вызовов, не null
Выбрасывает:: IllegalStateException — если ранее не вызывался optionalStart

toFormatter

public DateTimeFormatter toFormatter()

Завершает работу этого построителя, создавая DateTimeFormatter с локалью по умолчанию.

Будет создан форматтер с локалью FORMAT по умолчанию. Числа будут выводиться и разбираться с использованием стандартного DecimalStyle. Стиль разрешения будет SMART.

Перед созданием форматтера этот метод завершит все открытые необязательные секции, многократно вызывая optionalEnd().

При необходимости этот построитель можно использовать и после создания форматтера, хотя его состояние может измениться в результате вызовов optionalEnd.

Возвращает:: созданный форматтер, не null

toFormatter

public DateTimeFormatter toFormatter(Locale locale)

Завершает работу этого построителя, создавая DateTimeFormatter с указанной локалью.

Будет создан форматтер с указанной локалью. Числа будут выводиться и разбираться с использованием стандартного DecimalStyle. Стиль разрешения будет SMART.

Параметры:: locale — локаль для форматирования, не null
Возвращает:: созданный форматтер, не null

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.