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