Класс DateTimeFormatter

public final class DateTimeFormatter
extends Object

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

Этот класс предоставляет основной входной пункт приложения для печати и разбора и предоставляет общие реализации DateTimeFormatter:

  • Использование предопределённых констант, таких как ISO_LOCAL_DATE
  • Использование символов шаблона, таких как uuuu-MMM-dd
  • Использование локальных стилей, таких как long или medium

Более сложные форматировщики предоставляются классом DateTimeFormatterBuilder.

Основные классы даты и времени предоставляют два метода — один для форматирования, format(DateTimeFormatter formatter), и один для разбора, parse(CharSequence text, DateTimeFormatter formatter).

Например: 

LocalDate date = LocalDate.now();
String text = date.format(formatter);
LocalDate parsedDate = LocalDate.parse(text, formatter);

Помимо формата, форматировщики могут быть созданы с желаемым Locale, Chronology, ZoneId и DecimalStyle.

Метод withLocale возвращает новый форматировщик, который переопределяет локаль. Локаль влияет на некоторые аспекты форматирования и разбора. Например, ofLocalizedDate предоставляет форматировщик, использующий локальный формат даты.

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

Метод withZone возвращает новый форматировщик, который переопределяет зону. При переопределении значение даты и времени преобразуется в ZonedDateTime с запрошенным ZoneId перед форматированием. При разборе ZoneId применяется перед возвратом значения.

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

Некоторые приложения могут потребоваться использовать более старый класс java.text.Format для форматирования. Метод toFormat() возвращает реализацию java.text.Format.

Предопределённые форматировщики

Форматировщик Описание Пример
ofLocalizedDate(dateStyle) Форматировщик со стилем даты из локали '2011-12-03'
ofLocalizedTime(timeStyle) Форматировщик со стилем времени из локали '10:15:30'
ofLocalizedDateTime(dateTimeStyle) Форматировщик со стилем даты и времени из локали '3 июн 2008 11:05:30'
ofLocalizedDateTime(dateStyle,timeStyle) Форматировщик со стилями даты и времени из локали '3 июн 2008 11:05'
BASIC_ISO_DATE Базовая дата ISO '20111203'
ISO_LOCAL_DATE Локальная дата ISO '2011-12-03'
ISO_OFFSET_DATE Дата ISO со смещением '2011-12-03+01:00'
ISO_DATE Дата ISO со смещением или без него '2011-12-03+01:00'; '2011-12-03'
ISO_LOCAL_TIME Время без смещения '10:15:30'
ISO_OFFSET_TIME Время со смещением '10:15:30+01:00'
ISO_TIME Время со смещением или без него '10:15:30+01:00'; '10:15:30'
ISO_LOCAL_DATE_TIME Локальное время и дата ISO '2011-12-03T10:15:30'
ISO_OFFSET_DATE_TIME Время и дата со смещением '2011-12-03T10:15:30+01:00'
ISO_ZONED_DATE_TIME Зональное время и дата '2011-12-03T10:15:30+01:00[Europe/Paris]'
ISO_DATE_TIME Дата и время с ZoneId '2011-12-03T10:15:30+01:00[Europe/Paris]'
ISO_ORDINAL_DATE Год и день года '2012-337'
ISO_WEEK_DATE Год и неделя '2012-W48-6'
ISO_INSTANT Дата и время мгновенного момента времени '2011-12-03T10:15:30Z'
RFC_1123_DATE_TIME RFC 1123 / RFC 822 'Вт, 3 июн 2008 11:05:30 GMT'

Шаблоны для форматирования и разбора

Шаблоны основаны на простом наборе символов и букв. Шаблон используется для создания форматировщика с помощью методов ofPattern(String) и ofPattern(String, Locale). Например, "d MMM uuuu" отформатирует 2011-12-03 как '3 дек 2011'. Форматировщик, созданный из шаблона, может использоваться неограниченное количество раз; он неизменяем и потокобезопасен.

Например: 

LocalDate date = LocalDate.now();
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");
String text = date.format(formatter);
LocalDate parsedDate = LocalDate.parse(text, formatter);

Все буквы от 'A' до 'Z' и от 'a' до 'z' зарезервированы как символы шаблона. Определены следующие символы шаблона:

Символ Значение Представление Примеры
G эра текст н.э.; Anno Domini; A
u год год 2004; 04
y год-эры год 2004; 04
D день года число 189
M/L месяц года число/текст 7; 07; ийл; июль; И
d день месяца число 10
g модифицированный-юлианский день число 2451334
Q/q четверть года число/текст 3; 03; Q3; 3-я четверть
Y год по неделям год 1996; 96
w неделя в году по неделям число 27
W неделя месяца число 4
E день недели текст Вт; Вторник; В
e/c локальный день недели число/текст 2; 02; Вт; Вторник; В
F день недели в месяце число 3
a до/после полудня текст ПОЛДЕНЬ
h час до/после полудня (1-12) число 12
K час до/после полудня (0-11) число 0
k час дня (1-24) число 24
H час дня (0-23) число 0
m минута часа число 30
s секунда минуты число 55
S дробная-часть секунды дробь 978
A миллисекунды дня число 1234
n наносекунда число 987654321
N наносекунда дня число 1234000000
V Идентификатор часового пояса id часового пояса America/Los_Angeles; Z; -08:30
v общее имя часового пояса имя часового пояса Тихоокеанское время; PT
z имя часового пояса имя часового пояса Тихоокеанское стандартное время; PST
O локальное смещение часового пояса смещение-O GMT+8; GMT+08:00; UTC-08:00
X смещение часового пояса 'Z' для нуля смещение-X Z; -08; -0830; -08:30; -083015; -08:30:15
x смещение часового пояса смещение-x +0000; -08; -0830; -08:30; -083015; -08:30:15
Z смещение часового пояса смещение-Z +0000; -0800; -08:00
p заполнение следующего модификатор заполнения 1
' экранирование для текста разделитель
'' одинарная кавычка литерал '
[ начало необязательной секции
] конец необязательной секции
# зарезервировано для будущего использования
{ зарезервировано для будущего использования
} зарезервировано для будущего использования

Количество символов шаблона определяет формат.

Текст: Стиль текста определяется на основе количества используемых символов шаблона. Менее 4 символов шаблона будут использовать short form. Ровно 4 символа шаблона будут использовать full form. Ровно 5 символов шаблона будут использовать narrow form. Символы шаблона 'L', 'c' и 'q' указывают на самостоятельную форму стилей текста.

Число: Если количество символов равно одному, то значение выводится с минимальным количеством цифр и без заполнения. В противном случае количество цифр используется как ширина поля вывода, при необходимости с заполнением нулями. У следующих символов шаблона есть ограничения на количество символов. Только один символ 'c' и 'F' может быть указан. До двух символов 'd', 'H', 'h', 'K', 'k', 'm' и 's' могут быть указаны. До трёх символов 'D' могут быть указаны.

Число/Текст: Если количество символов шаблона равно 3 или больше, то применяются правила для Текста, указанные выше. В противном случае применяются правила для Числа, указанные выше.

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

Год: Количество символов определяет минимальную ширину поля, при которой используется заполнение. Если количество символов равно двум, используется reduced формат с двумя цифрами. При выводе выводятся две крайние правые цифры. При парсинге используется базовое значение 2000, что приводит к году в диапазоне от 2000 до 2099 включительно. Если количество символов меньше четырёх (но не равно двум), то знак выводится только для отрицательных годов, как в SignStyle.NORMAL. В противном случае знак выводится, если ширина заполнения превышена, как в SignStyle.EXCEEDS_PAD.

