Интерфейс TemporalField

Все известные реализующие классы:: ChronoField

public interface TemporalField

Поле даты и времени, например, месяц года или час минуты.

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

Наиболее часто используемые единицы определены в ChronoField. Дополнительные поля представлены в IsoFields, WeekFields и JulianFields. Поля также могут быть записаны кодом приложения путём реализации этого интерфейса.

Поле работает с помощью двойной диспетчеризации. Клиентский код вызывает методы на объекте даты и времени, например, LocalDateTime, которые проверяют, является ли поле ChronoField. Если это так, то объект даты и времени должен обработать его. В противном случае вызов метода повторно диспетчеризуется в соответствующий метод в этом интерфейсе.

Требования к реализации:: Этот интерфейс должен быть реализован с осторожностью, чтобы гарантировать правильную работу других классов. Все реализации, которые могут быть созданы, должны быть final, неизменяемыми и потокобезопасными. Реализации должны быть Serializable по возможности. Перечисление является эффективным выбором реализации.
С:: 1.8

Методы

Модификатор и тип	Метод	Описание
`<R extends Temporal> R`	`adjustInto(R temporal, long newValue)`	Возвращает копию указанного временного объекта со значением этого поля, установленным.
`TemporalUnit`	`getBaseUnit()`	Возвращает единицу измерения поля.
`default String`	`getDisplayName(Locale locale)`	Возвращает имя поля для отображения в запрошенном языке.
`long`	`getFrom(TemporalAccessor temporal)`	Возвращает значение этого поля из указанного временного объекта.
`TemporalUnit`	`getRangeUnit()`	Проверяет, представляет ли это поле компонент даты.
`boolean`	`isDateBased()`	Проверяет, поддерживается ли это поле временным объектом.
`boolean`	`isSupportedBy(TemporalAccessor temporal)`	Проверяет, представляет ли это поле компонент времени.
`boolean`	`isTimeBased()`	Возвращает диапазон допустимых значений для поля.
`ValueRange`	`range()`	Возвращает диапазон допустимых значений для этого поля, используя временной объект для уточнения результата.
`ValueRange`	`rangeRefinedBy(TemporalAccessor temporal)`	Разрешает это поле для предоставления более простого альтернативного или даты.
`default TemporalAccessor`	`resolve(Map<TemporalField,Long> fieldValues, TemporalAccessor partialTemporal, ResolverStyle resolverStyle)`	Возвращает описательное имя поля.

Методы

getDisplayName

default String getDisplayName(Locale locale)

Возвращает имя поля для указанного языка.

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

Реализация по умолчанию должна проверить, что язык не null, и вернуть toString().

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

getBaseUnit

TemporalUnit getBaseUnit()

Возвращает единицу измерения поля.

Единица измерения поля — это период, в котором изменяется значение поля. Например, в поле 'MonthOfYear' единицей измерения является 'Months'. См. также getRangeUnit().

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

getRangeUnit

TemporalUnit getRangeUnit()

Возвращает диапазон, в котором ограничено поле.

Диапазон поля — это период, в котором изменяется значение поля. Например, в поле 'MonthOfYear' диапазоном является 'Years'. См. также getBaseUnit().

Диапазон никогда не равен null. Например, поле 'Year' является сокращением для 'YearOfForever'. Следовательно, оно имеет единицу измерения 'Years' и диапазон 'Forever'.

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

range

ValueRange range()

Возвращает диапазон допустимых значений для поля.

Все поля могут быть выражены как long целое число. Этот метод возвращает объект, описывающий допустимый диапазон для этого значения. Этот метод обычно применим только к календарной системе ISO-8601.

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

Возвращает:: диапазон допустимых значений для поля, не null

isDateBased

boolean isDateBased()

Проверяет, представляет ли это поле компонент даты.

Поле является основанным на дате, если оно может быть получено из EPOCH_DAY. Обратите внимание, что для isDateBased() и isTimeBased() допустимо возвращать false, например, при представлении такого поля, как минута недели.

Возвращает:: true, если это поле является компонентом даты

isTimeBased

boolean isTimeBased()

Проверяет, представляет ли это поле компонент времени.

Поле является основанным на времени, если оно может быть получено из NANO_OF_DAY. Обратите внимание, что для isDateBased() и isTimeBased() допустимо возвращать false, например, при представлении такого поля, как минута недели.

Возвращает:: true, если это поле является компонентом времени

isSupportedBy

boolean isSupportedBy(TemporalAccessor temporal)

Проверяет, поддерживает ли временной объект это поле.

Это определяет, поддерживает ли временной объект это поле. Если это возвращает false, то временной объект не может быть запрошен для этого поля.

Существует два эквивалентных способа использования этого метода. Первый — вызвать этот метод напрямую. Второй — использовать TemporalAccessor.isSupported(TemporalField):

// these two lines are equivalent, but the second approach is recommended
   temporal = thisField.isSupportedBy(temporal);
   temporal = temporal.isSupported(thisField);

Рекомендуется использовать второй подход, isSupported(TemporalField), так как он намного понятнее в коде.

Реализации должны определять, поддерживаются ли они с помощью полей, доступных в ChronoField.

Параметры:: temporal - временной объект для запроса, не null
Возвращает:: true, если дату-время можно запросить для этого поля, false — если нет

rangeRefinedBy

