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