Пакет 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.