Интерфейс 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 - единица, для которой нужно вернуть значение
Возвращает:: значение 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/time/temporal/TemporalAmount.html