Класс DateTimeFormatterBuilder

public final class DateTimeFormatterBuilder
extends Object

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

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

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

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

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

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

Конструкторы

Конструктор Описание
DateTimeFormatterBuilder()

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

Методы

Модификатор и тип Метод Описание
DateTimeFormatterBuilder append​(DateTimeFormatter formatter)

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

Добавляет идентификатор хронологии, например 'ISO' или 'ThaiBuddhist', к форматеру.
DateTimeFormatterBuilder appendChronologyText​(TextStyle textStyle)

Добавляет имя хронологии в форматер.
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​(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​(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 - если и dateStyle, и timeStyle равны null

parseCaseSensitive

public DateTimeFormatterBuilder parseCaseSensitive()

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

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

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

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

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

parseCaseInsensitive

public DateTimeFormatterBuilder parseCaseInsensitive()

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

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

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

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

parseStrict

public DateTimeFormatterBuilder parseStrict()

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

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

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

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

parseLenient

public DateTimeFormatterBuilder parseLenient()

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

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

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

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

parseDefaulting

public DateTimeFormatterBuilder parseDefaulting(TemporalField field,
                                                long value)

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

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

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

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

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

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

appendValue

public DateTimeFormatterBuilder appendValue(TemporalField field)

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

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

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

Парсер для значения с переменной шириной, такого как это, обычно ведёт себя жадно, требуя одной цифры, но принимая столько цифр, сколько возможно. Это поведение может повлиять на «смежный разбор значений». Смотрите 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. Без смежного разбора значений год жадно проанализировал бы все шесть цифр и ничего не оставил бы для месяца.

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

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

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

appendValue

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

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

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

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

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

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

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

Параметры:
field - поле для добавления, не null
minWidth - минимальная ширина поля вывода, от 1 до 19
maxWidth - максимальная ширина поля вывода, от 1 до 19
signStyle - стиль вывода знака «плюс/минус», не null
Возвращает:
this, для цепочки вызовов, не null
Исключение:
IllegalArgumentException - если ширины некорректны

appendValueReduced

public DateTimeFormatterBuilder appendValueReduced(TemporalField field,
                                                   int width,
                                                   int maxWidth,
                                                   int baseValue)

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

Поскольку поля, такие как год, различаются в зависимости от хронологии, рекомендуется использовать вариант метода appendValueReduced(TemporalField, int, int, ChronoLocalDate) с типом данных date в большинстве случаев. Этот вариант подходит для простых полей или работы только с ISO-хронологией.

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

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

Например, базовое значение 1980 и ширина 2 будут иметь допустимые значения от 1980 до 2079. При разборе текст "12" приведет к значению 2012, так как это значение в диапазоне, где последние два символа — "12". В отличие от этого, разбор текста "1915" приведет к значению 1915.

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

appendValueReduced

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

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

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

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

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

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

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

Например, базовое значение 1980 и ширина 2 будут иметь допустимые значения от 1980 до 2079. При разборе текст "12" приведет к значению 2012, так как это значение в диапазоне, где последние два символа — "12". В отличие от этого, разбор текста "1915" приведет к значению 1915.

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

appendFraction

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

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

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

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

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

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

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

appendText

public DateTimeFormatterBuilder appendText(TemporalField field)

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

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

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

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

appendText

public DateTimeFormatterBuilder appendText(TemporalField field,
                                           TextStyle textStyle)

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

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

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

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

appendText

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

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

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

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

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

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

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

Параметры:
field - поле для добавления, не null
textLookup - карта из значения в текст
Возвращает:
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() для получения подробных сведений.

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

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

appendInstant

public DateTimeFormatterBuilder appendInstant(int fractionalDigits)

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

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

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

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

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

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

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

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

appendOffsetId

public DateTimeFormatterBuilder appendOffsetId()

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

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

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

appendOffset

public DateTimeFormatterBuilder appendOffset(String pattern,
                                             String noOffsetText)

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

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

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

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

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

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

  • +HH - только час, игнорируя минуты и секунды
  • +HHmm - час, с минутами, если они не нулевые, игнорируя секунды, без двоеточий
  • +HH:mm - час, с минутами, если они не нулевые, игнорируя секунды, с двоеточием
  • +HHMM - час и минуты, игнорируя секунды, без двоеточий
  • +HH:MM - час и минуты, игнорируя секунды, с двоеточием
  • +HHMMss - час и минуты, со секундами, если они не нулевые, без двоеточий
  • +HH:MM:ss - час и минуты, со секундами, если они не нулевые, с двоеточием
  • +HHMMSS - час, минуты и секунды, без двоеточий
  • +HH:MM:SS - час, минуты и секунды, с двоеточием
  • +HHmmss - час, с минутами, если они не нулевые, или с минутами и секундами, если они не нулевые, без двоеточий
  • +HH:mm:ss - час, с минутами, если они не нулевые, или с минутами и секундами, если они не нулевые, с двоеточием
  • +H - только час, игнорируя минуты и секунды
  • +Hmm - час, с минутами, если они не нулевые, игнорируя секунды, без двоеточий
  • +H:mm - час, с минутами, если они не нулевые, игнорируя секунды, с двоеточием
  • +HMM - час и минуты, игнорируя секунды, без двоеточий
  • +H:MM - час и минуты, игнорируя секунды, с двоеточием
  • +HMMss - час и минуты, со секундами, если они не нулевые, без двоеточий
  • +H:MM:ss - час и минуты, со секундами, если они не нулевые, с двоеточием
  • +HMMSS - час, минуты и секунды, без двоеточий
  • +H:MM:SS - час, минуты и секунды, с двоеточием
  • +Hmmss - час, с минутами, если они не нулевые, или с минутами и секундами, если они не нулевые, без двоеточий
  • +H:mm:ss - час, с минутами, если они не нулевые, или с минутами и секундами, если они не нулевые, с двоеточием
Шаблоны, содержащие «HH», будут форматировать и анализировать двухзначные часы, дополненные нулями при необходимости. Шаблоны, содержащие «H», будут форматировать без дополнения нулями, а анализировать одну или две цифры. В режиме мягкого анализа парсер будет жадным и анализировать максимальное количество возможных цифр. Текст «без смещения» определяет, какой текст выводится, когда общее количество полей смещения, которые нужно вывести, равно нулю. Примеры значений включают «Z», «+00:00», «UTC» или «GMT». Три формата принимаются для анализа UTC — текст «без смещения» и плюс и минус версии нуля, определенные шаблоном.
Параметры:
pattern - используемый шаблон, не null
noOffsetText - текст, используемый, когда смещение равно нулю, не null
Возвращает:
this, для цепочки вызовов, не null
Исключения:
IllegalArgumentException - если шаблон недопустим

appendLocalizedOffset

public DateTimeFormatterBuilder appendLocalizedOffset(TextStyle style)

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

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

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

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

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

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

appendZoneId

public DateTimeFormatterBuilder appendZoneId()

Добавляет идентификатор часового пояса, например «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")
Возвращает:
this, для цепочки вызовов, не null
См. также:
appendZoneRegionId()

appendZoneRegionId

public DateTimeFormatterBuilder appendZoneRegionId()

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

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

Во время форматирования зона определяется с помощью механизма, эквивалентного запросу к временной метке с помощью TemporalQueries.zoneId(). Если зона является ZoneOffset или её невозможно получить, то выбрасывается исключение, если этот раздел форматировщика не является необязательным. Если зона не является смещением, то зона будет выведена с использованием идентификатора зоны из 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")

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

Возвращает:
this, для цепочки вызовов, не null
См. также:
appendZoneId()

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() за исключением механизма получения зоны.

Возвращает:
this, для цепочки вызовов, не null
См. также:
appendZoneId()

appendZoneText

public DateTimeFormatterBuilder appendZoneText(TextStyle textStyle)

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

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

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

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

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

appendZoneText

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

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

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

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

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

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

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

appendGenericZoneText

public DateTimeFormatterBuilder appendGenericZoneText(TextStyle textStyle)

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

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

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

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

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

appendGenericZoneText

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

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

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

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

appendLiteral

public DateTimeFormatterBuilder appendLiteral(char literal)

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

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

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

appendLiteral

public DateTimeFormatterBuilder appendLiteral(String literal)

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

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

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

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

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
   h       clock-hour-of-am-pm (1-12)  number            12
   K       hour-of-am-pm (0-11)        number            0
   k       clock-hour-of-day (1-24)    number            24

   H       hour-of-day (0-23)          number            0
   m       minute-of-hour              number            30
   s       second-of-minute            number            55
   S       fraction-of-second          fraction          978
   A       milli-of-day                number            1234
   n       nano-of-second              number            987654321
   N       nano-of-day                 number            1234000000

   V       time-zone ID                zone-id           America/Los_Angeles; Z; -08:30
   v       generic time-zone name      zone-name         PT, Pacific Time
   z       time-zone name              zone-name         Pacific Standard Time; PST
   O       localized zone-offset       offset-O          GMT+8; GMT+08:00; UTC-08:00;
   X       zone-offset 'Z' for zero    offset-X          Z; -08; -0830; -08:30; -083015; -08:30:15
   x       zone-offset                 offset-x          +0000; -08; -0830; -08:30; -083015; -08:30:15
   Z       zone-offset                 offset-Z          +0000; -0800; -08:00

   p       pad next                    pad modifier      1

   '       escape for text             delimiter
   ''      single quote                literal           '
   [       optional section start
   ]       optional section end
   #       reserved for future use
   {       reserved for future use
   }       reserved for future use

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

Поля даты: Символы шаблона для вывода даты.

Pattern  Count  Equivalent builder methods
  -------  -----  --------------------------
    G       1      appendText(ChronoField.ERA, TextStyle.SHORT)
    GG      2      appendText(ChronoField.ERA, TextStyle.SHORT)
    GGG     3      appendText(ChronoField.ERA, TextStyle.SHORT)
    GGGG    4      appendText(ChronoField.ERA, TextStyle.FULL)
    GGGGG   5      appendText(ChronoField.ERA, TextStyle.NARROW)

    u       1      appendValue(ChronoField.YEAR, 1, 19, SignStyle.NORMAL)
    uu      2      appendValueReduced(ChronoField.YEAR, 2, 2000)
    uuu     3      appendValue(ChronoField.YEAR, 3, 19, SignStyle.NORMAL)
    u..u    4..n   appendValue(ChronoField.YEAR, n, 19, SignStyle.EXCEEDS_PAD)
    y       1      appendValue(ChronoField.YEAR_OF_ERA, 1, 19, SignStyle.NORMAL)
    yy      2      appendValueReduced(ChronoField.YEAR_OF_ERA, 2, 2000)
    yyy     3      appendValue(ChronoField.YEAR_OF_ERA, 3, 19, SignStyle.NORMAL)
    y..y    4..n   appendValue(ChronoField.YEAR_OF_ERA, n, 19, SignStyle.EXCEEDS_PAD)
    Y       1      append special localized WeekFields element for numeric week-based-year
    YY      2      append special localized WeekFields element for reduced numeric week-based-year 2 digits
    YYY     3      append special localized WeekFields element for numeric week-based-year (3, 19, SignStyle.NORMAL)
    Y..Y    4..n   append special localized WeekFields element for numeric week-based-year (n, 19, SignStyle.EXCEEDS_PAD)

    Q       1      appendValue(IsoFields.QUARTER_OF_YEAR)
    QQ      2      appendValue(IsoFields.QUARTER_OF_YEAR, 2)
    QQQ     3      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.SHORT)
    QQQQ    4      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.FULL)
    QQQQQ   5      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.NARROW)
    q       1      appendValue(IsoFields.QUARTER_OF_YEAR)
    qq      2      appendValue(IsoFields.QUARTER_OF_YEAR, 2)
    qqq     3      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.SHORT_STANDALONE)
    qqqq    4      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.FULL_STANDALONE)
    qqqqq   5      appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.NARROW_STANDALONE)

    M       1      appendValue(ChronoField.MONTH_OF_YEAR)
    MM      2      appendValue(ChronoField.MONTH_OF_YEAR, 2)
    MMM     3      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.SHORT)
    MMMM    4      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.FULL)
    MMMMM   5      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.NARROW)
    L       1      appendValue(ChronoField.MONTH_OF_YEAR)
    LL      2      appendValue(ChronoField.MONTH_OF_YEAR, 2)
    LLL     3      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.SHORT_STANDALONE)
    LLLL    4      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.FULL_STANDALONE)
    LLLLL   5      appendText(ChronoField.MONTH_OF_YEAR, TextStyle.NARROW_STANDALONE)

    w       1      append special localized WeekFields element for numeric week-of-year
    ww      2      append special localized WeekFields element for numeric week-of-year, zero-padded
    W       1      append special localized WeekFields element for numeric week-of-month
    d       1      appendValue(ChronoField.DAY_OF_MONTH)
    dd      2      appendValue(ChronoField.DAY_OF_MONTH, 2)
    D       1      appendValue(ChronoField.DAY_OF_YEAR)
    DD      2      appendValue(ChronoField.DAY_OF_YEAR, 2, 3, SignStyle.NOT_NEGATIVE)
    DDD     3      appendValue(ChronoField.DAY_OF_YEAR, 3)
    F       1      appendValue(ChronoField.ALIGNED_DAY_OF_WEEK_IN_MONTH)
    g..g    1..n   appendValue(JulianFields.MODIFIED_JULIAN_DAY, n, 19, SignStyle.NORMAL)
    E       1      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
    EE      2      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
    EEE     3      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
    EEEE    4      appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL)
    EEEEE   5      appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW)
    e       1      append special localized WeekFields element for numeric day-of-week
    ee      2      append special localized WeekFields element for numeric day-of-week, zero-padded
    eee     3      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
    eeee    4      appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL)
    eeeee   5      appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW)
    c       1      append special localized WeekFields element for numeric day-of-week
    ccc     3      appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT_STANDALONE)
    cccc    4      appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL_STANDALONE)
    ccccc   5      appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW_STANDALONE)