Идентификатор часового пояса: Выводит идентификатор часового пояса, например, 'Europe/Paris'. Если количество символов равно двум, то выводится идентификатор часового пояса. Любое другое количество символов приводит к IllegalArgumentException.

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

Если символ шаблона равен 'v', выводится имя часового пояса, не учитывающее переходы на летнее время. Если количество символов равно одному, то выводится короткое имя. Если количество символов равно четырём, выводится полное имя. Два, три и пять или более символов приводят к IllegalArgumentException.

Смещение X и x: Форматирует смещение на основе количества символов шаблона. Один символ выводит только час, например, '+01', если минута не равна нулю, то выводится также и минута, например, '+0130'. Два символа выводит час и минуту без двоеточия, например, '+0130'. Три символа выводит час и минуту с двоеточием, например, '+01:30'. Четыре символа выводит час, минуту и необязательные секунды без двоеточия, например, '+013015'. Пять символов выводит час, минуту и необязательные секунды с двоеточием, например, '+01:30:15'. Шесть или более символов приводят к IllegalArgumentException. Символ шаблона 'X' (заглавная буква) выведет 'Z', если смещение для вывода равно нулю, а символ шаблона 'x' (строчная буква) выведет '+00', '+0000' или '+00:00'.

Смещение O: Форматирует локализованное смещение на основе количества символов шаблона. Один символ выводит короткую форму локализованного смещения, которое представляет собой текст смещения, например, 'GMT', с часом без ведущего нуля, необязательными двухзначными минутами и секундами, если они не равны нулю, и двоеточием, например, 'GMT+8'. Четыре символа выводит полную форму, которая представляет собой текст локализованного смещения, например, 'GMT', с двузначным часом и минутами, необязательным полем секунд, если оно не равно нулю, и двоеточием, например, 'GMT+08:00'. Любое другое количество символов приводит к IllegalArgumentException.

Смещение Z: Форматирует смещение на основе количества символов шаблона. Один, два или три символа выводит час и минуту без двоеточия, например, '+0130'. Вывод будет '+0000', когда смещение равно нулю. Четыре символа выводит полную форму локализованного смещения, эквивалентную четырём символам смещения O. Вывод будет соответствующим текстом локализованного смещения, если смещение равно нулю. Пять символов выводит час, минуту, с необязательными секундами, если они не равны нулю, с двоеточием. Он выводит 'Z', если смещение равно нулю. Шесть или более символов приводят к IllegalArgumentException.

Необязательная секция: Маркеры необязательной секции работают точно так же, как вызов DateTimeFormatterBuilder.optionalStart() и DateTimeFormatterBuilder.optionalEnd().

Модификатор заполнения: Изменяет шаблон, который следует непосредственно за ним, на заполнение пробелами. Ширина заполнения определяется количеством символов шаблона. Это то же самое, что вызов DateTimeFormatterBuilder.padNext(int).

Например, 'ppH' выводит час суток, заполненный пробелами слева до ширины 2.

Любой нераспознанный символ — ошибка. Любой символ, не являющийся буквой, кроме '[', ']', '{', '}', '#' и одиночного кавычки, будет выведен непосредственно. Несмотря на это, рекомендуется использовать одинарные кавычки вокруг всех символов, которые вы хотите вывести непосредственно, чтобы гарантировать, что будущие изменения не сломают ваше приложение.

Разрешение

Парсинг реализован как операция в две фазы. Во-первых, текст парсится с использованием структуры, определённой форматировщиком, создавая Map соответствия поле-значение, ZoneId и Chronology. Во-вторых, проанализированные данные разрешаются путём проверки, объединения и упрощения различных полей в более полезные.

Данный класс предоставляет пять методов парсинга. Четыре из них выполняют фазы парсинга и разрешения. Пятый метод, parseUnresolved(CharSequence, ParsePosition), выполняет только первую фазу, оставляя результат неразрешённым. Таким образом, это по существу операция низкого уровня.

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

ResolverStyle — это перечисление, которое предлагает три разных подхода: строгий, интеллектуальный и снисходительный. Интеллектуальный подход используется по умолчанию. Его можно установить с помощью withResolverStyle(ResolverStyle).

Параметр withResolverFields(TemporalField...) позволяет отфильтровать набор полей, которые будут разрешены, прежде чем начнется разрешение. Например, если форматировщик проанализировал год, месяц, день месяца и день года, то есть два подхода к разрешению даты: (год + месяц + день месяца) и (год + день года). Параметр resolverFields позволяет выбрать один из двух подходов. Если не заданы поля resolverFields, то оба подхода должны привести к одной и той же дате.

Разрешение отдельных полей для формирования полной даты и времени — сложный процесс с поведением, распределённым по нескольким классам. Он выполняет следующие шаги:

  1. Определяется хронология. Хронология результата — это либо хронология, которая была проанализирована, либо, если хронология не была проанализирована, это хронология, установленная в этом классе, либо, если она равна null, это IsoChronology.
  2. Разрешаются поля даты ChronoField. Это достигается с помощью Chronology.resolveDate(Map, ResolverStyle). Документация по разрешению полей находится в реализации Chronology.
  3. Разрешаются поля времени ChronoField. Это описано в ChronoField и одинаково для всех хронологий.
  4. Обрабатываются все поля, которые не являются ChronoField. Это достигается с помощью TemporalField.resolve(Map, TemporalAccessor, ResolverStyle). Документация по разрешению полей находится в реализации TemporalField.
  5. Поля даты и времени ChronoField разрешаются повторно. Это позволяет полям на четвёртом шаге производить ChronoField значения и обрабатывать их в даты и время.
  6. Формируется LocalTime , если доступно хотя бы значение часа.
  7. Все оставшиеся неразрешённые поля проверяются на соответствие любой разрешённой дате и/или времени. Таким образом, на предыдущей стадии разрешалась (год + месяц + день месяца) в дату, а на этой стадии проверялось, был ли день недели корректен для даты.
  8. Если был проанализирован лишний номер дней, то он добавляется к дате, если дата доступна.
  9. Если присутствует поле, связанное со секундами, но LocalTime не было проанализировано, то разрешитель гарантирует, что значения милли-, микро- и наносекунд доступны для выполнения контракта ChronoField. Отсутствующие значения будут установлены в ноль.
  10. Если и дата, и время были проанализированы, а также присутствует смещение или часовой пояс, создаётся поле ChronoField.INSTANT_SECONDS. Если был проанализирован смещение, то смещение будет объединено с LocalDateTime для формирования момента времени, а любой часовой пояс будет проигнорирован. Если был проанализирован ZoneId без смещения, то часовой пояс будет объединён с LocalDateTime для формирования момента времени в соответствии с правилами ChronoLocalDateTime.atZone(ZoneId).
Требования к реализации:
Этот класс неизменяемый и потокобезопасный.
С:
1.8

Поля

Модификатор и тип Поле Описание
static DateTimeFormatter BASIC_ISO_DATE

Форматтер даты ISO, форматирующий или анализирующий дату без смещения, например, '20111203'.
static DateTimeFormatter ISO_DATE

