Интерфейс ChronoPeriod

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

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

public interface ChronoPeriod extends TemporalAmount

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

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

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

Требования к реализации:: Этот интерфейс необходимо реализовывать с осторожностью, чтобы обеспечить корректную работу других классов. Все реализации, экземпляры которых можно создавать, должны быть final, неизменяемыми и потокобезопасными. По возможности подклассы должны реализовывать Serializable.
Начиная с версии:: 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)

Получает ChronoPeriod, представляющий промежуток времени между двумя датами.

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

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

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

Параметры:

startDateInclusive — начальная дата, включительно; задаёт хронологию вычисления, не должна быть null

endDateExclusive — конечная дата, исключительно, в любой хронологии, не должна быть null

Возвращает:

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

См. также:

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()

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

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

hashCode в классе Object

Возвращает:

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

См. также:

toString

String toString()

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

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

Переопределяет:: toString в классе Object
Возвращает:: строковое представление этого периода, не 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://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/time/chrono/ChronoPeriod.html