Интерфейс TemporalAmount

Все известные подинтерфейсы:: ChronoPeriod

Все известные реализующие классы:: Duration, Period

public interface TemporalAmount

Интерфейс уровня инфраструктуры, определяющий величину времени, например «6 часов», «8 дней» или «2 года и 3 месяца».

Это базовый тип интерфейса для величин времени. Величина отличается от даты или времени суток тем, что не привязана к какой-либо конкретной точке на временной шкале.

Величину можно представить как Map из TemporalUnit в long, доступный через getUnits() и get(TemporalUnit). Простой случай может включать одну пару «единица-значение», например «6 часов». Более сложный случай может включать несколько таких пар, например «7 лет, 3 месяца и 5 дней».

Существует две распространённые реализации. Period — реализация для дат, хранящая годы, месяцы и дни. Duration — реализация для времени, хранящая секунды и наносекунды, но предоставляющая доступ к некоторым другим единицам длительности, например минутам, часам и суткам фиксированной продолжительности в 24 часа.

Этот интерфейс является интерфейсом уровня инфраструктуры, который не следует широко использовать в коде приложений. Вместо этого приложениям следует создавать и передавать экземпляры конкретных типов, например Period и Duration.

Требования к реализации:: Этот интерфейс не накладывает ограничений на изменяемость реализаций, однако настоятельно рекомендуется делать их неизменяемыми.
Начиная с:: 1.8

Краткое описание методов

Модификатор и тип	Метод	Описание
`Temporal`	`addTo(Temporal temporal)`	Добавляет величину к указанному временному объекту.
`long`	`get(TemporalUnit unit)`	Возвращает значение запрошенной единицы.
`List<TemporalUnit>`	`getUnits()`	Возвращает список единиц, однозначно определяющих значение этого TemporalAmount.
`Temporal`	`subtractFrom(Temporal temporal)`	Вычитает этот объект из указанного временного объекта.

Подробное описание методов

get

long get(TemporalUnit unit)

Возвращает значение запрошенной единицы. Единицы, возвращаемые методом getUnits(), однозначно определяют значение TemporalAmount. Значение должно возвращаться для каждой единицы, указанной в getUnits.

Требования к реализации:: Реализации могут объявлять поддержку единиц, не перечисленных в getUnits(). Обычно реализация определяет дополнительные единицы как преобразования для удобства разработчиков.
Параметры:: unit — единица TemporalUnit, значение которой нужно вернуть
Возвращает:: значение единицы типа long
Исключения:: DateTimeException — если не удаётся получить значение единицы; UnsupportedTemporalTypeException — если unit не поддерживается

getUnits

List<TemporalUnit> getUnits()

Возвращает список единиц, однозначно определяющих значение этого TemporalAmount. Список TemporalUnits определяется классом реализации. Этот список представляет собой снимок единиц на момент вызова getUnits и не подлежит изменению. Единицы упорядочены от самой продолжительной к самой короткой.

Требования к реализации:: Список единиц полностью и однозначно представляет состояние объекта, без пропусков, пересечений и дублирования. Единицы упорядочены от самой продолжительной к самой короткой.
Возвращает:: список TemporalUnits; не null

addTo

Temporal addTo(Temporal temporal)

Добавляет величину к указанному временному объекту.

Добавляет величину к указанному временному объекту, используя логику, реализованную в классе реализации.

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

  // These two lines are equivalent, but the second approach is recommended
  dateTime = amount.addTo(dateTime);
  dateTime = dateTime.plus(adder);

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

Требования к реализации:

Реализация должна принять входной объект и добавить величину к нему. Реализация определяет логику сложения и отвечает за её документирование. Для получения сведений о временном объекте и выполнения сложения можно использовать любой метод Temporal. Тип возвращаемого объекта должен совпадать с наблюдаемым типом входного объекта.

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

Входной временной объект может относиться к календарной системе, отличной от ISO. Реализации могут документировать совместимость с другими календарными системами или отклонять временные объекты, не относящиеся к ISO, с помощью querying the chronology.

Этот метод может вызываться параллельно из нескольких потоков. При вызове он должен быть потокобезопасным.

Параметры:

temporal — временной объект, к которому нужно добавить величину; не null

Возвращает:

объект того же наблюдаемого типа с выполненным сложением; не null

Исключения:

DateTimeException — если выполнить сложение не удалось

ArithmeticException — при переполнении числового значения

subtractFrom

Temporal subtractFrom(Temporal temporal)

Вычитает этот объект из указанного временного объекта.

Вычитает величину из указанного временного объекта, используя логику, реализованную в классе реализации.

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

  // these two lines are equivalent, but the second approach is recommended
  dateTime = amount.subtractFrom(dateTime);
  dateTime = dateTime.minus(amount);

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

Требования к реализации:

Реализация должна принять входной объект и вычесть величину из него. Реализация определяет логику вычитания и отвечает за её документирование. Для получения сведений о временном объекте и выполнения вычитания можно использовать любой метод Temporal. Тип возвращаемого объекта должен совпадать с наблюдаемым типом входного объекта.

Этот метод может вызываться параллельно из нескольких потоков. При вызове он должен быть потокобезопасным.

Параметры:

temporal — временной объект, из которого нужно вычесть величину; не null

Возвращает:

объект того же наблюдаемого типа с выполненным вычитанием; не null

Исключения:

DateTimeException — если выполнить вычитание не удалось

ArithmeticException — при переполнении числового значения

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/time/temporal/TemporalAmount.html