Интерфейс 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). Таким образом, вычисление зависит от хронологии.

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

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

Parameters:

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

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

Returns:

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

See Also:

get

long get(TemporalUnit unit)

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

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

Specified by:: get в интерфейсе TemporalAmount
Parameters:: unit - временной интервал, для которого нужно вернуть значение
Returns:: значение типа long для заданного интервала
Throws:: DateTimeException - если интервал не поддерживается; UnsupportedTemporalTypeException - если интервал не поддерживается

getUnits

List<TemporalUnit> getUnits()

Возвращает набор поддерживаемых единиц измерения данного периода.

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

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

Specified by:: getUnits в интерфейсе TemporalAmount
Returns:: список поддерживаемых единиц измерения, не null

getChronology

Chronology getChronology()

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

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

Returns:: хронология, определяющая период, не null

isZero

default boolean isZero()

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

Returns:: true, если период имеет длину ноль

isNegative

default boolean isNegative()

Проверяет, отрицательны ли какие-либо поддерживаемые единицы измерения этого периода.

Returns:: true, если какая-либо единица измерения периода отрицательна

plus

ChronoPeriod plus(TemporalAmount amountToAdd)

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

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

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

Parameters:: amountToAdd - период для добавления, не null
Returns:: новый период, основанный на этом периоде с добавленным запрошенным периодом, не null
Throws:: ArithmeticException - если произошел переполнение при арифметических вычислениях

minus

ChronoPeriod minus(TemporalAmount amountToSubtract)

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

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

Parameters:: amountToSubtract - период для вычитания, не null
Returns:: новый период, основанный на этом периоде с вычтенным запрошенным периодом, не null
Throws:: ArithmeticException - если произошел переполнение при арифметических вычислениях

multipliedBy

ChronoPeriod multipliedBy(int scalar)

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

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

Parameters:: scalar - скаляр для умножения, не null
Returns:: новый период, основанный на этом периоде с умноженными значениями, не null
Throws:: ArithmeticException - если произошел переполнение при арифметических вычислениях

negated

default ChronoPeriod negated()

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

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

Returns:: новый период, основанный на этом периоде с измененными знаками, не null
Throws:: ArithmeticException - если произошел переполнение при арифметических вычислениях, что случается только если у одной из единиц измерения значение Long.MIN_VALUE

normalized

ChronoPeriod normalized()

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

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

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

Returns:: копию периода с приведенными к нормальному виду величинами, не null
Throws:: 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);

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

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

Specified by:: addTo в интерфейсе TemporalAmount
Parameters:: temporal - объект временной метки для корректировки, не null
Returns:: объект того же типа с произведённой корректировкой, не null
Throws:: 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);

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

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

Specified by:: subtractFrom в интерфейсе TemporalAmount
Parameters:: temporal - объект временной метки для корректировки, не null
Returns:: объект того же типа с произведённой корректировкой, не null
Throws:: 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

Возвращает:

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

См. также:

toString

String toString()

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

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

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

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