Класс DateTimeFormatter

java.lang.Object
- java.time.format.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`	Дата и время с часовым поясом	'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'

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

Шаблоны основаны на простом наборе букв и символов. Шаблон используется для создания Formatter с помощью методов 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' зарезервированы как символы шаблона. Определены следующие символы шаблона:

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

   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       week-of-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-am-pm (1-24)  number            0

   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
   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

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

Текст: Стиль текста определяется на основе количества используемых символов шаблона. Менее 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.

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

Имена часовых поясов: Выводит отображаемое имя идентификатора часового пояса. Если количество символов равно одному, двум или трём, выводится короткое имя. Если количество символов равно четырём, выводится полное имя. Пять или более символов вызывает 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...) позволяет отфильтровать набор полей, которые будут разрешены, перед началом разрешения. Например, если форматировщик проанализировал год, месяц, день месяца и день года, то есть два подхода к разрешению даты: (год + месяц + день месяца) и (год + день года). Параметр resolver fields позволяет выбрать один из двух подходов. Если поля resolver не установлены, оба подхода должны привести к одной и той же дате.

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

Определяется хронология. Хронология результата — это либо хронология, которая была проанализирована, либо, если хронология не была проанализирована, это хронология, установленная в этом классе, или, если она равна null, это IsoChronology.
Разрешаются поля даты ChronoField. Это достигается с помощью Chronology.resolveDate(Map, ResolverStyle). Документация по разрешению полей находится в реализации Chronology.
Разрешаются поля времени ChronoField. Это документировано в ChronoField и одинаково для всех хронологий.
Обрабатываются любые поля, которые не ChronoField . Это достигается с помощью TemporalField.resolve(Map, TemporalAccessor, ResolverStyle). Документация по разрешению полей находится в реализации TemporalField.
Поля даты и времени ChronoField переразрешаются. Это позволяет полям на четвёртом шаге генерировать значения ChronoField и обрабатывать их в даты и время.
Формируется LocalTime , если доступно хотя бы значение часа дня. Это включает в себя предоставление значений по умолчанию для минут, секунд и долей секунды.
Любые оставшиеся неразрешённые поля проверяются на соответствие любой разрешённой дате и/или времени. Таким образом, на предыдущем этапе (год + месяц + день месяца) разрешалось в дату, а на этом этапе проверялось, является ли день недели допустимым для даты.
Если был проанализирован избыточный номер дней, то он добавляется к дате, если дата доступна.

Требования к реализации:: Этот класс неизменяемый и потокобезопасный.
С:: 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()` Возвращает переопределённую зону, используемую во время форматирования.
`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(Set<TemporalField> resolverFields)` Возвращает копию этого форматера с новым набором полей разрешения.
`DateTimeFormatter`	`withResolverFields(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_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_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. Анализ нечувствителен к регистру.

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.

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_OFFSET_DATE_TIME

public static final DateTimeFormatter ISO_OFFSET_DATE_TIME

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

Форматировщика ISO_LOCAL_DATE_TIME
Идентификатора offset ID. Если смещение содержит секунды, они будут обработаны, даже если это не часть стандарта ISO-8601. Анализ нечувствителен к регистру.

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_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. Анализ чувствителен к регистру.
Закрывающей квадратной скобки ']'.

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. Анализ нечувствителен к регистру.

ISO_INSTANT

public static final DateTimeFormatter ISO_INSTANT

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

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

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

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

ISO_OFFSET_DATE_TIME, где мгновенный момент преобразуется из ChronoField.INSTANT_SECONDS и ChronoField.NANO_OF_SECOND с помощью смещения 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. Анализ нечувствителен к регистру.

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". Не обрабатываются североамериканские и военные названия зон.

Анализ нечувствителен к регистру.

Methods

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.

Parameters:: pattern - используемый шаблон, не null
Returns:: форматтер, основанный на шаблоне, не null
Throws:: IllegalArgumentException - если шаблон недействителен
See Also:: DateTimeFormatterBuilder.appendPattern(String)

ofPattern

public static DateTimeFormatter ofPattern(String pattern,
                                          Locale locale)

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

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

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

Parameters:: pattern - используемый шаблон, не null; locale - используемая локаль, не null
Returns:: форматтер, основанный на шаблоне, не null
Throws:: IllegalArgumentException - если шаблон недействителен
See Also:: 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.

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

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

ofLocalizedDateTime

public static DateTimeFormatter ofLocalizedDateTime(FormatStyle dateTimeStyle)

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

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

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

ofLocalizedDateTime

public static DateTimeFormatter ofLocalizedDateTime(FormatStyle dateStyle,
                                                    FormatStyle timeStyle)

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

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

parsedExcessDays

public static final TemporalQuery<Period> parsedExcessDays()

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

Возвращает одиночный запрос, который предоставляет доступ к дополнительной информации из анализа. Запрос всегда возвращает не-null период, возвращая нулевой период вместо 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()

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

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

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

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

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

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, удаляя все поля, кроме тех, которые указаны в качестве аргументов этого метода.

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

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

withResolverFields

public DateTimeFormatter withResolverFields(Set<TemporalField> resolverFields)

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

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

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

format

public String format(TemporalAccessor temporal)

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

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

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

formatTo

public void formatTo(TemporalAccessor temporal,
                     Appendable appendable)

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

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

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

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

parse

public TemporalAccessor parse(CharSequence text)

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

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

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

Параметры:: text - текст для анализа, не null
Возвращает:: разрешенный временной объект, не null
Выбрасывает:: DateTimeParseException - если невозможно проанализировать запрашиваемый результат

parse

public TemporalAccessor parse(CharSequence text,
                              ParsePosition position)

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

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

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

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

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

Параметры:: text - текст для анализа, не null; position - позиция для начала анализа, обновляется с длиной проанализированного текста и индексом любой ошибки, не null
Возвращает:: разрешенный временной объект, не null
Выбрасывает:: DateTimeParseException - если невозможно проанализировать запрашиваемый результат; IndexOutOfBoundsException - если позиция неверна

parse

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

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

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

LocalDateTime dt = parser.parse(str, LocalDateTime::from);

Тип параметров:: T - тип анализируемого объекта даты и времени
Параметры:: text - текст для анализа, не null; query - запрос, определяющий тип для анализа, не null
Возвращает:: проанализированное время, не null
Выбрасывает:: 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 {
   ...
  }

Параметры:: text - текст для анализа, не null; queries - запросы, определяющие типы, которые нужно попытаться проанализировать, должны реализовывать TemporalAccessor, не null
Возвращает:: проанализированное время, не null
Выбрасывает:: IllegalArgumentException - если указано менее 2 типов; DateTimeParseException - если невозможно проанализировать запрашиваемый результат

parseUnresolved

public TemporalAccessor parseUnresolved(CharSequence text,
                                        ParsePosition position)

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

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

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

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

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

Параметры:: text - текст для анализа, не null; position - позиция для начала анализа, обновляется с длиной проанализированного текста и индексом любой ошибки, не null
Возвращает:: проанализированный текст, null, если анализ завершился ошибкой
Выбрасывает:: DateTimeException - если во время анализа произошла какая-либо проблема; IndexOutOfBoundsException - если позиция неверна

toFormat

public Format toFormat()

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

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

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

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

toFormat

public Format toFormat(TemporalQuery<?> parseQuery)

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

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

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

toString

public String toString()

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

Переопределяет:: toString в классе Object
Возвращает:: описание этого форматера, не 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.