Форматтер даты ISO, форматирующий или анализирующий дату со смещением, если оно доступно, например, '2011-12-03' или '2011-12-03+01:00'.
static DateTimeFormatter ISO_DATE_TIME

Форматтер даты-времени, подобный ISO, форматирующий или анализирующий дату-время со смещением и часовым поясом, если они доступны, например, '2011-12-03T10:15:30', '2011-12-03T10:15:30+01:00' или '2011-12-03T10:15:30+01:00[Europe/Paris]'.
static DateTimeFormatter ISO_INSTANT

Форматтер момента ISO, форматирующий или анализирующий момент во UTC, например, '2011-12-03T10:15:30Z'.
static DateTimeFormatter ISO_LOCAL_DATE

Форматтер даты ISO, форматирующий или анализирующий дату без смещения, например, '2011-12-03'.
static DateTimeFormatter ISO_LOCAL_DATE_TIME

Форматтер даты-времени ISO, форматирующий или анализирующий дату-время без смещения, например, '2011-12-03T10:15:30'.
static DateTimeFormatter ISO_LOCAL_TIME

Форматтер времени ISO, форматирующий или анализирующий время без смещения, например, '10:15' или '10:15:30'.
static DateTimeFormatter ISO_OFFSET_DATE

Форматтер даты ISO, форматирующий или анализирующий дату со смещением, например, '2011-12-03+01:00'.
static DateTimeFormatter ISO_OFFSET_DATE_TIME

Форматтер даты-времени ISO, форматирующий или анализирующий дату-время со смещением, например, '2011-12-03T10:15:30+01:00'.
static DateTimeFormatter ISO_OFFSET_TIME

Форматтер времени ISO, форматирующий или анализирующий время со смещением, например, '10:15+01:00' или '10:15:30+01:00'.
static DateTimeFormatter ISO_ORDINAL_DATE

Форматтер даты ISO, форматирующий или анализирующий порядковый номер даты без смещения, например, '2012-337'.
static DateTimeFormatter ISO_TIME

Форматтер времени ISO, форматирующий или анализирующий время со смещением, если оно доступно, например, '10:15', '10:15:30' или '10:15:30+01:00'.
static DateTimeFormatter ISO_WEEK_DATE

Форматтер даты ISO, форматирующий или анализирующий дату по номеру недели без смещения, например, '2012-W48-6'.
static DateTimeFormatter ISO_ZONED_DATE_TIME

Форматтер даты-времени, подобный ISO, форматирующий или анализирующий дату-время со смещением и часовым поясом, например, '2011-12-03T10:15:30+01:00[Europe/Paris]'.
static DateTimeFormatter RFC_1123_DATE_TIME

Форматтер даты-времени RFC-1123, например, 'Tue, 3 Jun 2008 11:05:30 GMT'.

Методы

Модификатор и тип Метод Описание
String format​(TemporalAccessor temporal)

Форматирует объект даты-времени с помощью этого форматтера.
void formatTo​(TemporalAccessor temporal, Appendable appendable)

Форматирует объект даты-времени в Appendable с помощью этого форматтера.
Chronology getChronology()

Получает переопределённую хронологию, используемую во время форматирования.
DecimalStyle getDecimalStyle()

Получает DecimalStyle, используемый во время форматирования.
Locale getLocale()

Получает локаль, используемую во время форматирования.
Set<TemporalField> getResolverFields()

Получает поля разрешения, используемые во время анализа.
ResolverStyle getResolverStyle()

Получает стиль разрешения, используемый во время анализа.
ZoneId getZone()

Получает переопределённый часовой пояс, используемый во время форматирования.
DateTimeFormatter localizedBy​(Locale locale)

Возвращает копию этого форматтера с локализованными значениями локали, календаря, региона, десятичного стиля и/или часового пояса, которые переопределяют значения в этом форматтере.
static DateTimeFormatter ofLocalizedDate​(FormatStyle dateStyle)

Возвращает локально-специфичный формат даты для ISO хронологии.
static DateTimeFormatter ofLocalizedDateTime​(FormatStyle dateTimeStyle)

Возвращает локально-специфичный форматтер даты-времени для ISO хронологии.
static DateTimeFormatter ofLocalizedDateTime​(FormatStyle dateStyle, FormatStyle timeStyle)

Возвращает локально-специфичный формат даты и времени для ISO хронологии.
static DateTimeFormatter ofLocalizedTime​(FormatStyle timeStyle)

Возвращает локально-специфичный формат времени для ISO хронологии.
static DateTimeFormatter ofPattern​(String pattern)

Создаёт форматтер, используя указанный шаблон.
static DateTimeFormatter ofPattern​(String pattern, Locale locale)

Создаёт форматтер, используя указанный шаблон и локаль.
TemporalAccessor parse​(CharSequence text)

Полностью анализирует текст, производя временный объект.
TemporalAccessor parse​(CharSequence text, ParsePosition position)

Анализирует текст с помощью этого форматтера, предоставляя управление позицией текста.
<T> T parse​(CharSequence text, TemporalQuery<T> query)

Полностью анализирует текст, производя объект указанного типа.
TemporalAccessor parseBest​(CharSequence text, TemporalQuery<?>... queries)

Полностью анализирует текст, производя объект одного из указанных типов.
static TemporalQuery<Period> parsedExcessDays()

Запрос, предоставляющий доступ к дополнительным дням, которые были проанализированы.
static TemporalQuery<Boolean> parsedLeapSecond()

Запрос, предоставляющий доступ к тому, был ли проанализирован високосный момент.
TemporalAccessor parseUnresolved​(CharSequence text, ParsePosition position)

Анализирует текст с помощью этого форматтера, не разрешая результат, предназначен для продвинутых случаев использования.
Format toFormat()

Возвращает этот форматтер как экземпляр java.text.Format.

Format toFormat​(TemporalQuery<?> parseQuery)

Возвращает этот форматтер как экземпляр java.text.Format экземпляр, который будет анализировать с использованием указанного запроса.
String toString()

Возвращает описание базовых форматтеров.
DateTimeFormatter withChronology​(Chronology chrono)

Возвращает копию этого форматтера с новой переопределённой хронологией.
DateTimeFormatter withDecimalStyle​(DecimalStyle decimalStyle)

Возвращает копию этого форматтера с новым DecimalStyle.
DateTimeFormatter withLocale​(Locale locale)

Возвращает копию этого форматтера с новой локалью.
DateTimeFormatter withResolverFields​(TemporalField... resolverFields)

Возвращает копию этого форматтера с новым набором полей разрешения.
DateTimeFormatter withResolverFields​(Set<TemporalField> resolverFields)

Возвращает копию этого форматтера с новым набором полей разрешения.
DateTimeFormatter withResolverStyle​(ResolverStyle resolverStyle)

Возвращает копию этого форматтера с новым стилем разрешения.
DateTimeFormatter withZone​(ZoneId zone)

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

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

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

Поля

ISO_LOCAL_DATE

public static final DateTimeFormatter ISO_LOCAL_DATE

Форматтер даты ISO, который форматирует или анализирует дату без смещения, например, '2011-12-03'.

Возвращает неизменяемый форматтер, способный форматировать и анализировать расширенный локальный формат даты ISO-8601. Формат состоит из:

  • Четыре и более цифр для year. Года в диапазоне от 0000 до 9999 будут дополнены нулями до четырёх цифр. Годы вне этого диапазона будут иметь префиксный положительный или отрицательный знак.
  • Дефис
  • Две цифры для month-of-year. Они дополняются нулём до двух цифр.
  • Дефис
  • Две цифры для day-of-month. Они дополняются нулём до двух цифр.

