Пакет 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. Описание в Javadoc «@param» используется для обобщения поведения при null-значениях. Исключение «@throws NullPointerException» не документировано явно в каждом методе.

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