Пакет 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"). Исключение NullPointerException не документируется в каждом методе явно.

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