Интерфейс 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, 2023, 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/21/docs/api/java.base/java/time/temporal/TemporalAmount.html