Интерфейс 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 - единица измерения, для которой необходимо получить значение
Возвращает:: значение 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
Возвращает:: период, основанный на этом периоде с добавленным указанным периодом, не null
Исключения:: ArithmeticException - если происходит переполнение

minus

ChronoPeriod minus(TemporalAmount amountToSubtract)

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

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

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

multipliedBy

ChronoPeriod multipliedBy(int scalar)

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

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

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

negated

default ChronoPeriod negated()

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

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

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

normalized

ChronoPeriod normalized()

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

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

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

Возвращает:: период, основанный на этом периоде с интервалами каждой единицы измерения нормализованными, не 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, если этот период равен другому периоду
См. также:: Object.hashCode(), HashMap

hashCode

int hashCode()

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

Переопределяет:: hashCode в классе Object
Возвращает:: подходящий хеш-код
См. также:: Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

toString

String toString()

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

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

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

© 1993, 2020, 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/11/docs/api/java.base/java/time/chrono/ChronoPeriod.html