Возвращаемый форматтер имеет хронологию ISO, чтобы гарантировать правильное преобразование дат в других календарных системах. Он не имеет переопределённой зоны и использует стиль анализа STRICT.

ISO_OFFSET_DATE

public static final DateTimeFormatter ISO_OFFSET_DATE

Форматтер даты ISO, который форматирует или анализирует дату со смещением, например, '2011-12-03+01:00'.

Возвращает неизменяемый форматтер, способный форматировать и анализировать расширенный формат даты со смещением ISO-8601. Формат состоит из:

  • Форматтера ISO_LOCAL_DATE
  • Значения offset ID. Если смещение включает секунды, они обрабатываются, несмотря на то, что это не часть стандарта ISO-8601. Анализ нечувствителен к регистру.

Возвращаемый форматтер имеет хронологию ISO, чтобы гарантировать правильное преобразование дат в других календарных системах. Он не имеет переопределённой зоны и использует стиль анализа STRICT.

ISO_DATE

public static final DateTimeFormatter ISO_DATE

Форматтер даты ISO, который форматирует или анализирует дату со смещением, если оно доступно, например, '2011-12-03' или '2011-12-03+01:00'.

Возвращает неизменяемый форматтер, способный форматировать и анализировать расширенный формат даты ISO-8601. Формат состоит из:

  • Форматтера ISO_LOCAL_DATE
  • Если смещение недоступно, то формат завершается.
  • Значения offset ID. Если смещение включает секунды, они обрабатываются, несмотря на то, что это не часть стандарта ISO-8601. Анализ нечувствителен к регистру.

Поскольку этот форматтер имеет необязательный элемент, может потребоваться анализ с помощью parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...).

Возвращаемый форматтер имеет хронологию ISO, чтобы гарантировать правильное преобразование дат в других календарных системах. Он не имеет переопределённой зоны и использует стиль анализа STRICT.

ISO_LOCAL_TIME

public static final DateTimeFormatter ISO_LOCAL_TIME

Форматтер времени ISO, который форматирует или анализирует время без смещения, например, '10:15' или '10:15:30'.

Возвращает неизменяемый форматтер, способный форматировать и анализировать расширенный локальный формат времени ISO-8601. Формат состоит из:

  • Две цифры для hour-of-day. Они дополняются нулём до двух цифр.
  • Двоеточие
  • Две цифры для minute-of-hour. Они дополняются нулём до двух цифр.
  • Если секунды не доступны, то формат завершается.
  • Двоеточие
  • Две цифры для second-of-minute. Они дополняются нулём до двух цифр.
  • Если наносекунды равны нулю или не доступны, то формат завершается.
  • Десятичная точка
  • От одной до девяти цифр для nano-of-second. Выводится столько цифр, сколько нужно.

Возвращаемый форматтер не имеет переопределённой хронологии или зоны. Он использует стиль анализа STRICT.

ISO_OFFSET_TIME

public static final DateTimeFormatter ISO_OFFSET_TIME

Форматтер времени ISO, который форматирует или анализирует время со смещением, например, '10:15+01:00' или '10:15:30+01:00'.

Возвращает неизменяемый форматтер, способный форматировать и анализировать расширенный формат времени со смещением ISO-8601. Формат состоит из:

  • Форматтера ISO_LOCAL_TIME
  • Значения offset ID. Если смещение включает секунды, они обрабатываются, несмотря на то, что это не часть стандарта ISO-8601. Анализ нечувствителен к регистру.

Возвращаемый форматтер не имеет переопределённой хронологии или зоны. Он использует стиль анализа STRICT.

ISO_TIME

public static final DateTimeFormatter ISO_TIME

Форматтер времени ISO, который форматирует или анализирует время со смещением, если оно доступно, например, '10:15', '10:15:30' или '10:15:30+01:00'.

Возвращает неизменяемый форматтер, способный форматировать и анализировать расширенный локальный или смещённый формат времени ISO-8601, а также расширенный не-ISO формат, указывающий часовой пояс. Формат состоит из:

  • Форматтера ISO_LOCAL_TIME
  • Если смещение недоступно, то формат завершается.
  • Значения offset ID. Если смещение включает секунды, они обрабатываются, несмотря на то, что это не часть стандарта ISO-8601. Анализ нечувствителен к регистру.

Поскольку этот форматтер имеет необязательный элемент, может потребоваться анализ с помощью parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...).

Возвращаемый форматтер не имеет переопределённой хронологии или зоны. Он использует стиль анализа STRICT.

ISO_LOCAL_DATE_TIME

public static final DateTimeFormatter ISO_LOCAL_DATE_TIME

Форматтер даты и времени ISO, который форматирует или анализирует дату и время без смещения, например, '2011-12-03T10:15:30'.

Возвращает неизменяемый форматтер, способный форматировать и анализировать расширенный смещённый формат даты и времени ISO-8601. Формат состоит из:

  • Форматтера ISO_LOCAL_DATE
  • Буква 'T'. Анализ нечувствителен к регистру.
  • Форматтера ISO_LOCAL_TIME

Возвращаемый форматтер имеет хронологию ISO, чтобы гарантировать правильное преобразование дат в других календарных системах. Он не имеет переопределённой зоны и использует стиль анализа STRICT.

ISO_OFFSET_DATE_TIME

public static final DateTimeFormatter ISO_OFFSET_DATE_TIME

Форматтер даты и времени ISO, который форматирует или анализирует дату и время со смещением, например, '2011-12-03T10:15:30+01:00'.

Возвращает неизменяемый форматтер, способный форматировать и анализировать расширенный формат даты и времени со смещением ISO-8601. Формат состоит из:

  • Форматтера ISO_LOCAL_DATE_TIME
  • Значения offset ID. Если смещение включает секунды, они обрабатываются, несмотря на то, что это не часть стандарта ISO-8601. Анализ смещения нестрогий, что позволяет опустить минуты и секунды. Анализ нечувствителен к регистру.

Возвращаемый форматтер имеет хронологию ISO, чтобы гарантировать правильное преобразование дат в других календарных системах. Он не имеет переопределённой зоны и использует стиль анализа STRICT.

ISO_ZONED_DATE_TIME

public static final DateTimeFormatter ISO_ZONED_DATE_TIME

Форматтер даты и времени, похожий на ISO, который форматирует или анализирует дату и время со смещением и часовым поясом, например, '2011-12-03T10:15:30+01:00[Europe/Paris]'.

Возвращает неизменяемый форматтер, способный форматировать и анализировать формат, расширяющий формат смещённого даты и времени ISO-8601 с добавлением часового пояса. Часть в квадратных скобках не входит в стандарт ISO-8601. Формат состоит из:

  • Форматтера ISO_OFFSET_DATE_TIME
  • Если идентификатор зоны не доступен или является ZoneOffset, то формат завершается.
  • Открывающая квадратная скобка '['.
  • Значения zone ID. Это не часть стандарта ISO-8601. Анализ чувствителен к регистру.
  • Закрывающая квадратная скобка ']'.

Возвращаемый форматтер имеет хронологию ISO, чтобы гарантировать правильное преобразование дат в других календарных системах. Он не имеет переопределённой зоны и использует стиль анализа STRICT.