ValueRange rangeRefinedBy(TemporalAccessor temporal)

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

Это использует временной объект для определения диапазона допустимых значений для поля. Это аналогично range(), но этот метод уточняет результат с помощью временного объекта. Например, если поле — DAY_OF_MONTH, то метод range не точен, так как существует четыре возможных длины месяца: 28, 29, 30 и 31 день. Использование этого метода с датой позволяет получить точный диапазон, возвращая только один из этих четырех вариантов.

Существует два эквивалентных способа использования этого метода. Первый — вызвать этот метод напрямую. Второй — использовать TemporalAccessor.range(TemporalField):

// these two lines are equivalent, but the second approach is recommended
   temporal = thisField.rangeRefinedBy(temporal);
   temporal = temporal.range(thisField);

Рекомендуется использовать второй подход, range(TemporalField), так как он намного понятнее в коде.

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

Параметры:: temporal - временной объект, используемый для уточнения результата, не null
Возвращает:: диапазон допустимых значений для этого поля, не null
Выбрасывает:: DateTimeException - если диапазон для поля получить невозможно; UnsupportedTemporalTypeException - если поле не поддерживается временным объектом

getFrom

long getFrom(TemporalAccessor temporal)

Возвращает значение этого поля из указанного временного объекта.

Этот метод запрашивает значение этого поля у временного объекта.

Существует два эквивалентных способа использования этого метода. Первый — вызвать этот метод напрямую. Второй — использовать TemporalAccessor.getLong(TemporalField) (или TemporalAccessor.get(TemporalField)):

// these two lines are equivalent, but the second approach is recommended
   temporal = thisField.getFrom(temporal);
   temporal = temporal.getLong(thisField);

Рекомендуется использовать второй подход, getLong(TemporalField), так как он намного понятнее в коде.

Параметры:: temporal - временной объект для запроса, не null
Возвращает:: значение этого поля, не null
Выбрасывает:: DateTimeException - если значение для поля получить невозможно; UnsupportedTemporalTypeException - если поле не поддерживается временным объектом; ArithmeticException - если происходит переполнение числовых данных

adjustInto

<R extends Temporal> R adjustInto(R temporal,
                                  long newValue)

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

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

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

Существует два эквивалентных способа использования этого метода. Первый — вызвать этот метод напрямую. Второй — использовать Temporal.with(TemporalField, long):

// these two lines are equivalent, but the second approach is recommended
   temporal = thisField.adjustInto(temporal);
   temporal = temporal.with(thisField);

Рекомендуется использовать второй подход, with(TemporalField), так как он намного понятнее в коде.

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

Параметры типов:: R - тип временного объекта
Параметры:: temporal - временной объект для изменения, не null; newValue - новое значение поля
Возвращает:: измененный временной объект, не null
Выбрасывает:: DateTimeException - если поле нельзя установить; UnsupportedTemporalTypeException - если поле не поддерживается временным объектом; ArithmeticException - если происходит переполнение числовых данных

resolve

default TemporalAccessor resolve(Map<TemporalField,Long> fieldValues,
                                 TemporalAccessor partialTemporal,
                                 ResolverStyle resolverStyle)

Разрешает это поле, чтобы предоставить более простой вариант или дату.

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

Приложения обычно не должны вызывать этот метод напрямую.

Требования к реализации:

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

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

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

Например, класс IsoFields содержит поля четверть года и день четверти. Реализация этого метода в этом классе разрешает два поля плюс поле YEAR в полное LocalDate. Метод разрешения удалит все три поля из карты перед возвращением LocalDate.

Частично завершённая временная шкала используется для запроса хронологии и зоны. В общем случае потребуется только хронология. Запрос элементов, отличных от зоны или хронологии, не определён и не должен использоваться. Поведение других методов, таких как get, getLong, range и isSupported, непредсказуемо, а результаты не определены.

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

При разрешении полей времени карта будет изменена, а возвращённое значение — null. При разрешении полей дат дата обычно возвращается из метода, а карта изменяется для удаления разрешённых полей. Однако также допустимо, чтобы поля дат разрешались в другие экземпляры ChronoField, которые могут создавать дату, такие как EPOCH_DAY.

Не все TemporalAccessor реализации принимаются в качестве возвращаемых значений. Реализации, вызывающие этот метод, должны принимать ChronoLocalDate, ChronoLocalDateTime, ChronoZonedDateTime и LocalTime.

Реализация по умолчанию должна вернуть null.

Параметры:

fieldValues - карта полей и значений, которую можно обновить, не null

partialTemporal - частично завершённая временная шкала для запроса зоны и хронологии; запрос других вещей не определён и не рекомендуется, не null

resolverStyle - запрашиваемый тип разрешения, не null

Возвращает:

объект разрешённой временной шкалы; null, если разрешение только изменило карту или разрешение не произошло

Исключения:

ArithmeticException - если произошёл переполнение чисел

DateTimeException - если разрешение привело к ошибке. Это не должно выбрасываться при запросе поля у временной шкалы без предварительной проверки поддержки этого поля

toString

String toString()

Получает описательное имя для поля.

Должно быть в формате 'BaseOfRange', например, 'MonthOfYear', если поле не имеет диапазона FOREVER, а упоминается только базовая единица, например, 'Year' или 'Era'.

Переопределяет:: 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.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/temporal/TemporalField.html