Интерфейс TemporalUnit

Duration getDuration()

Возвращает длительность этой единицы, которая может быть приблизительной.

Все единицы возвращают этим методом длительность, измеряемую в стандартных наносекундах. Длительность будет положительной и ненулевой. Например, длительность часа составляет 60 * 60 * 1,000,000,000ns.

Для некоторых единиц длительность может быть точной, а для других — приблизительной. Например, длительность дня считается приблизительной из-за возможного перехода на летнее время. Чтобы определить, является ли длительность приблизительной, используйте isDurationEstimated().

boolean isDurationEstimated()

Проверяет, является ли длительность единицы приблизительной.

У всех единиц есть длительность, однако она не всегда точна. Например, длительность дня считается приблизительной из-за возможного перехода на летнее время. Этот метод возвращает true, если длительность приблизительная, и false, если она точная. Обратите внимание, что понятие точной или приблизительной длительности не учитывает високосные секунды.

boolean isDateBased()

Проверяет, представляет ли эта единица компонент даты.

Единица относится к дате, если ее можно использовать для определения значения даты. Ее длительность должна быть целым кратным продолжительности стандартного дня. Обратите внимание, что допустимо, если и isDateBased(), и isTimeBased() возвращают false, например при представлении единицы длительностью 36 часов.

boolean isTimeBased()

Проверяет, представляет ли эта единица компонент времени.

Единица относится ко времени, если ее можно использовать для определения значения времени. Ее длительность должна без остатка делить продолжительность стандартного дня. Обратите внимание, что допустимо, если и isDateBased(), и isTimeBased() возвращают false, например при представлении единицы длительностью 36 часов.

default boolean isSupportedBy(Temporal temporal)

Проверяет, поддерживается ли эта единица указанным объектом даты и времени.

Проверяет, может ли реализующий интерфейс объект даты и времени прибавлять или вычитать эту единицу. Это позволяет избежать выбрасывания исключения.

Эта реализация по умолчанию получает значение с помощью Temporal.plus(long, TemporalUnit).

<R extends Temporal> R addTo(R temporal, long amount)

Возвращает копию указанного объекта даты и времени с добавленным указанным периодом.

Добавляемый период является кратным этой единице. Например, этот метод можно использовать, чтобы добавить «3 дня» к дате: для этого нужно вызвать метод у экземпляра, представляющего «дни», передав дату и период «3». Добавляемый период может быть отрицательным, что эквивалентно вычитанию.

Этот метод можно использовать двумя равнозначными способами. Первый — вызвать его напрямую. Второй — использовать Temporal.plus(long, TemporalUnit):

  // these two lines are equivalent, but the second approach is recommended
  temporal = thisUnit.addTo(temporal);
  temporal = temporal.plus(thisUnit);

Рекомендуется использовать второй подход, plus(TemporalUnit), поскольку такой код гораздо понятнее.

Реализации должны выполнять запросы и вычисления с использованием единиц, доступных в ChronoUnit, или полей, доступных в ChronoField. Если единица не поддерживается, необходимо выбросить UnsupportedTemporalTypeException.

Реализации не должны изменять указанный объект даты и времени. Вместо этого необходимо вернуть скорректированную копию исходного объекта. Это обеспечивает эквивалентное и безопасное поведение для неизменяемых и изменяемых реализаций.

long between(Temporal temporal1Inclusive, Temporal temporal2Exclusive)

Вычисляет промежуток времени между двумя объектами даты и времени.

Вычисляет промежуток в единицах этого типа. Начальная и конечная точки задаются объектами даты и времени, которые должны быть совместимых типов. Перед вычислением количества реализация преобразует объект второго типа в экземпляр первого типа. Результат будет отрицательным, если конечная точка предшествует начальной. Например, количество часов между двумя объектами даты и времени можно вычислить с помощью HOURS.between(startTime, endTime).

Вычисление возвращает целое число, представляющее количество полных единиц между двумя объектами даты и времени. При наличии полей меньших единиц их значения учитываются при определении итогового целого числа. Например, промежуток в часах между временем 11:30 и 13:29 составляет всего один час, поскольку до двух часов не хватает одной минуты; промежуток в месяцах между датами 2024-09-29 и 2025-02-28 (последним днем февраля) составляет 4 месяца, поскольку до пяти месяцев не хватает одного дня.

Этот метод можно использовать двумя равнозначными способами. Первый — вызвать его напрямую. Второй — использовать Temporal.until(Temporal, TemporalUnit):

  // these two lines are equivalent
  between = thisUnit.between(start, end);
  between = start.until(end, thisUnit);

Выбор способа зависит от того, какой из них делает код более понятным.

Например, с помощью этого метода можно вычислить количество дней между двумя датами:

 long daysBetween = DAYS.between(start, end);
 // or alternatively
 long daysBetween = start.until(end, DAYS);

Реализации должны выполнять запросы и вычисления с использованием единиц, доступных в ChronoUnit, или полей, доступных в ChronoField. Если единица не поддерживается, необходимо выбросить UnsupportedTemporalTypeException. Реализации не должны изменять указанные объекты даты и времени.

String toString()

Возвращает описательное имя единицы.

Имя должно быть во множественном числе и записано в верхнем верблюжьем регистре, например 'Days' или 'Minutes'.