ISO_DATE_TIME

public static final DateTimeFormatter ISO_DATE_TIME

Форматтер даты и времени, похожий на ISO, который форматирует или анализирует дату и время со смещением и часовым поясом, если они доступны, например, '2011-12-03T10:15:30', '2011-12-03T10:15:30+01:00' или '2011-12-03T10:15:30+01:00[Europe/Paris]'.

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

  • Форматтера ISO_LOCAL_DATE_TIME
  • Если смещение недоступно для форматирования или анализа, то формат завершается.
  • Значения offset ID. Если смещение включает секунды, они обрабатываются, несмотря на то, что это не часть стандарта ISO-8601.
  • Если идентификатор зоны не доступен или является ZoneOffset, то формат завершается.
  • Открывающая квадратная скобка '['.
  • Значения zone ID. Это не часть стандарта ISO-8601. Анализ чувствителен к регистру.
  • Закрывающая квадратная скобка ']'.

Поскольку этот форматтер имеет необязательный элемент, может потребоваться анализ с помощью parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...).

Возвращаемый форматтер имеет хронологию ISO, чтобы гарантировать правильное преобразование дат в других календарных системах. Он не имеет переопределённой зоны и использует стиль анализа STRICT.

ISO_ORDINAL_DATE

public static final DateTimeFormatter ISO_ORDINAL_DATE

Форматировщик дат ISO, который форматирует или анализирует порядковый день без смещения, например, '2012-337'.

Это возвращает неизменяемый форматировщик, способный форматировать и анализировать расширенный формат порядковой даты ISO-8601. Формат состоит из:

  • Четыре и более цифры для year. Года в диапазоне от 0000 до 9999 будут дополнены нулями до четырех цифр. Годы за пределами этого диапазона будут иметь префиксный положительный или отрицательный символ.
  • Дефис
  • Три цифры для day-of-year. Они дополняются нулями до трех цифр.
  • Если смещение недоступно для форматирования или анализа, формат завершается.
  • offset ID. Если смещение имеет секунды, они будут обработаны, хотя это не является частью стандарта ISO-8601. Анализ регистронезависимый.

Так как этот форматировщик имеет необязательный элемент, может потребоваться анализ с помощью parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...).

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

ISO_WEEK_DATE

public static final DateTimeFormatter ISO_WEEK_DATE

Форматировщик дат ISO, который форматирует или анализирует дату, основанную на неделе, без смещения, например, '2012-W48-6'.

Это возвращает неизменяемый форматировщик, способный форматировать и анализировать расширенный формат даты ISO-8601, основанный на неделе. Формат состоит из:

  • Четыре и более цифры для week-based-year. Года в диапазоне от 0000 до 9999 будут дополнены нулями до четырех цифр. Года за пределами этого диапазона будут иметь префиксный положительный или отрицательный символ.
  • Дефис
  • Буква 'W'. Анализ регистронезависимый.
  • Две цифры для week-of-week-based-year. Они дополняются нулями до двух цифр.
  • Дефис
  • Одна цифра для day-of-week. Значение варьируется от понедельника (1) до воскресенья (7).
  • Если смещение недоступно для форматирования или анализа, формат завершается.
  • offset ID. Если смещение имеет секунды, они будут обработаны, хотя это не является частью стандарта ISO-8601. Анализ регистронезависимый.

Так как этот форматировщик имеет необязательный элемент, может потребоваться анализ с помощью parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...).

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

ISO_INSTANT

public static final DateTimeFormatter ISO_INSTANT

Форматировщик мгновенных моментов ISO, который форматирует или анализирует мгновение времени в UTC, например, '2011-12-03T10:15:30Z'.

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

Это специальный форматировщик, предназначенный для отображения мгновения времени в читаемом формате Instant. Класс Instant предназначен для представления только момента во времени и внутренне хранит значение в наносекундах от фиксированной эпохи 1970-01-01Z. Поэтому Instant не может быть отформатирован как дата или время без указания зоны времени. Этот форматировщик позволяет отформатировать Instant путём предоставления соответствующего преобразования с помощью ZoneOffset.UTC.

Формат состоит из:

Возвращаемый форматировщик не имеет переопределённой хронологии или зоны. Он использует стиль разрешения STRICT.

BASIC_ISO_DATE

public static final DateTimeFormatter BASIC_ISO_DATE

Форматировщик дат ISO, который форматирует или анализирует дату без смещения, например, '20111203'.

Это возвращает неизменяемый форматировщик, способный форматировать и анализировать базовый локальный формат даты ISO-8601. Формат состоит из:

  • Четыре цифры для year. Поддерживаются только годы в диапазоне от 0000 до 9999.
  • Две цифры для month-of-year. Они дополняются нулями до двух цифр.
  • Две цифры для day-of-month. Они дополняются нулями до двух цифр.
  • Если смещение недоступно для форматирования или анализа, формат завершается.
  • offset ID без двоеточий. Если смещение имеет секунды, они будут обработаны, хотя это не является частью стандарта ISO-8601. Анализ смещения допускает необязательность минут и секунд. Анализ регистронезависимый.

Так как этот форматировщик имеет необязательный элемент, может потребоваться анализ с помощью parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...).

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

RFC_1123_DATE_TIME

public static final DateTimeFormatter RFC_1123_DATE_TIME

Форматировщик даты и времени RFC-1123, например, 'Tue, 3 Jun 2008 11:05:30 GMT'.

Это возвращает неизменяемый форматировщик, способный форматировать и анализировать большую часть формата RFC-1123. RFC-1123 обновляет RFC-822, изменяя год с двух на четыре цифры. Эта реализация требует четырёхзначного года. Эта реализация также не обрабатывает североамериканские или военные обозначения зон, только 'GMT' и смещения.

Формат состоит из:

  • Если день недели недоступен для форматирования или анализа, перейти к дню месяца.
  • Трехбуквенное обозначение day-of-week на английском языке.
  • Запятая
  • Пробел
  • Одна или две цифры для day-of-month.
  • Пробел
  • Трехбуквенное обозначение month-of-year на английском языке.
  • Пробел
  • Четыре цифры для year. Поддерживаются только годы в диапазоне от 0000 до 9999.
  • Пробел
  • Две цифры для hour-of-day. Они дополняются нулями до двух цифр.
  • Двоеточие
  • Две цифры для minute-of-hour. Они дополняются нулями до двух цифр.
  • Если секунда минуты недоступна, перейти к следующему пробелу.
  • Двоеточие
  • Две цифры для second-of-minute. Они дополняются нулями до двух цифр.
  • Пробел
  • offset ID без двоеточий или секунд. Смещение ноль обозначается как "GMT". Североамериканские и военные обозначения зон не обрабатываются.

Анализ регистронезависимый.

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

Методы

ofPattern

public static DateTimeFormatter ofPattern(String pattern)

Создаёт форматер с использованием указанного шаблона.

Этот метод создаст форматер, основанный на простом шаблоне букв и символов, как описано в документации класса. Например, d MMM uuuu отформатирует 2011-12-03 как '3 Dec 2011'.

Форматер будет использовать default FORMAT locale. Это можно изменить, используя withLocale(Locale) на возвращённом формате. В качестве альтернативы используйте вариант метода ofPattern(String, Locale).

Возвращённый форматер не имеет переопределённой хронологии или зоны. Он использует стиль разрешения SMART.