Поля времени: Символы шаблона для вывода времени.

Pattern  Count  Equivalent builder methods
  -------  -----  --------------------------
    a       1      appendText(ChronoField.AMPM_OF_DAY, TextStyle.SHORT)
    h       1      appendValue(ChronoField.CLOCK_HOUR_OF_AMPM)
    hh      2      appendValue(ChronoField.CLOCK_HOUR_OF_AMPM, 2)
    H       1      appendValue(ChronoField.HOUR_OF_DAY)
    HH      2      appendValue(ChronoField.HOUR_OF_DAY, 2)
    k       1      appendValue(ChronoField.CLOCK_HOUR_OF_DAY)
    kk      2      appendValue(ChronoField.CLOCK_HOUR_OF_DAY, 2)
    K       1      appendValue(ChronoField.HOUR_OF_AMPM)
    KK      2      appendValue(ChronoField.HOUR_OF_AMPM, 2)
    m       1      appendValue(ChronoField.MINUTE_OF_HOUR)
    mm      2      appendValue(ChronoField.MINUTE_OF_HOUR, 2)
    s       1      appendValue(ChronoField.SECOND_OF_MINUTE)
    ss      2      appendValue(ChronoField.SECOND_OF_MINUTE, 2)

    S..S    1..n   appendFraction(ChronoField.NANO_OF_SECOND, n, n, false)
    A..A    1..n   appendValue(ChronoField.MILLI_OF_DAY, n, 19, SignStyle.NOT_NEGATIVE)
    n..n    1..n   appendValue(ChronoField.NANO_OF_SECOND, n, 19, SignStyle.NOT_NEGATIVE)
    N..N    1..n   appendValue(ChronoField.NANO_OF_DAY, n, 19, SignStyle.NOT_NEGATIVE)

Идентификатор зоны: Символы шаблона для вывода 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). Необязательная секция завершается автоматически в конце билдера. Во время форматирования минутное значение будет выведено только если оно может быть получено из даты и времени. Во время разбора входные данные будут успешно обработаны, независимо от наличия минуты.

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

optionalEnd

public DateTimeFormatterBuilder optionalEnd()

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

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

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

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

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

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

toFormatter

public DateTimeFormatter toFormatter()

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

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

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

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

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

toFormatter

public DateTimeFormatter toFormatter(Locale locale)

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

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

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

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

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

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

Spec-Zone .ru
спецификации, руководства, описания, API