Интерфейс 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

См. также:

ChronoLocalDate.until(ChronoLocalDate)

get

long get(TemporalUnit unit)

Возвращает значение запрошенного единицы измерения.

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

Определено в:: get в интерфейсе TemporalAmount
Параметры:: unit - TemporalUnit, значение которого нужно вернуть
Возвращает:: значение единицы измерения типа long
Исключения:: 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 месяца".

Переопределяет:

equals в классе Object

Параметры:

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

Возвращает:

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

См. также:

hashCode

int hashCode()

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

Overrides:

hashCode в классе Object

Возвращает:

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

См. также:

toString

String toString()

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

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

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

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