Параметры:
pattern - используемый шаблон, не null
Возвращает:
форматер, основанный на шаблоне, не null
Выбрасывает:
IllegalArgumentException - если шаблон некорректен
См. также:
DateTimeFormatterBuilder.appendPattern(String)

ofPattern

public static DateTimeFormatter ofPattern(String pattern,
                                          Locale locale)

Создаёт форматер с использованием указанного шаблона и региональных настроек.

Этот метод создаст форматер, основанный на простом шаблоне букв и символов, как описано в документации класса. Например, d MMM uuuu отформатирует 2011-12-03 как '3 Dec 2011'.

Форматер будет использовать указанные региональные настройки. Это можно изменить, используя withLocale(Locale) на возвращённом формате.

Возвращённый форматер не имеет переопределённой хронологии или зоны. Он использует стиль разрешения SMART.

Параметры:
pattern - используемый шаблон, не null
locale - используемые региональные настройки, не null
Возвращает:
форматер, основанный на шаблоне, не null
Выбрасывает:
IllegalArgumentException - если шаблон некорректен
См. также:
DateTimeFormatterBuilder.appendPattern(String)

ofLocalizedDate

public static DateTimeFormatter ofLocalizedDate(FormatStyle dateStyle)

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

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

Региональные настройки определяются из форматера. Форматер, возвращённый напрямую этим методом, будет использовать default FORMAT locale. Региональные настройки можно контролировать, используя withLocale(Locale) на результате этого метода.

Обратите внимание, что локализованный шаблон ищется лениво. Это DateTimeFormatter хранит необходимый стиль и региональные настройки, ища требуемый шаблон по мере необходимости.

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

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

ofLocalizedTime

public static DateTimeFormatter ofLocalizedTime(FormatStyle timeStyle)

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

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

Региональные настройки определяются из форматера. Форматер, возвращённый напрямую этим методом, будет использовать default FORMAT locale. Региональные настройки можно контролировать, используя withLocale(Locale) на результате этого метода.

Обратите внимание, что локализованный шаблон ищется лениво. Это DateTimeFormatter хранит необходимый стиль и региональные настройки, ища требуемый шаблон по мере необходимости.

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

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

ofLocalizedDateTime

public static DateTimeFormatter ofLocalizedDateTime(FormatStyle dateTimeStyle)

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

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

Региональные настройки определяются из форматера. Форматер, возвращённый напрямую этим методом, будет использовать default FORMAT locale. Региональные настройки можно контролировать, используя withLocale(Locale) на результате этого метода.

Обратите внимание, что локализованный шаблон ищется лениво. Это DateTimeFormatter хранит необходимый стиль и региональные настройки, ища требуемый шаблон по мере необходимости.

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

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

ofLocalizedDateTime

public static DateTimeFormatter ofLocalizedDateTime(FormatStyle dateStyle,
                                                    FormatStyle timeStyle)

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

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

Региональные настройки определяются из форматера. Форматер, возвращённый напрямую этим методом, будет использовать default FORMAT locale. Региональные настройки можно контролировать, используя withLocale(Locale) на результате этого метода.

Обратите внимание, что локализованный шаблон ищется лениво. Это DateTimeFormatter хранит необходимый стиль и региональные настройки, ища требуемый шаблон по мере необходимости.

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

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

parsedExcessDays

public static final TemporalQuery<Period> parsedExcessDays()

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

Возвращает одиночный запрос, который предоставляет доступ к дополнительной информации из анализа. Запрос всегда возвращает непустой период, возвращая нулевой период вместо null.

Существуют две ситуации, когда этот запрос может вернуть ненулевой период.

  • Если ResolverStyle равен LENIENT и время анализируется без даты, то полный результат анализа состоит из LocalTime и излишка Period в днях.
  • Если ResolverStyle равен SMART и время анализируется без даты, где время равно 24:00:00, то полный результат анализа состоит из LocalTime 00:00:00 и излишка Period в один день.

В обоих случаях, если проанализирован полный ChronoLocalDateTime или Instant, то излишки дней добавляются к части даты. В результате этот запрос вернёт нулевой период.

Поведение SMART обрабатывает общее значение «конец дня» 24:00. Обработка в режиме LENIENT также даёт такой же результат:

Text to parse        Parsed object                         Excess days
  "2012-12-03T00:00"   LocalDateTime.of(2012, 12, 3, 0, 0)   ZERO
  "2012-12-03T24:00"   LocalDateTime.of(2012, 12, 4, 0, 0)   ZERO
  "00:00"              LocalTime.of(0, 0)                    ZERO
  "24:00"              LocalTime.of(0, 0)                    Period.ofDays(1)
Запрос можно использовать следующим образом: 
TemporalAccessor parsed = formatter.parse(str);
  LocalTime time = parsed.query(LocalTime::from);
  Period extraDays = parsed.query(DateTimeFormatter.parsedExcessDays());
Возвращает:
запрос, предоставляющий доступ к излишним дням, которые были проанализированы

parsedLeapSecond

public static final TemporalQuery<Boolean> parsedLeapSecond()

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

Возвращает одиночный запрос, предоставляющий доступ к дополнительной информации из анализа. Запрос всегда возвращает непустой булевый тип, true, если анализ увидел високосную секунду, false — если нет.

Анализ момента времени обрабатывает специальное «высокосную секунду» время '23:59:60'. Высокосные секунды происходят в '23:59:60' в часовом поясе UTC, но в другое местное время в различных часовых поясах. Для избежания этой потенциальной неоднозначности обработка високосных секунд ограничена DateTimeFormatterBuilder.appendInstant(), так как этот метод всегда анализирует момент времени с UTC смещением.

Если получено время '23:59:60', то применяется простое преобразование, заменяющее секунду минуты 60 на 59. Этот запрос можно использовать на результате анализа, чтобы определить, было ли выполнено корректирование високосной секунды. Запрос вернёт true , если корректировка для удаления високосной секунды была выполнена, и false — если нет. Обратите внимание, что применение механизма сглаживания високосных секунд, такого как UTC-SLS, является обязанностью приложения, как следует:

TemporalAccessor parsed = formatter.parse(str);
  Instant instant = parsed.query(Instant::from);
  if (parsed.query(DateTimeFormatter.parsedLeapSecond())) {
    // validate leap-second is correct and apply correct smoothing
  }
Возвращает:
запрос, предоставляющий доступ к тому, была ли проанализирована високосная секунда

getLocale

public Locale getLocale()

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

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

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

withLocale

public DateTimeFormatter withLocale(Locale locale)

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

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

Языковой стандарт сохраняется в качестве переданного, без дальнейшей обработки. Если языковой стандарт имеет расширения Юникода, они могут быть использованы позже в обработке текста. Чтобы установить хронологию, часовой пояс и десятичный стиль из расширений Юникода, см. localizedBy().

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

Параметры:
locale - новый языковой стандарт, не null
Возвращает:
форматер, основанный на этом форматере с запрошенным языковым стандартом, не null
См. также:
localizedBy(Locale)

localizedBy

public DateTimeFormatter localizedBy(Locale locale)

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

Это используется для поиска любой части форматера, требующей специфической локализации, такой как текст или локализованный шаблон. Если языковой стандарт содержит расширения Юникода «ca» (календарь), «nu» (система счисления), «rg» (переопределение региона) и/или «tz» (часовой пояс), хронология, система счисления и/или зона переопределяются. Если указаны оба «ca» и «rg», хронология из расширения «ca» переопределяет неявную хронологию из расширения «rg». То же самое относится к расширению «nu».

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

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

