Интерфейс 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 и не изменяется. Единицы упорядочены от самой большой длительности к самой короткой.

Требования к реализации:: Список единиц полностью и однозначно представляет состояние объекта без пропусков, перекрытий или дублирования. Единицы упорядочены от самой большой длительности к самой короткой.
Возвращает:: список единиц; не 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, 2021, 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/17/docs/api/java.base/java/time/temporal/TemporalAmount.html