Класс DateTimeFormatterBuilder

java.lang.Object

java.time.format.DateTimeFormatterBuilder

public final class DateTimeFormatterBuilder extends Object

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

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

Основные элементы даты и времени могут быть добавлены:

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

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

Наконец, может быть использован сокращённый шаблон, в основном совместимый с 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`, используя указанную локаль.

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

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

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

DateTimeFormatterBuilder

public DateTimeFormatterBuilder()

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

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

getLocalizedDateTimePattern

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

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

Если в локали указан параметр «rg» (переопределение региона) с Unicode расширениями, шаблон форматирования переопределяется шаблоном, соответствующим региону.

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

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

Parameters:: field - поле для добавления, не null; width - ширина выводимого поля, от 1 до 19
Returns:: this, для цепочки, не null
Throws:: 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). В этом случае происходит форматирование и парсинг, описанные там.

Parameters:: field - поле для добавления, не null; minWidth - минимальная ширина поля выводимого значения, от 1 до 19; maxWidth - максимальная ширина поля выводимого значения, от 1 до 19; signStyle - стиль вывода знаков «плюс»/«минус», не null
Returns:: this, для цепочки, не null
Throws:: 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 и абсолютные значения для значений вне этого диапазона.

Например, для baseValue = 1980 и width = 2 допустимые значения находятся в диапазоне от 1980 до 2079. При парсинге текст "12" приводит к значению 2012, поскольку это значение в диапазоне, где последние две цифры — «12». В отличие от этого, парсинг текста "1915" приводит к значению 1915.

Parameters:: field - поле для добавления, не null; width - ширина поля для вывода и парсинга, от 1 до 10; maxWidth - максимальная ширина поля для вывода, от 1 до 10; baseValue - базовое значение диапазона допустимых значений
Returns:: this, для цепочки, не null
Throws:: 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, используемого ниже.

Parameters:: field - поле для добавления, не null; width - ширина поля для вывода и парсинга, от 1 до 10; maxWidth - максимальная ширина поля для вывода, от 1 до 10; baseDate - базовая дата, используемая для расчёта базового значения диапазона допустимых значений в календаре, не null
Returns:: this, для цепочки, не null
Throws:: IllegalArgumentException - если ширина или базовое значение некорректны

appendFraction

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

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

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

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

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

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

Parameters:: field - поле для добавления, не null; minWidth - минимальная ширина поля, не включая десятичную точку, от 0 до 9; maxWidth - максимальная ширина поля, не включая десятичную точку, от 1 до 9; decimalPoint - нужно ли выводить локальный символ десятичной точки
Returns:: this, для цепочки вызовов, не null
Throws:: IllegalArgumentException - если у поля есть переменный набор допустимых значений или какая-либо ширина недопустима

appendText

public DateTimeFormatterBuilder appendText(TemporalField field)

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

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

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

Parameters:: field - поле для добавления, не null
Returns:: this, для цепочки вызовов, не null

appendText

public DateTimeFormatterBuilder appendText(TemporalField field, TextStyle textStyle)

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

Parameters:: field - поле для добавления, не null; textStyle - стиль текста для использования, не null
Returns:: this, для цепочки вызовов, не null

appendText

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

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

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

Предоставление карты текста обеспечивает значительную гибкость в форматировании и парсинге. Например, устаревшее приложение может потребовать или предоставить месяцы года как "JNY", "FBY", "MCH" и т. д. Они не соответствуют стандартному набору текста для локальных названий месяцев. Используя этот метод, можно создать карту, которая определяет связь между каждым значением и текстом:

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

Другое использование может быть в выводе значения с суффиксом, например, "1-е", "2-е", "3-е" или в виде римских цифр "I", "II", "III", "IV".

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

Parameters:: field - поле для добавления, не null; textLookup - карта от значения к тексту
Returns:: this, для цепочки вызовов, не 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).

Returns:: this, для цепочки вызовов, не null

appendInstant

public DateTimeFormatterBuilder appendInstant(int fractionalDigits)

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

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

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

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

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

Parameters:: fractionalDigits - количество цифр дробной части секунды для форматирования, от 0 до 9 или -1 для использования необходимого количества цифр
Returns:: this, для цепочки вызовов, не null
Throws:: IllegalArgumentException - если количество дробных цифр некорректно

appendOffsetId

public DateTimeFormatterBuilder appendOffsetId()

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

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

Returns:: this, для цепочки вызовов, не 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 принимаются три формата - текст "без смещения" и плюсовые и минусовые версии нуля, определённые шаблоном.

Parameters:: pattern - используемый шаблон, не null; noOffsetText - текст для использования, когда смещение равно нулю, не null
Returns:: this, для цепочки вызовов, не null
Throws:: IllegalArgumentException - если шаблон недопустим

appendLocalizedOffset

public DateTimeFormatterBuilder appendLocalizedOffset(TextStyle style)

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

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

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

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

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

Parameters:: style - используемый стиль формата, не null
Returns:: this, для цепочки вызовов, не null
Throws:: IllegalArgumentException - если стиль не является ни full, ни short

appendZoneId

public DateTimeFormatterBuilder appendZoneId()

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

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

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

Во время парсинга текст должен соответствовать известному часовому поясу или смещению. Существуют два типа идентификаторов часового пояса: основанные на смещении, такие как '+01:30', и основанные на регионе, такие как 'Europe/London'. Они анализируются по-разному. Если анализ начинается с '+', '-', 'UT', 'UTC' или 'GMT', то анализатор ожидает часовой пояс, основанный на смещении, и не будет соответствовать часовым поясам, основанным на регионе. Идентификатор смещения, например '+02:30', может находиться в начале анализа или быть префиксом 'UT', 'UTC' или 'GMT'. Анализ идентификатора смещения эквивалентен использованию 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"                -- ZoneOffset.of("+01:30")
   "UTC+01:30"               -- ZoneOffset.of("+01:30")
   "GMT+01:30"               -- ZoneOffset.of("+01:30")

Returns:

this, для цепочки вызовов, не null

See Also:

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

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

Returns:

this, для цепочки вызовов, не null

See Also:

appendZoneOrOffsetId

public DateTimeFormatterBuilder appendZoneOrOffsetId()

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

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

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

Во время парсинга текст должен соответствовать известной зоне или смещению. Существует два типа идентификаторов зоны: основанные на смещении, такие как '+01:30', и основанные на регионе, такие как 'Europe/London'. Они парсятся по-разному. Если парсинг начинается с '+', '-', 'UT', 'UTC' или 'GMT', то парсер ожидает зону, основанную на смещении, и не будет соответствовать зонам, основанным на регионе. Идентификатор смещения, например '+02:30', может быть в начале парсинга или быть префиксным 'UT', 'UTC' или 'GMT'. Парсинг идентификатора смещения эквивалентен использованию 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"                -- ZoneOffset.of("UT+01:30")
   "UTC+01:30"               -- ZoneOffset.of("UTC+01:30")
   "GMT+01:30"               -- ZoneOffset.of("GMT+01:30")

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

Returns:

this, для цепочки вызовов, не null

See Also:

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 в такой ситуации.

Parameters:: textStyle - стиль текста, используемый, не null
Returns:: this, для цепочки вызовов, не null

appendZoneText

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

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

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

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

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

Parameters:: textStyle - стиль текста, используемый, не null; preferredZones - набор предпочтительных идентификаторов зон, не null
Returns:: this, для цепочки вызовов, не null

appendGenericZoneText

public DateTimeFormatterBuilder appendGenericZoneText(TextStyle textStyle)

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

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

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

Parameters:: textStyle - стиль текста, используемый, не null
Returns:: this, для цепочки вызовов, не null
Since:: 9

appendGenericZoneText

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

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

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

См. appendGenericZoneText(TextStyle) для подробной информации о форматировании и парсинге.

Parameters:: textStyle - стиль текста, используемый, не null; preferredZones - набор предпочтительных идентификаторов зон, не null
Returns:: this, для цепочки вызовов, не null
Since:: 9

appendChronologyId

public DateTimeFormatterBuilder appendChronologyId()

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

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

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

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

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

appendChronologyText

public DateTimeFormatterBuilder appendChronologyText(TextStyle textStyle)

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

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

Параметры:: textStyle - стиль текста для использования, не null
Возвращает:: this, для цепочки вызовов, не null

appendLocalized

public DateTimeFormatterBuilder appendLocalized(FormatStyle dateStyle, FormatStyle timeStyle)

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

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

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

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

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

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

Параметры:: dateStyle - стиль даты для использования, null означает, что дата не требуется; timeStyle - стиль времени для использования, null означает, что время не требуется
Возвращает:: this, для цепочки вызовов, не 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' представляет поле месяца. Количество букв символа шаблона соответствует такому же представлению, как и в разделе Шаблоны для форматирования и разбора. Другие символы шаблона в запрошенном шаблоне являются недопустимыми.

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

Параметры:

requestedTemplate - запрошенный шаблон для использования, не null

Возвращает:

this, для цепочки вызовов, не null

Исключение:

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

С:

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

См. также:

appendLiteral

public DateTimeFormatterBuilder appendLiteral(char literal)

Добавляет символ-литерал в форматер.

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

Параметры:: literal - литерал для добавления, не null
Возвращает:: this, для цепочки вызовов, не null

appendLiteral

public DateTimeFormatterBuilder appendLiteral(String literal)

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

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

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

Параметры:: literal - литерал для добавления, не null
Возвращает:: this, для цепочки вызовов, не null

appendDayPeriodText

public DateTimeFormatterBuilder appendDayPeriodText(TextStyle style)

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

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

Во время форматирования период дня извлекается из 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

Возвращает:

this, для цепочки вызовов, не null

С:

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

append

public DateTimeFormatterBuilder append(DateTimeFormatter formatter)

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

Этот метод имеет тот же эффект, что и добавление каждого составляющего элемента форматера непосредственно в этот билдер.

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

appendOptional

public DateTimeFormatterBuilder appendOptional(DateTimeFormatter formatter)

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

Этот метод имеет тот же эффект, что и добавление каждого составляющего элемента непосредственно в этот билдер, окружённого optionalStart() и optionalEnd().

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

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

appendPattern

public DateTimeFormatterBuilder appendPattern(String pattern)

Добавляет элементы, определённые указанным шаблоном, в билдер.

Все буквы от 'A' до 'Z' и от 'a' до 'z' зарезервированы как символы шаблона. Символы '#', '{' и '}' зарезервированы для будущего использования. Символы '[' и ']' указывают на необязательные шаблоны. Определены следующие символы шаблона:

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

   Q/q     quarter-of-year             number/text       3; 03; Q3; 3rd quarter
   Y       week-based-year             year              1996; 96
   w       week-of-week-based-year     number            27
   W       week-of-month               number            4
   E       day-of-week                 text              Tue; Tuesday; T
   e/c     localized day-of-week       number/text       2; 02; Tue; Tuesday; T
   F       day-of-week-in-month        number            3

   a       am-pm-of-day                text              PM
   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' парсят двухзначные и более четырёхзначные годы по-разному. Символы шаблона 'n', 'A', 'N' и 'p' добавлены. Типы чисел будут отклонять большие числа.

Parameters:: pattern - шаблон для добавления, не null
Returns:: this, для цепочки вызовов, не null
Throws:: IllegalArgumentException - если шаблон недействителен

padNext

public DateTimeFormatterBuilder padNext(int padWidth)

Принудительно добавляет пробелы для следующего принтера/парсера до фиксированной ширины.

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

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

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

Parameters:: padWidth - ширина дополнения, 1 или больше
Returns:: this, для цепочки вызовов, не null
Throws:: IllegalArgumentException - если ширина дополнения слишком мала

padNext

public DateTimeFormatterBuilder padNext(int padWidth, char padChar)

Принудительно добавляет символы для следующего принтера/парсера до фиксированной ширины.

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

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

Parameters:: padWidth - ширина дополнения, 1 или больше; padChar - символ дополнения
Returns:: this, для цепочки вызовов, не null
Throws:: IllegalArgumentException - если ширина дополнения слишком мала

optionalStart

public DateTimeFormatterBuilder optionalStart()

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

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

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

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

Returns:: this, для цепочки вызовов, не null

optionalEnd

public DateTimeFormatterBuilder optionalEnd()

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

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

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

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

Returns:: this, для цепочки вызовов, не null
Throws:: IllegalStateException - если не было предыдущего вызова optionalStart

toFormatter

public DateTimeFormatter toFormatter()

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

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

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

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

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

toFormatter

public DateTimeFormatter toFormatter(Locale locale)

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

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

Parameters:: locale - локаль для использования при форматировании, не null
Returns:: созданный форматировщик, не 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/time/format/DateTimeFormatterBuilder.html