Параметры:
locale - языковой стандарт, не null
Возвращает:
форматер, основанный на этом форматере с локализованными значениями календаря, десятичного стиля и/или часового пояса, которые переопределяют значения в этом форматере.
С:
10
См. также:
withLocale(Locale)

getDecimalStyle

public DecimalStyle getDecimalStyle()

Возвращает DecimalStyle, используемый при форматировании.

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

withDecimalStyle

public DateTimeFormatter withDecimalStyle(DecimalStyle decimalStyle)

Возвращает копию этого форматера с новым DecimalStyle.

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

Параметры:
decimalStyle - новый DecimalStyle, не null
Возвращает:
форматер, основанный на этом форматере с запрошенным DecimalStyle, не null

getChronology

public Chronology getChronology()

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

Возвращает переопределяемую хронологию, используемую для преобразования дат. По умолчанию форматер не имеет переопределяемой хронологии, возвращая null. См. withChronology(Chronology) для получения более подробной информации о переопределении.

Возвращает:
переопределяемую хронологию этого форматера, null, если переопределения нет

withChronology

public DateTimeFormatter withChronology(Chronology chrono)

Возвращает копию этого форматера с новой переопределяемой хронологией.

Возвращает форматер с похожим состоянием, как у этого форматера, но с заданной переопределяемой хронологией. По умолчанию форматер не имеет переопределяемой хронологии, возвращая null.

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

При форматировании, если временный объект содержит дату, она будет преобразована в дату в переопределяемой хронологии. Определяется ли временный объект как содержащий дату, определяется путем запроса поля EPOCH_DAY. Любое время или часовой пояс сохраняются неизменными, если не переопределены.

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

При разборе следует рассмотреть два разных случая. Если хронология была проанализирована непосредственно из текста, возможно, потому что был использован DateTimeFormatterBuilder.appendChronologyId(), то это переопределяемая хронология не оказывает никакого влияния. Если зона не была проанализирована, то эта переопределяемая хронология будет использована для интерпретации ChronoField значений в дату в соответствии с правилами разрешения дат хронологии.

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

Параметры:
chrono - новая хронология, null, если переопределения нет
Возвращает:
форматер, основанный на этом форматере с запрошенной переопределяемой хронологией, не null

getZone

public ZoneId getZone()

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

Возвращает переопределяемую зону, используемую для преобразования моментов времени. По умолчанию у форматера нет переопределяемой зоны, возвращается null. См. withZone(ZoneId) для получения более подробной информации о переопределении.

Возвращает:
переопределяемую зону этого форматера, null, если переопределения нет

withZone

public DateTimeFormatter withZone(ZoneId zone)

Возвращает копию этого форматера с новой переопределяемой зоной.

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

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

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

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

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

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

Параметры:
zone - новая переопределяемая зона, null, если переопределения нет
Возвращает:
форматер, основанный на этом форматере с запрошенной переопределяемой зоной, не null

getResolverStyle

public ResolverStyle getResolverStyle()

Возвращает стиль разрешения, используемый при анализе.

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

Возвращает:
стиль разрешения этого форматера, не null

withResolverStyle

public DateTimeFormatter withResolverStyle(ResolverStyle resolverStyle)

Возвращает копию этого форматера с новым стилем разрешения.

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

Изменение стиля разрешения влияет только при разборе. Анализ строки текста происходит в две фазы. Фаза 1 — базовый анализ текста в соответствии с полями, добавленными в билдер. Фаза 2 разрешает пары поле-значение, проанализированные в объекты даты и/или времени. Стиль разрешения используется для управления тем, как происходит фаза 2, разрешение. См. ResolverStyle для получения дополнительной информации о доступных вариантах.

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

Параметры:
resolverStyle - новый стиль разрешения, не null
Возвращает:
форматер, основанный на этом форматере с запрошенным стилем разрешения, не null

getResolverFields

public Set<TemporalField> getResolverFields()

Возвращает поля разрешения, используемые при разборе.

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

Возвращает:
неизменяемый набор полей разрешения этого форматера, null, если полей нет

withResolverFields

public DateTimeFormatter withResolverFields(TemporalField... resolverFields)

Возвращает копию этого форматировщика с новым набором полей разрешения.

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

Изменение полей разрешения оказывает влияние только во время разбора. Разбор текстовой строки происходит в двух фазах. Фаза 1 — это базовый текстовый разбор в соответствии с полями, добавленными в конструктор. Фаза 2 разрешает пары поле-значение, преобразованные в объекты даты и/или времени. Поля разрешения используются для фильтрации пар поле-значение между фазой 1 и 2.

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

Аналогичным образом, этот метод можно использовать для игнорирования вторичных полей, которые в противном случае проверялись бы на соответствие. Например, если форматировщик состоит из года, месяца, дня месяца и дня недели, то существует только один способ разрешения даты, но значение дня недели, полученное в результате разбора, будет проверяться на соответствие разрешённой дате. Вызов этого метода с аргументами YEAR, MONTH_OF_YEAR и DAY_OF_MONTH гарантирует, что дата будет разрешена правильно, но без проверки на соответствие дня недели.

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

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

Parameters:
resolverFields - новый набор полей разрешения, null, если полей нет
Returns:
форматировщик, основанный на этом форматировщике со стилем разрешения, запрошенным пользователем, не null

withResolverFields

public DateTimeFormatter withResolverFields(Set<TemporalField> resolverFields)

Возвращает копию этого форматировщика с новым набором полей разрешения.

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

Изменение полей разрешения оказывает влияние только во время разбора. Разбор текстовой строки происходит в двух фазах. Фаза 1 — это базовый текстовый разбор в соответствии с полями, добавленными в конструктор. Фаза 2 разрешает пары поле-значение, преобразованные в объекты даты и/или времени. Поля разрешения используются для фильтрации пар поле-значение между фазой 1 и 2.

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

Аналогичным образом, этот метод можно использовать для игнорирования вторичных полей, которые в противном случае проверялись бы на соответствие. Например, если форматировщик состоит из года, месяца, дня месяца и дня недели, то существует только один способ разрешения даты, но значение дня недели, полученное в результате разбора, будет проверяться на соответствие разрешённой дате. Вызов этого метода с аргументами YEAR, MONTH_OF_YEAR и DAY_OF_MONTH гарантирует, что дата будет разрешена правильно, но без проверки на соответствие дня недели.

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

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

Parameters:
resolverFields - новый набор полей разрешения, null, если полей нет
Returns:
форматировщик, основанный на этом форматировщике со стилем разрешения, запрошенным пользователем, не null

format

public String format(TemporalAccessor temporal)

Форматирует объект даты и времени с помощью этого форматировщика.

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

Parameters:
temporal - объект временной шкалы для форматирования, не null
Returns:
отформатированная строка, не null
Throws:
DateTimeException - если произошла ошибка во время форматирования

formatTo

public void formatTo(TemporalAccessor temporal,
                     Appendable appendable)

Форматирует объект даты и времени в Appendable с помощью этого форматировщика.

Это выводит отформатированную дату и время в указанное место назначения. Appendable — это интерфейс общего назначения, реализуемый всеми ключевыми классами вывода символов, включая StringBuffer, StringBuilder, PrintStream и Writer.

