Класс 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

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

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 — хронология Chronology, не null; locale — локаль, не null
Возвращает:: шаблон форматирования, специфичный для локали и Chronology
Исключения:: IllegalArgumentException — если dateStyle и timeStyle оба равны null

getLocalizedDateTimePattern

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

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

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

Параметры:

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

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

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

Возвращает:

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

Исключения:

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. При разборе для анализа смещения будет использоваться поведение appendOffsetId(), при необходимости преобразующее момент времени в 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 для восточного часового пояса США. В этом случае можно использовать appendZoneText(TextStyle, Set), чтобы указать набор предпочтительных ZoneId.

Параметры:: 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. Если получить часовой пояс не удаётся, выбрасывается исключение, если только раздел форматтера не является необязательным.

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

Параметры:: 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' соответствуют CLDR/LDML Unicode. В отличие от этого, SimpleDateFormat использует 'u' для обозначения числового дня недели. Символы шаблона 'y' и 'Y' по-разному разбирают годы, заданные двумя и более чем четырьмя цифрами. Добавлены символы шаблона '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.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/time/format/DateTimeFormatterBuilder.html