Класс Period

java.lang.Object

java.time.Period

Все реализуемые интерфейсы:: Serializable, ChronoPeriod, TemporalAmount

public final class Period extends Object implements ChronoPeriod, Serializable

Величина времени, выраженная в датах календарной системы ISO-8601, например «2 года, 3 месяца и 4 дня».

Этот класс моделирует количество времени в годах, месяцах и днях. Эквивалент этого класса, выраженный во временных единицах, см. в Duration.

При прибавлении к ZonedDateTime длительности и периоды по-разному учитывают переход на летнее время. Duration добавляет точное количество секунд, поэтому длительность в один день всегда составляет ровно 24 часа. Напротив, Period добавляет условный день, стараясь сохранить местное время.

Например, рассмотрим прибавление периода в один день и длительности в один день к моменту 18:00 вечером перед переходом на летнее время. Period добавит условный день, и в результате получится ZonedDateTime в 18:00 следующего дня. Напротив, Duration добавит ровно 24 часа, в результате получится ZonedDateTime в 19:00 следующего дня (при условии, что переход на летнее время составляет один час).

Поддерживаемые единицы периода: YEARS, MONTHS и DAYS. Все три поля всегда присутствуют, но могут иметь нулевое значение.

Календарная система ISO-8601 — это современная гражданская календарная система, используемая сегодня в большей части мира. Она эквивалентна пролептической григорианской календарной системе, в которой современные правила високосных лет применяются ко всему временному диапазону.

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

Это класс на основе значений; программистам следует считать экземпляры, которые равны, взаимозаменяемыми и не использовать экземпляры для синхронизации, иначе может возникнуть непредсказуемое поведение. Например, в одном из будущих выпусков синхронизация может завершиться сбоем. Для сравнения следует использовать метод equals.

Требования к реализации:

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

С версии:

1.8

