Пакет java.time.temporal

Доступ к дате и времени с использованием полей и единиц измерения, а также корректоров даты и времени.

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

• Единицы измерения даты и времени, такие как годы, месяцы, дни и часы
• Поля даты и времени, такие как месяц года, день недели или час
• Функции корректировки даты и времени
• Различные определения недель

Поля и единицы

Даты и время выражаются через поля и единицы. Единица используется для измерения промежутка времени, например, лет, дней или минут. Все единицы реализуют TemporalUnit. Набор известных единиц определён в ChronoUnit, например DAYS. Интерфейс единиц разработан для поддержки прикладных единиц.

Поле используется для выражения части большей даты и времени, например, года, месяца или секунды. Все поля реализуют TemporalField. Набор известных полей определен в ChronoField, например HOUR_OF_DAY. Дополнительные поля определены в JulianFields, WeekFields и IsoFields. Интерфейс полей разработан для поддержки прикладных полей.

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

Одно из применений полей в прикладном коде — извлечение полей, для которых нет удобного метода. Например, получение дня месяца достаточно часто используется, и для этого есть метод в LocalDate под названием getDayOfMonth(). Однако для более необычных полей необходимо использовать поле. Например, date.get(ChronoField.ALIGNED_WEEK_OF_MONTH). Поля также обеспечивают доступ к диапазону допустимых значений.

Корректировка и запрос

Ключевая часть пространства проблем даты и времени — корректировка даты до нового, связанного значения, такого как «последний день месяца» или «следующая среда». Эти операции моделируются как функции, корректирующие базовую дату и время. Функции реализуют TemporalAdjuster и действуют на Temporal. Набор общих функций предоставлен в TemporalAdjusters. Например, чтобы найти первое вхождение дня недели после заданной даты, используйте TemporalAdjusters.next(DayOfWeek), например date.with(next(MONDAY)). Приложения также могут определять корректирующие функции, реализуя TemporalAdjuster.

Интерфейс TemporalAmount моделирует величины относительного времени.

В дополнение к корректировке даты и времени предоставлен интерфейс для запросов с помощью TemporalQuery. Наиболее распространённые реализации интерфейса запроса — это ссылки на методы. Методы from(TemporalAccessor) в основных классах могут использоваться, например, LocalDate::from или Month::from. Дополнительные реализации предоставлены в TemporalQueries в виде статических методов. Приложения также могут определять запросы, реализуя TemporalQuery.

Недели

В разных регионах существуют различные определения недель. Например, в Европе неделя обычно начинается с понедельника, а в США — с воскресенья. Класс WeekFields моделирует это различие.

Система календаря ISO определяет дополнительное деление лет на недели. Это определяет год на основе целых недель с понедельника по понедельник. Это смоделировано в IsoFields.

Спецификация пакета

Если не указано иное, передача null-аргумента в конструктор или метод любого класса или интерфейса в этом пакете вызовет исключение NullPointerException. Описание null-поведения приведено в документации Javadoc "@param". Исключение "@throws NullPointerException" не документировано явно в каждом методе.

Все вычисления должны проверять переполнение числовых типов и выбрасывать либо ArithmeticException, либо DateTimeException.