Интерфейс ChronoPeriod

Все суперинтерфейсы:: TemporalAmount

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

public interface ChronoPeriod extends TemporalAmount

Временной интервал, основанный на дате, например, '3 года, 4 месяца и 5 дней' в произвольной хронологии, предназначенный для сложных задач глобализации.

Этот интерфейс моделирует временной интервал, основанный на дате, в календарной системе. Хотя большинство календарных систем используют годы, месяцы и дни, некоторые не используют. Поэтому этот интерфейс работает только с набором поддерживаемых единиц, определенных Chronology. Набор поддерживаемых единиц фиксирован для данной хронологии. Значение поддерживаемой единицы может быть равно нулю.

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

Требования к реализации:: Этот интерфейс должен быть реализован с осторожностью, чтобы обеспечить правильную работу других классов. Все реализуемые классы, которые могут быть созданы, должны быть final, неизменяемыми и потокобезопасными. Подклассы должны быть сериализуемыми, где это возможно.
С:: 1.8

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

Модификатор и тип	Метод	Описание
`Temporal`	`addTo(Temporal temporal)`	Добавляет этот период к указанному временнному объекту.
`static ChronoPeriod`	`between(ChronoLocalDate startDateInclusive, ChronoLocalDate endDateExclusive)`	Получает `ChronoPeriod`, состоящий из интервала времени между двумя датами.
`boolean`	`equals(Object obj)`	Проверяет, равен ли этот период другому периоду, включая хронологию.
`long`	`get(TemporalUnit unit)`	Получает значение запрошенной единицы.
`Chronology`	`getChronology()`	Получает хронологию, определяющую смысл поддерживаемых единиц.
`List<TemporalUnit>`	`getUnits()`	Получает набор единиц, поддерживаемых этим периодом.
`int`	`hashCode()`	Хеш-код для этого периода.
`default boolean`	`isNegative()`	Проверяет, является ли какой-либо из поддерживаемых единиц периода отрицательной.
`default boolean`	`isZero()`	Проверяет, равны ли все поддерживаемые единицы периода нулю.
`ChronoPeriod`	`minus(TemporalAmount amountToSubtract)`	Возвращает копию этого периода, из которого вычтен указанный период.
`ChronoPeriod`	`multipliedBy(int scalar)`	Возвращает новый экземпляр, в котором каждое значение в этом периоде умножено на указанный скаляр.
`default ChronoPeriod`	`negated()`	Возвращает новый экземпляр, в котором каждое значение в этом периоде изменено на противоположное.
`ChronoPeriod`	`normalized()`	Возвращает копию этого периода с нормализованными значениями каждой единицы.
`ChronoPeriod`	`plus(TemporalAmount amountToAdd)`	Возвращает копию этого периода с добавленным указанным периодом.
`Temporal`	`subtractFrom(Temporal temporal)`	Вычитает этот период из указанного временного объекта.
`String`	`toString()`	Выводит этот период в виде `String`.

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

between

static ChronoPeriod between(ChronoLocalDate startDateInclusive, ChronoLocalDate endDateExclusive)

Получает период времени между двумя датами.

Начальная дата включена, а конечная — нет. Период рассчитывается с использованием ChronoLocalDate.until(ChronoLocalDate). Таким образом, вычисление зависит от хронологии.

Используется хронология первой даты. Хронология второй даты игнорируется, а дата преобразуется в целевую систему хронологии перед началом расчёта.

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

Параметры:

startDateInclusive - начальная дата, включающаяся, определяющая хронологию расчета, не null

endDateExclusive - конечная дата, исключающаяся, в любой хронологии, не null

Возвращает:

период между этой датой и конечной датой, не null

См. также:

get

long get(TemporalUnit unit)

Получает значение запрошенного временного интервала.

Поддерживаемые интервалы зависят от хронологии. Обычно это YEARS, MONTHS и DAYS. Запрос неподдерживаемого интервала вызовет исключение.

Определено в:: get в интерфейсе TemporalAmount
Параметры:: unit - TemporalUnit, значение которого необходимо вернуть
Возвращает:: целое значение интервала
Исключения:: DateTimeException - если интервал не поддерживается; UnsupportedTemporalTypeException - если интервал не поддерживается

getUnits

List<TemporalUnit> getUnits()

Получает набор поддерживаемых интервалов этим периодом.

Поддерживаемые интервалы зависят от хронологии. Обычно это YEARS, MONTHS и DAYS. Они возвращаются в порядке убывания.

Этот набор может быть использован совместно с get(TemporalUnit) для доступа ко всему состоянию периода.

Определено в:: getUnits в интерфейсе TemporalAmount
Возвращает:: список поддерживаемых интервалов, не null

getChronology

Chronology getChronology()

Получает хронологию, определяющую смысл поддерживаемых интервалов.

