Класс 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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создает и возвращает копию этого объекта.
`protected void`	`finalize()`	Устарело и подлежит удалению: этот элемент API может быть удален в будущей версии. Финализация объявлена устаревшей и подлежит удалению в будущем выпуске.
`final Class<?>`	`getClass()`	Возвращает класс среды выполнения этого `Object`.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо истечения заданного интервала реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо истечения заданного интервала реального времени.

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

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)

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

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

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

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

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

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

minusYears

public Period minusYears(long yearsToSubtract)

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

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

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

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

minusMonths

public Period minusMonths(long monthsToSubtract)

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

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

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

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

minusDays

public Period minusDays(long daysToSubtract)

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

Вычитает указанное количество из единицы дней в копии этого периода. Единицы лет и месяцев не изменяются. Например, при вычитании 2 дней из «1 года, 6 месяцев и 3 дней» получается «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.