Класс 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 extensions, шаблон форматирования переопределяется шаблоном, соответствующим региону.

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

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

parseCaseInsensitive

public DateTimeFormatterBuilder parseCaseInsensitive()

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

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

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

parseStrict

public DateTimeFormatterBuilder parseStrict()

Изменяет стиль разбора на строгий для оставшейся части форматировщика.

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

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

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

parseLenient

public DateTimeFormatterBuilder parseLenient()

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

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

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

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

parseDefaulting

public DateTimeFormatterBuilder parseDefaulting(TemporalField field, long value)

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

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

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

Во время форматирования этот метод не оказывает никакого влияния.

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

Параметры:: field - поле, для которого нужно установить значение по умолчанию, не null; value - значение по умолчанию для поля
Возвращает:: this для цепочки, не null

appendValue

public DateTimeFormatterBuilder appendValue(TemporalField field)

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

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

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

Парсер для значения переменной длины, как этот, обычно ведёт себя жадно, требуя одной цифры, но принимая как можно больше цифр. Это поведение может быть изменено 'adjacent value parsing'. Полные подробности см. в appendValue(java.time.temporal.TemporalField, int).

Параметры:: field - поле для добавления, не null
Возвращает:: this для цепочки, не 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', в форматтер, отклоняя идентификатор часового пояса, если это идентификатор смещения.

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

Во время форматирования часовой пояс извлекается с помощью механизма, эквивалентного запросу временной области с 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 может относиться как к «Центральному стандартному времени», так и к «Китайскому стандартному времени». В этом случае идентификатор зоны определяется информацией о регионе из 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 может относиться как к «Центральному стандартному времени», так и к «Китайскому стандартному времени». В этом случае идентификатор зоны определяется информацией о регионе из 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 может относиться как к «Центральному стандартному времени», так и к «Китайскому стандартному времени». В этом случае идентификатор зоны определяется информацией о регионе из 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(). Если хронология не может быть обработана, то выбрасывается исключение, если раздел форматировщика не является необязательным. Парсер использует настройку чувствительности к регистру.

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

appendChronologyText

public DateTimeFormatterBuilder appendChronologyText(TextStyle textStyle)

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

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

Parameters:: textStyle - стиль текста для использования, не null
Returns:: 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).

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

Parameters:

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

Returns:

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

Throws:

IllegalArgumentException - если requestedTemplate некорректно

Since:

External Specifications

See Also:

appendLiteral

public DateTimeFormatterBuilder appendLiteral(char literal)

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

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

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

appendLiteral

public DateTimeFormatterBuilder appendLiteral(String literal)

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

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

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

Parameters:: literal - литерал для добавления, не null
Returns:: 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. Если решённое время конфликтует с периодом дня, DateTimeException выбрасывается в режиме STRICT и SMART. В режиме LENIENT исключение не выбрасывается, и обработанный период дня игнорируется.

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

Parameters:

style - стиль текста для использования, не null

Returns:

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

Since:

External Specifications

append

public DateTimeFormatterBuilder append(DateTimeFormatter formatter)

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

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

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

appendOptional

public DateTimeFormatterBuilder appendOptional(DateTimeFormatter formatter)

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

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

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

Parameters:: formatter - форматировщик для добавления, не null
Returns:: 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()

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

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

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

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

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

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

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

toFormatter

public DateTimeFormatter toFormatter(Locale locale)

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

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

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

© 1993, 2023, 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/21/docs/api/java.base/java/time/format/DateTimeFormatterBuilder.html