Период определяется хронологией. Она управляет поддерживаемыми интервалами и ограничивает сложение/вычитание ChronoLocalDate экземплярами той же хронологии.

Возвращает:: хронологию, определяющую период, не null

isZero

default boolean isZero()

Проверяет, равны ли все поддерживаемые интервалы этого периода нулю.

Возвращает:: true, если длина периода равна нулю

isNegative

default boolean isNegative()

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

Возвращает:: true, если любой интервал в этом периоде отрицательный

plus

ChronoPeriod plus(TemporalAmount amountToAdd)

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

Если заданный период — ChronoPeriod, то он должен иметь ту же хронологию, что и этот период. Реализации могут выбрать принять или отклонить другие TemporalAmount реализации.

Этот экземпляр неизменяем и не изменяется этим вызовом метода.

Параметры:: amountToAdd - добавляемый период, не null
Возвращает:: новый ChronoPeriod, основанный на этом периоде с добавленным периодом, не null
Исключения:: ArithmeticException - если произошел переполнение

minus

ChronoPeriod minus(TemporalAmount amountToSubtract)

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

Этот экземпляр неизменяем и не изменяется этим вызовом метода.

Параметры:: amountToSubtract - вычитаемый период, не null
Возвращает:: новый ChronoPeriod, основанный на этом периоде с вычтенным периодом, не null
Исключения:: ArithmeticException - если произошел переполнение

multipliedBy

ChronoPeriod multipliedBy(int scalar)

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

Возвращает период, в котором каждый поддерживаемый интервал индивидуально умножается. Например, период "2 года, -3 месяца и 4 дня" умноженный на 3 вернёт "6 лет, -9 месяцев и 12 дней". Нормализация не выполняется.

Параметры:: scalar - скаляр для умножения, не null
Возвращает:: новый ChronoPeriod, основанный на этом периоде с умноженными значениями интервалов, не null
Исключения:: ArithmeticException - если произошел переполнение

negated

default ChronoPeriod negated()

Возвращает новый экземпляр, в котором каждое значение интервала этого периода изменено на противоположный знак.

Возвращает период, в котором каждый поддерживаемый интервал индивидуально меняет знак. Например, период "2 года, -3 месяца и 4 дня" будет изменён на "-2 года, 3 месяца и -4 дня". Нормализация не выполняется.

Возвращает:: новый ChronoPeriod, основанный на этом периоде с изменёнными знаками интервалов, не null
Исключения:: ArithmeticException - если произошло переполнение, что возможно только если у одного из интервалов значение Long.MIN_VALUE

normalized

ChronoPeriod normalized()

Возвращает копию этого периода с нормализованными значениями каждого интервала.

Процесс нормализации специфичен для каждой системы календаря. Например, в системе календаря ISO годы и месяцы нормализуются, но дни нет, так что "15 месяцев" будет нормализовано до "1 года и 3 месяцев".

Этот экземпляр неизменяем и не изменяется этим вызовом метода.

Возвращает:: новый ChronoPeriod, основанный на этом периоде с нормализованными значениями интервалов, не null
Исключения:: ArithmeticException - если произошел переполнение

addTo

Temporal addTo(Temporal temporal)

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

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

В большинстве случаев, яснее использовать обратный порядок вызова, используя Temporal.plus(TemporalAmount).

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

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

Этот экземпляр неизменяем и не изменяется этим вызовом метода.

Определено в:: addTo в интерфейсе TemporalAmount
Параметры:: 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 = thisPeriod.subtractFrom(dateTime);
   dateTime = dateTime.minus(thisPeriod);

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

Этот экземпляр неизменяем и не изменяется этим вызовом метода.

Определено в:: subtractFrom в интерфейсе TemporalAmount
Параметры:: temporal - временной объект для корректировки, не null
Возвращает:: объект того же типа с произведённой корректировкой, не null
Исключения:: DateTimeException - если вычитание невозможно; ArithmeticException - если произошел переполнение

equals

boolean equals(Object obj)

Проверяет, равен ли этот период другому периоду, включая хронологию.

Сравнивает этот период с другим, гарантируя, что тип, каждое количество и хронология совпадают. Обратите внимание, что это означает, что период "15 месяцев" не равен периоду "1 год и 3 месяца".

Overrides:

equals в классе Object

Parameters:

obj - объект для проверки, null возвращает false

Returns:

true, если этот период равен другому

See Also:

hashCode

int hashCode()

Хеш-код для этого периода.

Overrides:

hashCode в классе Object

Returns:

подходящий хеш-код

See Also:

toString

String toString()

Выводит этот период как String.

Вывод будет включать количества периодов и хронологию.

Overrides:: toString в классе Object
Returns:: строковое представление этого периода, не null

© 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/chrono/ChronoPeriod.html