Хотя методы Appendable могут генерировать исключения IOException, этот метод этого не делает. Вместо этого любое исключение IOException обертывается в исключение времени выполнения.

Parameters:
temporal - объект временной шкалы для форматирования, не null
appendable - используемый объект для вывода, не null
Throws:
DateTimeException - если произошла ошибка во время форматирования

parse

public TemporalAccessor parse(CharSequence text)

Полностью разбирает текст, создавая объект временной шкалы.

Это разбирает весь текст, создавая объект временной шкалы. Обычно более полезно использовать parse(CharSequence, TemporalQuery). Результат этого метода — TemporalAccessor, который был разрешен, применяя базовые проверки валидации для обеспечения корректной даты и времени.

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

Parameters:
text - текст для разбора, не null
Returns:
разбор временного объекта, не null
Throws:
DateTimeParseException - если невозможно выполнить разбор запрошенного результата

parse

public TemporalAccessor parse(CharSequence text,
                              ParsePosition position)

Разбирает текст с помощью этого форматировщика, предоставляя контроль над позицией текста.

Это разбирает текст без необходимости начинать разбор с начала строки или заканчивать в конце. Результат этого метода — TemporalAccessor, который был разрешен, применяя базовые проверки валидации для обеспечения корректной даты и времени.

Текст будет разбираться с указанной начальной ParsePosition. Необходимо прочитать не весь текст, индекс ParsePosition будет обновлён с индексом окончания разбора.

Работа этого метода немного отличается от аналогичных методов, использующих ParsePosition в java.text.Format. Этот класс будет возвращать ошибки, используя индекс ошибки в ParsePosition. В отличие от этого, этот метод будет генерировать исключение DateTimeParseException, если произошла ошибка, и исключение будет содержать индекс ошибки. Это изменение поведения необходимо из-за повышенной сложности разбора и разрешения дат/времени в этом API.

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

Parameters:
text - текст для разбора, не null
position - позиция для разбора, обновлённая с длиной разбора и индексом любой ошибки, не null
Returns:
разбор временного объекта, не null
Throws:
DateTimeParseException - если невозможно выполнить разбор запрошенного результата
IndexOutOfBoundsException - если позиция неверна

parse

public <T> T parse(CharSequence text,
                   TemporalQuery<T> query)

Полностью разбирает текст, создавая объект указанного типа.

Большинство приложений должны использовать этот метод для разбора. Он разбирает весь текст, чтобы получить необходимую дату и время. Запрос обычно является ссылкой на метод from(TemporalAccessor) метода. Например: 

LocalDateTime dt = parser.parse(str, LocalDateTime::from);
Если разбор завершится без чтения всего текста или произойдёт ошибка во время разбора или объединения, то будет выброшено исключение.
Type Parameters:
T - тип разбираемой даты и времени
Parameters:
text - текст для разбора, не null
query - запрос, определяющий тип для разбора, не null
Returns:
разбираемая дата и время, не null
Throws:
DateTimeParseException - если невозможно выполнить разбор запрошенного результата

parseBest

public TemporalAccessor parseBest(CharSequence text,
                                  TemporalQuery<?>... queries)

Полностью разбирает текст, создавая объект одного из указанных типов.

Этот метод разбора удобен для использования, когда анализатор может обрабатывать необязательные элементы. Например, шаблон 'uuuu-MM-dd HH.mm[ VV]' может быть полностью разобран в ZonedDateTime, или частично разобран в LocalDateTime. Запросы должны быть указаны в порядке, начиная с наилучшего варианта полного разбора и заканчивая наихудшим вариантом минимального разбора. Запрос обычно является ссылкой на метод from(TemporalAccessor) метода.

Результат связан с первым типом, который успешно разбирается. Обычно приложения используют instanceof для проверки результата. Например: 

TemporalAccessor dt = parser.parseBest(str, ZonedDateTime::from, LocalDateTime::from);
  if (dt instanceof ZonedDateTime) {
   ...
  } else {
   ...
  }
Если разбор завершится без чтения всего текста или произойдёт ошибка во время разбора или объединения, то будет выброшено исключение.
Parameters:
text - текст для разбора, не null
queries - запросы, определяющие типы для попытки разбора, должны реализовывать TemporalAccessor, не null
Returns:
разбираемая дата и время, не null
Throws:
IllegalArgumentException - если указано менее 2 типов
DateTimeParseException - если невозможно выполнить разбор запрошенного результата

parseUnresolved

public TemporalAccessor parseUnresolved(CharSequence text,
                                        ParsePosition position)

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

Парсинг реализован как двухфазная операция. Сначала текст парсится с помощью макета, определённого форматером, что даёт Map поля к значению, ZoneId и Chronology. Во-вторых, распарсенные данные разрешаются, путём валидации, объединения и упрощения различных полей в более полезные. Данный метод выполняет стадию парсинга, но не стадию разрешения.

Результат этого метода — TemporalAccessor, который представляет данные так, как они видны в вводе. Значения не проверяются, поэтому парсинг строки даты '2012-00-65' приведёт к временной точке с тремя полями — годом '2012', месяцем '0' и днём месяца '65'.

Текст будет парситься с указанного начального ParsePosition. Необходимо, чтобы весь текст был распарсен, поле ParsePosition будет обновлено индексом в конце парсинга.

Ошибки возвращаются с помощью поля индекса ошибки в ParsePosition вместо DateTimeParseException. Возвращаемый индекс ошибки будет установлен на индекс, указывающий на ошибку. Вызывающие методы должны проверять наличие ошибок перед использованием результата.

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

Данный метод предназначен для расширенных случаев использования, требующих доступа к внутреннему состоянию во время парсинга. Типичный код приложения должен использовать parse(CharSequence, TemporalQuery) или метод парсинга на целевом типе.

Parameters:
text - текст для парсинга, не null
position - позиция для парсинга, обновляется с длиной парсинга и индексом любой ошибки, не null
Returns:
распарсенный текст, null, если парсинг привёл к ошибке
Throws:
DateTimeException - если во время парсинга произошла какая-либо проблема
IndexOutOfBoundsException - если позиция неверна

toFormat

public Format toFormat()

Возвращает этот форматер как экземпляр java.text.Format.

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

Исключения будут следовать определениям Format, см. эти методы для получения информации об IllegalArgumentException во время форматирования и ParseException или null при парсинге. Формат не поддерживает присвоение атрибутов возвращаемой строке формата.

Returns:
этот форматер как экземпляр классического формата, не null

toFormat

public Format toFormat(TemporalQuery<?> parseQuery)

Возвращает этот форматер как экземпляр java.text.Format экземпляра, который будет парсить с помощью указанного запроса.

Возвращаемый экземпляр Format будет форматировать любой TemporalAccessor и парсить к типу, указанному. Тип должен быть таким, который поддерживается parse(java.lang.CharSequence).

Исключения будут следовать определениям Format, см. эти методы для получения информации об IllegalArgumentException во время форматирования и ParseException или null при парсинге. Формат не поддерживает присвоение атрибутов возвращаемой строке формата.

Parameters:
parseQuery - запрос, определяющий тип для парсинга, не null
Returns:
этот форматер как экземпляр классического формата, не null

toString

public String toString()

Возвращает описание базовых форматеров.

Overrides:
toString в классе Object
Returns:
описание этого форматера, не 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/DateTimeFormatter.html

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