См. также:

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final Period`	`ZERO`	Константа, обозначающая нулевой период.

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

Модификатор и тип	Метод	Описание
`Temporal`	`addTo(Temporal temporal)`	Прибавляет этот период к указанному временному объекту.
`static Period`	`between(LocalDate startDateInclusive, LocalDate endDateExclusive)`	Получает `Period`, содержащий количество лет, месяцев и дней между двумя датами.
`boolean`	`equals(Object obj)`	Проверяет, равен ли этот период другому периоду.
`static Period`	`from(TemporalAmount amount)`	Получает экземпляр `Period` из временной величины.
`long`	`get(TemporalUnit unit)`	Получает значение запрошенной единицы измерения.
`IsoChronology`	`getChronology()`	Получает хронологию этого периода — календарную систему ISO.
`int`	`getDays()`	Получает количество дней в этом периоде.
`int`	`getMonths()`	Получает количество месяцев в этом периоде.
`List<TemporalUnit>`	`getUnits()`	Получает набор единиц измерения, поддерживаемых этим периодом.
`int`	`getYears()`	Получает количество лет в этом периоде.
`int`	`hashCode()`	Хеш-код этого периода.
`boolean`	`isNegative()`	Проверяет, является ли отрицательной хотя бы одна из трех единиц этого периода.
`boolean`	`isZero()`	Проверяет, равны ли нулю все три единицы этого периода.
`Period`	`minus(TemporalAmount amountToSubtract)`	Возвращает копию этого периода, из которого вычтен указанный период.
`Period`	`minusDays(long daysToSubtract)`	Возвращает копию этого периода, из которого вычтено указанное количество дней.
`Period`	`minusMonths(long monthsToSubtract)`	Возвращает копию этого периода, из которого вычтено указанное количество месяцев.
`Period`	`minusYears(long yearsToSubtract)`	Возвращает копию этого периода, из которого вычтено указанное количество лет.
`Period`	`multipliedBy(int scalar)`	Возвращает новый экземпляр, в котором каждый компонент этого периода умножен на указанный скаляр.
`Period`	`negated()`	Возвращает новый экземпляр, в котором каждая величина этого периода имеет противоположный знак.
`Period`	`normalized()`	Возвращает копию этого периода с нормализованными годами и месяцами.
`static Period`	`of(int years, int months, int days)`	Получает `Period`, представляющий количество лет, месяцев и дней.
`static Period`	`ofDays(int days)`	Получает `Period`, представляющий количество дней.
`static Period`	`ofMonths(int months)`	Получает `Period`, представляющий количество месяцев.
`static Period`	`ofWeeks(int weeks)`	Получает `Period`, представляющий количество недель.
`static Period`	`ofYears(int years)`	Получает `Period`, представляющий количество лет.
`static Period`	`parse(CharSequence text)`	Получает `Period` из текстовой строки, например `PnYnMnD`.
`Period`	`plus(TemporalAmount amountToAdd)`	Возвращает копию этого периода, к которому прибавлен указанный период.
`Period`	`plusDays(long daysToAdd)`	Возвращает копию этого периода, к которому прибавлено указанное количество дней.
`Period`	`plusMonths(long monthsToAdd)`	Возвращает копию этого периода, к которому прибавлено указанное количество месяцев.
`Period`	`plusYears(long yearsToAdd)`	Возвращает копию этого периода, к которому прибавлено указанное количество лет.
`Temporal`	`subtractFrom(Temporal temporal)`	Вычитает этот период из указанного временного объекта.
`String`	`toString()`	Выводит этот период в виде `String`, например `P6Y3M1D`.
`long`	`toTotalMonths()`	Получает общее количество месяцев в этом периоде.
`Period`	`withDays(int days)`	Возвращает копию этого периода с указанным количеством дней.
`Period`	`withMonths(int months)`	Возвращает копию этого периода с указанным количеством месяцев.
`Period`	`withYears(int years)`	Возвращает копию этого периода с указанным количеством лет.

Методы, объявленные в классе Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Подробное описание полей

ZERO

public static final Period ZERO

Константа для периода, равного нулю.

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

ofYears

public static Period ofYears(int years)

Создает Period, представляющий количество лет.

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

Параметры:: years — количество лет, положительное или отрицательное
Возвращает:: период в годах, не null

ofMonths

public static Period ofMonths(int months)

Создает Period, представляющий количество месяцев.

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

Параметры:: months — количество месяцев, положительное или отрицательное
Возвращает:: период в месяцах, не null

ofWeeks

public static Period ofWeeks(int weeks)

Создает Period, представляющий количество недель.

Полученный период будет выражен в днях: количество дней равно количеству недель, умноженному на 7. Единицы лет и месяцев будут равны нулю.

Параметры:: weeks — количество недель, положительное или отрицательное
Возвращает:: период, в котором указанное количество недель преобразовано в дни, не null

ofDays

public static Period ofDays(int days)

Создает Period, представляющий количество дней.

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

Параметры:: days — количество дней, положительное или отрицательное
Возвращает:: период в днях, не null

of

public static Period of(int years, int months, int days)

Создает Period, представляющий количество лет, месяцев и дней.

Создает экземпляр на основе значений лет, месяцев и дней.

Параметры:: years — количество лет, может быть отрицательным; months — количество месяцев, может быть отрицательным; days — количество дней, может быть отрицательным
Возвращает:: период в годах, месяцах и днях, не null

from

public static Period from(TemporalAmount amount)

Создает экземпляр Period из временной величины.

Создает период на основе указанной величины. TemporalAmount представляет величину времени, которая может быть основана на дате или времени; эта фабрика извлекает из нее Period.

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

Если величина является ChronoPeriod, она должна использовать хронологию ISO.

Параметры:: amount — преобразуемая временная величина, не null
Возвращает:: эквивалентный период, не null
Выбрасывает:: DateTimeException — если не удается преобразовать в Period; ArithmeticException — если количество лет, месяцев или дней превышает значение типа int

parse

public static Period parse(CharSequence text)

Создает Period из текстовой строки, например PnYnMnD.

Метод разбирает строку, созданную методом toString(), которая соответствует форматам периода ISO-8601 PnYnMnD и PnW.

Строка начинается с необязательного знака — символа ASCII «минус» или «плюс». Если знак отрицательный, весь период считается отрицательным. Далее следует буква ASCII «P» в верхнем или нижнем регистре. Затем идут четыре секции, каждая из которых состоит из числа и суффикса. Должна присутствовать хотя бы одна из четырех секций. Суффиксы секций — символы ASCII «Y», «M», «W» и «D», обозначающие годы, месяцы, недели и дни; допускается верхний или нижний регистр. Суффиксы должны располагаться в указанном порядке. Числовая часть каждой секции должна состоять из цифр ASCII. Перед числом может стоять символ ASCII «минус» или «плюс». Число должно быть преобразуемо в int.

Начальный знак «плюс» или «минус», а также отрицательные значения для других единиц не входят в стандарт ISO-8601. Кроме того, ISO-8601 не допускает смешивания форматов PnYnMnD и PnW. Любое значение в неделях умножается на 7 и рассматривается как количество дней.

Например, допустимы следующие значения:

  "P2Y"             -- Period.ofYears(2)
  "P3M"             -- Period.ofMonths(3)
  "P4W"             -- Period.ofWeeks(4)
  "P5D"             -- Period.ofDays(5)
  "P1Y2M3D"         -- Period.of(1, 2, 3)
  "P1Y2M3W4D"       -- Period.of(1, 2, 25)
  "P-1Y2M"          -- Period.of(-1, 2, 0)
  "-P1Y2M"          -- Period.of(-1, -2, 0)

Параметры:: text — разбираемый текст, не null
Возвращает:: разобранный период, не null
Выбрасывает:: DateTimeParseException — если текст не удается разобрать как период

between

public static Period between(LocalDate startDateInclusive, LocalDate endDateExclusive)

Создает Period, состоящий из количества лет, месяцев и дней между двумя датами.

Начальная дата включается, а конечная — нет. Период вычисляется путем удаления полных месяцев, а затем подсчета оставшихся дней с корректировкой, чтобы оба значения имели одинаковый знак. Затем количество месяцев разделяется на годы и месяцы исходя из того, что в году 12 месяцев. Месяц учитывается, если день месяца конечной даты больше или равен дню месяца начальной даты. Например, период от 2010-01-15 до 2011-03-18 составляет один год, два месяца и три дня.

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

Параметры:

startDateInclusive — начальная дата, включительно, не null

endDateExclusive — конечная дата, не включительно, не null

Возвращает:

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

См. также:

get

public long get(TemporalUnit unit)

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

Возвращает значение для каждой из трех поддерживаемых единиц: YEARS, MONTHS и DAYS. Для всех остальных единиц выбрасывается исключение.

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

getUnits

public List<TemporalUnit> getUnits()

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

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

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

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

getChronology

public IsoChronology getChronology()

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

Chronology представляет используемую календарную систему. Календарная система ISO-8601 — это современная гражданская календарная система, используемая сегодня в большинстве стран мира. Она эквивалентна пролептическому григорианскому календарю, в котором действующие сегодня правила високосных лет применяются ко всему временному периоду.

Определено в:: getChronology в интерфейсе ChronoPeriod
Возвращает:: хронология ISO, не null

isZero

public boolean isZero()

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

Нулевой период имеет нулевые значения для единиц лет, месяцев и дней.

Определено в:: isZero в интерфейсе ChronoPeriod
Возвращает:: true, если длина этого периода равна нулю

isNegative

public boolean isNegative()

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

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

Определено в:: isNegative в интерфейсе ChronoPeriod
Возвращает:: true, если хотя бы одна единица периода отрицательна

getYears

public int getYears()

Возвращает количество лет в этом периоде.

Возвращает значение единицы лет.

Значение единицы месяцев автоматически не нормализуется относительно единицы лет. Это означает, что период «15 месяцев» отличается от периода «1 год и 3 месяца».

Возвращает:: количество лет в этом периоде, может быть отрицательным

getMonths

public int getMonths()

Возвращает количество месяцев в этом периоде.

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

Возвращает:: количество месяцев в этом периоде, может быть отрицательным

getDays

public int getDays()

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

Возвращает значение единицы дней.

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

withYears

public Period withYears(int years)

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

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

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

Параметры:: years — представляемое количество лет, может быть отрицательным
Возвращает:: Period на основе этого периода с указанным количеством лет, не null

withMonths

public Period withMonths(int months)

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

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

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

Параметры:: months — представляемое количество месяцев, может быть отрицательным
Возвращает:: Period на основе этого периода с указанным количеством месяцев, не null

withDays

public Period withDays(int days)

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

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

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

Параметры:: days — представляемое количество дней, может быть отрицательным
Возвращает:: Period на основе этого периода с указанным количеством дней, не null

plus

public Period plus(TemporalAmount amountToAdd)

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

Операция выполняется отдельно для лет, месяцев и дней. Нормализация не производится.

Например, к периоду «1 год, 6 месяцев и 3 дня» прибавление периода «2 года, 2 месяца и 2 дня» дает «3 года, 8 месяцев и 5 дней».

Указанная величина обычно является экземпляром Period. Другие типы интерпретируются с помощью from(TemporalAmount).

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

Определено в:: plus в интерфейсе ChronoPeriod
Параметры:: amountToAdd — прибавляемая величина, не null
Возвращает:: Period на основе этого периода с прибавленным указанным периодом, не null
Выбрасывает:: DateTimeException — если указанная величина имеет хронологию, отличную от ISO, или содержит недопустимую единицу; ArithmeticException — при числовом переполнении

plusYears

public Period plusYears(long yearsToAdd)

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

Прибавляет указанное значение к единице лет в копии этого периода. Значения единиц месяцев и дней не изменяются. Например, к периоду «1 год, 6 месяцев и 3 дня» прибавление 2 лет дает «3 года, 6 месяцев и 3 дня».

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

Параметры:: yearsToAdd — количество лет для прибавления, положительное или отрицательное
Возвращает:: Period на основе этого периода с прибавленным указанным количеством лет, не null
Выбрасывает:: ArithmeticException — при числовом переполнении

plusMonths

public Period plusMonths(long monthsToAdd)

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

Прибавляет указанное значение к единице месяцев в копии этого периода. Значения единиц лет и дней не изменяются. Например, к периоду «1 год, 6 месяцев и 3 дня» прибавление 2 месяцев дает «1 год, 8 месяцев и 3 дня».

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

Параметры:: monthsToAdd — количество месяцев для прибавления, положительное или отрицательное
Возвращает:: Period на основе этого периода с прибавленным указанным количеством месяцев, не null
Выбрасывает:: ArithmeticException — при числовом переполнении

plusDays

public Period plusDays(long daysToAdd)

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

Прибавляет указанное значение к единице дней в копии этого периода. Значения единиц лет и месяцев не изменяются. Например, к периоду «1 год, 6 месяцев и 3 дня» прибавление 2 дней дает «1 год, 6 месяцев и 5 дней».

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

Параметры:: daysToAdd — количество дней для прибавления, положительное или отрицательное
Возвращает:: Period на основе этого периода с прибавленным указанным количеством дней, не null
Выбрасывает:: ArithmeticException — при числовом переполнении

minus

public Period minus(TemporalAmount amountToSubtract)

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

Операция выполняется отдельно для лет, месяцев и дней. Нормализация не производится.

Например, из периода «1 год, 6 месяцев и 3 дня» вычитание периода «2 года, 2 месяца и 2 дня» дает «-1 год, 4 месяца и 1 день».

Указанная величина обычно является экземпляром Period. Другие типы интерпретируются с помощью from(TemporalAmount).

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

Определено в:: minus в интерфейсе ChronoPeriod
Параметры:: amountToSubtract — вычитаемая величина, не null
Возвращает:: Period на основе этого периода с вычтенным указанным периодом, не null
Выбрасывает:: DateTimeException — если указанная величина имеет хронологию, отличную от ISO, или содержит недопустимую единицу; ArithmeticException — при числовом переполнении

minusYears

public Period minusYears(long yearsToSubtract)

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

Вычитает указанное значение из единицы лет в копии этого периода. Значения единиц месяцев и дней не изменяются. Например, из периода «1 год, 6 месяцев и 3 дня» вычитание 2 лет дает «-1 год, 6 месяцев и 3 дня».

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

Параметры:: yearsToSubtract — количество лет для вычитания, положительное или отрицательное
Возвращает:: Period на основе этого периода с вычтенным указанным количеством лет, не null
Выбрасывает:: ArithmeticException — при числовом переполнении

minusMonths

public Period minusMonths(long monthsToSubtract)

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

Вычитает указанное значение из единицы месяцев в копии этого периода. Значения единиц лет и дней не изменяются. Например, из периода «1 год, 6 месяцев и 3 дня» вычитание 2 месяцев дает «1 год, 4 месяца и 3 дня».

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

Параметры:: monthsToSubtract — количество лет для вычитания, положительное или отрицательное
Возвращает:: Period на основе этого периода с вычтенным указанным количеством месяцев, не null
Выбрасывает:: ArithmeticException — при числовом переполнении

minusDays

public Period minusDays(long daysToSubtract)

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

Вычитает указанное значение из единицы дней в копии этого периода. Значения единиц лет и месяцев не изменяются. Например, из периода «1 год, 6 месяцев и 3 дня» вычитание 2 дней дает «1 год, 6 месяцев и 1 день».

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

Параметры:: daysToSubtract — количество месяцев для вычитания, положительное или отрицательное
Возвращает:: Period на основе этого периода с вычтенным указанным количеством дней, не null
Выбрасывает:: ArithmeticException — при числовом переполнении

multipliedBy

public Period multipliedBy(int scalar)

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

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

Определено в:: multipliedBy в интерфейсе ChronoPeriod
Параметры:: scalar — скалярный множитель, не null
Возвращает:: Period на основе этого периода, значения которого умножены на скаляр, не null
Выбрасывает:: ArithmeticException — при числовом переполнении

negated

public Period negated()

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

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

Определено в:: negated в интерфейсе ChronoPeriod
Возвращает:: Period на основе этого периода, значения которого имеют противоположный знак, не null
Выбрасывает:: ArithmeticException — при числовом переполнении, которое возможно только в том случае, если значение одной из единиц равно Integer.MIN_VALUE

normalized

public Period normalized()

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

Нормализует единицы лет и месяцев, оставляя единицу дней без изменений. Значение единицы месяцев корректируется так, чтобы его абсолютное значение было меньше 12, а значение единицы лет соответственно изменялось. Например, период «1 год и 15 месяцев» будет нормализован до «2 лет и 3 месяцев».

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

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

Определено в:: normalized в интерфейсе ChronoPeriod
Возвращает:: Period на основе этого периода, в котором лишние месяцы преобразованы в годы, не null
Выбрасывает:: ArithmeticException — при числовом переполнении

toTotalMonths

public long toTotalMonths()

Возвращает общее количество месяцев в этом периоде.

Возвращает общее количество месяцев в периоде: количество лет умножается на 12, затем прибавляется количество месяцев.

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

Возвращает:: общее количество месяцев в периоде, может быть отрицательным

addTo

public Temporal addTo(Temporal temporal)

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

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

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

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

Вычисление выполняется следующим образом. Сначала проверяется, что хронология временного объекта — ISO или null. Затем, если количество месяцев равно нулю, прибавляются ненулевые значения лет; в противном случае, если сумма лет и месяцев ненулевая, прибавляется их совокупное значение. В конце прибавляются дни, если они есть.

Такой подход позволяет прибавить неполный период к неполной дате. Например, период, состоящий из лет и/или месяцев, можно прибавить к YearMonth, но период, включающий дни, прибавить нельзя. Кроме того, при необходимости годы и месяцы прибавляются вместе, что обеспечивает правильную обработку конца месяца.

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

Определено в:: addTo в интерфейсе ChronoPeriod
Определено в:: addTo в интерфейсе TemporalAmount
Параметры:: temporal — временной объект для корректировки, не null
Возвращает:: объект того же типа с выполненной корректировкой, не null
Выбрасывает:: DateTimeException — если выполнить прибавление не удалось; ArithmeticException — при числовом переполнении

subtractFrom

public Temporal subtractFrom(Temporal temporal)

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

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

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

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

Вычисление выполняется следующим образом. Сначала проверяется, что хронология временного объекта — ISO или null. Затем, если количество месяцев равно нулю, вычитаются ненулевые значения лет; в противном случае, если сумма лет и месяцев ненулевая, вычитается их совокупное значение. В конце вычитаются дни, если они есть.

Такой подход позволяет вычесть неполный период из неполной даты. Например, период, состоящий из лет и/или месяцев, можно вычесть из YearMonth, но период, включающий дни, вычесть нельзя. Кроме того, при необходимости годы и месяцы вычитаются вместе, что обеспечивает правильную обработку конца месяца.

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

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

equals

public boolean equals(Object obj)

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

Сравнение выполняется по типу Period и каждому из трех значений. Для равенства значения единиц лет, месяцев и дней должны совпадать по отдельности. Обратите внимание: это означает, что период «15 месяцев» не равен периоду «1 год и 3 месяца».

Определено в:

equals в интерфейсе ChronoPeriod

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

equals в классе Object

Параметры:

obj — проверяемый объект; для null возвращается false

Возвращает:

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

См. также:

hashCode

public int hashCode()

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

Определено в:

hashCode в интерфейсе ChronoPeriod

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

hashCode в классе Object

Возвращает:

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

См. также:

toString

public String toString()

Выводит этот период в виде String, например P6Y3M1D.

Результат будет представлен в формате периода ISO-8601. Нулевой период будет представлен как ноль дней — 'P0D'.

Указано в:: toString в интерфейсе ChronoPeriod
Переопределяет:: 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/Period.html