Интерфейс ChronoLocalDate

Все суперинтерфейсы:: Comparable<ChronoLocalDate>, Temporal, TemporalAccessor, TemporalAdjuster

Все известные реализующие классы:: HijrahDate, JapaneseDate, LocalDate, MinguoDate, ThaiBuddhistDate

public interface ChronoLocalDate
extends Temporal, TemporalAdjuster, Comparable<ChronoLocalDate>

Дата без времени суток или часового пояса в произвольном хронологическом порядке, предназначенная для использования в передовых сценариях глобализации.

Большинство приложений должны объявлять сигнатуры методов, поля и переменные как LocalDate, а не этот интерфейс.

Объект ChronoLocalDate является абстрактным представлением даты, где Chronology chronology, или система календаря, является подключаемым модулем. Дата определяется в терминах полей, выраженных с помощью TemporalField, где большинство распространённых реализаций определены в ChronoField. Хронология определяет, как работает система календаря и значение стандартных полей.

Когда использовать этот интерфейс

Дизайн API рекомендует использование LocalDate вместо этого интерфейса, даже в случае, когда приложение должно работать с несколькими системами календаря.

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

Архитектурные вопросы для рассмотрения

Это некоторые из моментов, которые необходимо учитывать перед использованием этого интерфейса во всем приложении.

1) Приложения, использующие этот интерфейс, в отличие от использования только LocalDate, сталкиваются с значительно большей вероятностью ошибок. Это связано с тем, что система календаря, используемая в работе, неизвестна на этапе разработки. Основной причиной ошибок является то, что разработчик применяет предположения, основанные на повседневном использовании системы календаря ISO, к коду, предназначенному для работы с любой произвольной системой календаря. В следующем разделе описывается, как эти предположения могут создавать проблемы. Основной механизм снижения этого повышенного риска ошибок — это строгий процесс контроля кода. Это также следует учитывать как дополнительные затраты на обслуживание в течение всего срока службы кода.

2) Этот интерфейс не гарантирует неизменяемость реализаций. Хотя в примечаниях к реализации указано, что все реализации должны быть неизменяемыми, в коде или системе типов нет ничего, что обеспечивало бы это. Любой метод, объявленный для принятия ChronoLocalDate, может, следовательно, получить плохо или злонамеренно написанную изменяемую реализацию.

3) Приложения, использующие этот интерфейс, должны учитывать влияние эр. LocalDate защищает пользователей от концепции эр, гарантируя, что getYear() возвращает пролептический год. Это решение гарантирует, что разработчики могут рассматривать экземпляры LocalDate как состоящие из трех полей — года, месяца и дня. В противоположность этому, пользователи этого интерфейса должны рассматривать даты как состоящие из четырех полей — эры, года эры, месяца и дня. Дополнительное поле эры часто забывают, но оно имеет решающее значение для дат в произвольной системе календаря. Например, в японской системе календаря эра представляет собой правление императора. Всякий раз, когда одно правление заканчивается, а другое начинается, год эры сбрасывается до одного.

4) Единственным согласованным международным стандартом передачи даты между двумя системами является стандарт ISO-8601, который требует использования системы календаря ISO. Использование этого интерфейса во всем приложении неизбежно потребует передачи даты через сетевую границу или границу компонента, что потребует применения специального протокола или формата приложения.

5) Длительное хранение данных, например, в базе данных, почти всегда будет принимать даты только в системе календаря ISO-8601 (или связанной системе юлианско-григорианского календаря). Передача дат в других системах календаря увеличивает сложность взаимодействия с хранилищем данных.

6) В большинстве случаев передача ChronoLocalDate через приложение не требуется, как обсуждалось в последнем разделе ниже.

Ложные предположения, приводящие к ошибкам в коде с несколькими системами календаря

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

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

Код, добавляющий 12 месяцев к дате и предполагающий, что добавляется год, некорректен. В некоторых системах календаря разное количество месяцев, например, 13 в коптском или эфиопском календарях.

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

Код, добавляющий один месяц, затем добавляющий второй месяц и предполагающий, что день месяца останется около исходного значения, некорректен. В некоторых системах календаря большая разница между длительностью самого длинного и самого короткого месяца. Например, в коптском или эфиопском календарях 12 месяцев по 30 дней и 1 месяц по 5 дней.

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

Код, предполагающий, что потому что год date1 больше года date2 , то date1 следует после date2, некорректен. Это неверно для всех систем календаря применительно к году эры, и особенно неверно для японской системы календаря, где год эры перезапускается с правлением каждого нового императора.

Код, рассматривающий месяц один и день один как начало года, некорректен. Не все системы календаря начинают год со значением месяца один.

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

Использование LocalDate вместо этого

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

Определите все сигнатуры методов, относящихся к датам, в терминах LocalDate.
Храните хронологию (систему календаря) в профиле пользователя или получайте хронологию из региональных настроек пользователя.
Преобразуйте ISO LocalDate в предпочтительную систему календаря пользователя и обратно при выводе и обработке входных данных.

Этот подход рассматривает проблему глобализированных систем календаря как проблему локализации и ограничивает её слоем пользовательского интерфейса. Этот подход соответствует другим проблемам локализации в платформе Java.

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

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

В любой другой части системы, где дата должна быть обработана в системе календаря, отличной от ISO, сценарий использования обычно указывает используемую систему календаря. Например, приложение может потребоваться для расчета ближайшего исламского или еврейского праздника, что может потребовать манипулирования датой. Этот тип сценария может быть обработан следующим образом:

начало с ISO LocalDate передаваемой в метод
преобразование даты в альтернативную систему календаря, которая в этом случае известна, а не произвольная
выполнение вычисления
возврат к LocalDate

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

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

Методы

Модификатор и тип	Метод	Описание
`default Temporal`	`adjustInto(Temporal temporal)`	Настраивает указанный временной объект так, чтобы у него была та же дата, что и у этого объекта.
`default ChronoLocalDateTime<?>`	`atTime(LocalTime localTime)`	Объединяет эту дату со временем для создания `ChronoLocalDateTime`.
`default int`	`compareTo(ChronoLocalDate other)`	Сравнивает эту дату с другой датой, включая хронологию.
`boolean`	`equals(Object obj)`	Проверяет, равна ли эта дата другой дате, включая хронологию.
`default String`	`format(DateTimeFormatter formatter)`	Форматирует эту дату с использованием указанного форматера.
`static ChronoLocalDate`	`from(TemporalAccessor temporal)`	Получает экземпляр `ChronoLocalDate` из временного объекта.
`Chronology`	`getChronology()`	Получает хронологию этой даты.
`default Era`	`getEra()`	Получает эру, как определено хронологией.
`int`	`hashCode()`	Хеш-код для этой даты.
`default boolean`	`isAfter(ChronoLocalDate other)`	Проверяет, следует ли эта дата после указанной даты, игнорируя хронологию.
`default boolean`	`isBefore(ChronoLocalDate other)`	Проверяет, предшествует ли эта дата указанной дате, игнорируя хронологию.
`default boolean`	`isEqual(ChronoLocalDate other)`	Проверяет, равна ли эта дата указанной дате, игнорируя хронологию.
`default boolean`	`isLeapYear()`	Проверяет, является ли год високосным, как определено календарной системой.
`default boolean`	`isSupported(TemporalField field)`	Проверяет, поддерживается ли указанное поле.
`default boolean`	`isSupported(TemporalUnit unit)`	Проверяет, поддерживается ли указанный период.
`int`	`lengthOfMonth()`	Возвращает длительность месяца, представленного этой датой, как определено календарной системой.
`default int`	`lengthOfYear()`	Возвращает длительность года, представленного этой датой, как определено календарной системой.
`default ChronoLocalDate`	`minus(long amountToSubtract, TemporalUnit unit)`	Возвращает объект того же типа, что и этот объект, с вычтенным указанным периодом.
`default ChronoLocalDate`	`minus(TemporalAmount amount)`	Возвращает объект того же типа, что и этот объект, с вычтенным значением.
`default ChronoLocalDate`	`plus(long amountToAdd, TemporalUnit unit)`	Возвращает объект того же типа, что и этот объект, с добавленным указанным периодом.
`default ChronoLocalDate`	`plus(TemporalAmount amount)`	Возвращает объект того же типа, что и этот объект, с добавленным значением.
`default <R> R`	`query(TemporalQuery<R> query)`	Запрашивает эту дату с использованием указанного запроса.
`static Comparator<ChronoLocalDate>`	`timeLineOrder()`	Получает компаратор, который сравнивает `ChronoLocalDate` в порядке временной шкалы, игнорируя хронологию.
`default long`	`toEpochDay()`	Преобразует эту дату в эпохальный день.
`String`	`toString()`	Выводит эту дату в виде `String`.
`ChronoPeriod`	`until(ChronoLocalDate endDateExclusive)`	Вычисляет период между этой датой и другой датой как `ChronoPeriod`.
`long`	`until(Temporal endExclusive, TemporalUnit unit)`	Вычисляет количество времени до другой даты в терминах указанного периода.
`default ChronoLocalDate`	`with(TemporalAdjuster adjuster)`	Возвращает измененный объект того же типа, что и этот объект, с произведённой корректировкой.
`default ChronoLocalDate`	`with(TemporalField field, long newValue)`	Возвращает объект того же типа, что и этот объект, с изменённым указанным полем.

Методы, объявленные в интерфейсе java.time.temporal.TemporalAccessor

get, getLong, range

Методы

timeLineOrder

static Comparator<ChronoLocalDate> timeLineOrder()

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

Этот компаратор отличается от сравнения в compareTo(java.time.chrono.ChronoLocalDate) тем, что сравнивает только базовую дату, а не хронологию. Это позволяет сравнивать даты в разных календарных системах на основе позиции даты на локальной временной линии. Базовое сравнение эквивалентно сравнению эпохальных дней.

Возвращает:: компаратор, сравнивающий в порядке временной линии, игнорируя хронологию
См. также:: isAfter(java.time.chrono.ChronoLocalDate), isBefore(java.time.chrono.ChronoLocalDate), isEqual(java.time.chrono.ChronoLocalDate)

from

static ChronoLocalDate from(TemporalAccessor temporal)

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

Это получает локальную дату на основе указанного временного объекта. TemporalAccessor представляет произвольный набор информации о дате и времени, которую этот фабричный метод преобразует в экземпляр ChronoLocalDate.

Преобразование извлекает и объединяет хронологию и дату из временного объекта. Поведение эквивалентно использованию Chronology.date(TemporalAccessor) с извлеченной хронологией. Реализации разрешено выполнять оптимизации, такие как доступ к тем полям, которые эквивалентны соответствующим объектам.

Этот метод соответствует сигнатуре функционального интерфейса TemporalQuery, позволяя использовать его в качестве запроса через ссылку на метод, ChronoLocalDate::from.

Параметры:: temporal - временной объект для преобразования, не null
Возвращает:: дата, не null
ИИсключения:: DateTimeException - если невозможно преобразовать в ChronoLocalDate
См. также:: Chronology.date(TemporalAccessor)

getChronology

Chronology getChronology()

Получает хронологию этой даты.

Chronology представляет используемую календарную систему. Эра и другие поля в ChronoField определяются хронологией.

Возвращает:: хронология, не null

getEra

default Era getEra()

Получает эру, как определено хронологией.

Эра, по сути, наибольшее деление временной линии. Большинство календарных систем имеет одну эпоху, делящую временную линию на две эры. Однако некоторые имеют несколько эр, например, по одной на царствование каждого лидера. Точное значение определяется Chronology.

Все правильно реализованные классы Era являются синглтонами, поэтому допустимо написать date.getEra() == SomeChrono.ERA_NAME).

Эта реализация по умолчанию использует Chronology.eraOf(int).

Возвращает:: константу эры, специфичную для хронологии, применимую к этой дате, не null

isLeapYear

default boolean isLeapYear()

Проверяет, является ли год високосным, как определено календарной системой.

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

Эта реализация по умолчанию использует Chronology.isLeapYear(long).

Возвращает:: true, если дата находится в високосном году, иначе false

lengthOfMonth

int lengthOfMonth()

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

Возвращает длительность месяца в днях.

Возвращает:: длительность месяца в днях

lengthOfYear

default int lengthOfYear()

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

Возвращает длительность года в днях.

Реализация по умолчанию использует isLeapYear() и возвращает 365 или 366.

Возвращает:: длительность года в днях

isSupported

default boolean isSupported(TemporalField field)

Проверяет, поддерживается ли указанное поле.

Проверяет, можно ли запросить указанное поле для этой даты. Если false, то вызов методов range, get и with(TemporalField, long) приведет к исключению.

Набор поддерживаемых полей определяется хронологией и обычно включает все поля дат.

Если поле не является ChronoField, то результат этого метода получается путем вызова TemporalField.isSupportedBy(TemporalAccessor) , передавая this в качестве аргумента. Поддерживается ли поле, определяется полем.

Задано в:: isSupported в интерфейсе TemporalAccessor
Параметры:: field - поле для проверки, null возвращает false
Возвращает:: true, если поле может быть запрошено, иначе false

isSupported

default boolean isSupported(TemporalUnit unit)

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

Проверяет, можно ли добавить или вычесть указанный интервал из этой даты. Если false, то вызов методов plus(long, TemporalUnit) и minus приведет к исключению.

Набор поддерживаемых интервалов определяется хронологией и обычно включает все интервалы дат, кроме FOREVER.

Если интервал не является ChronoUnit, то результат этого метода получается путем вызова TemporalUnit.isSupportedBy(Temporal) , передавая this в качестве аргумента. Поддерживается ли интервал, определяется интервалом.

Задано в:: isSupported в интерфейсе Temporal
Параметры:: unit - интервал для проверки, null возвращает false
Возвращает:: true, если интервал можно добавить/вычесть, иначе false

with

default ChronoLocalDate with(TemporalAdjuster adjuster)

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

Корректирует это время в соответствии с правилами указанного корректирующего элемента. Простой корректирующий элемент может просто установить одно из полей, например, поле года. Более сложный корректирующий элемент может установить дату на последнее число месяца. Выбор общих корректировок предоставляется в TemporalAdjusters. Они включают поиск «последнего числа месяца» и «следующей среды». Корректирующий элемент отвечает за обработку специальных случаев, таких как переменная длина месяца и високосные годы.

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

date = date.with(Month.JULY);        // most key classes implement TemporalAdjuster
  date = date.with(lastDayOfMonth());  // static import from Adjusters
  date = date.with(next(WEDNESDAY));   // static import from Adjusters and DayOfWeek

Задано в:: with в интерфейсе Temporal
Параметры:: adjuster - корректирующий элемент для использования, не null
Возвращает:: объект того же типа с произведенной корректировкой, не null
ИИсключения:: DateTimeException - если корректировка не может быть произведена; ArithmeticException - если произошел переполнение чисел

with

default ChronoLocalDate with(TemporalField field,
                             long newValue)

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

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

В некоторых случаях изменение поля не определено полностью. Например, если целевой объект представляет собой дату 31 января, то изменение месяца на февраль было бы неясным. В таких случаях поле отвечает за разрешение результата. Обычно оно выберет предыдущую допустимую дату, которая в данном примере будет последним допустимым числом февраля.

Задано в:: with в интерфейсе Temporal
Параметры:: field - поле для установки в результате, не null; newValue - новое значение поля в результате
Возвращает:: объект того же типа со значением указанного поля, не null
ИИсключения:: DateTimeException - если поле не может быть установлено; UnsupportedTemporalTypeException - если поле не поддерживается; ArithmeticException - если произошел переполнение чисел

plus

default ChronoLocalDate plus(TemporalAmount amount)

Возвращает объект того же типа, что и этот объект, с добавленной величиной.

Корректирует этот временной объект, добавляя в соответствии с правилами указанного значения. Значение обычно является Period, но может быть любого другого типа, реализующего интерфейс TemporalAmount, например, Duration.

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

date = date.plus(period);                // add a Period instance
  date = date.plus(duration);              // add a Duration instance
  date = date.plus(workingDays(6));        // example user-written workingDays method

Обратите внимание, что вызов plus за которым следует minus не гарантирует возвращения той же даты и времени.

Задано в:: plus в интерфейсе Temporal
Параметры:: amount - величина для добавления, не null
Возвращает:: объект того же типа с произведенной корректировкой, не null
ИИсключения:: DateTimeException - если добавление невозможно; ArithmeticException - если произошел переполнение чисел

plus

default ChronoLocalDate plus(long amountToAdd,
                             TemporalUnit unit)

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

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

В некоторых случаях изменение поля не полностью определено. Например, если целевой объект является датой, представляющей 31 января, то добавление одного месяца будет неясно. В таких случаях поле отвечает за разрешение результата. Обычно оно выбирает предыдущую допустимую дату, которая в данном примере будет последним допустимым днем февраля.

Определено в:: plus в интерфейсе Temporal
Параметры:: amountToAdd - количество указанной единицы для добавления, может быть отрицательным; unit - единица количества для добавления, не null
Возвращает:: объект того же типа с добавленным указанным периодом, не null
Выбрасывает:: DateTimeException - если единицу нельзя добавить; ArithmeticException - если произошел переполнение числовых значений

minus

default ChronoLocalDate minus(TemporalAmount amount)

Возвращает объект того же типа, что и этот объект, со вычтенным значением.

Это корректирует эту временную метку, вычитая согласно правилам указанного значения. Значение обычно является Period, но может быть и любого другого типа, реализующего интерфейс TemporalAmount, например, Duration.

Примеры кода, показывающие, как и почему используется этот метод:

date = date.minus(period);               // subtract a Period instance
  date = date.minus(duration);             // subtract a Duration instance
  date = date.minus(workingDays(6));       // example user-written workingDays method

Обратите внимание, что вызов plus за которым следует minus не гарантирует, что будет возвращена та же дата и время.

Определено в:: minus в интерфейсе Temporal
Параметры:: amount - значение для вычитания, не null
Возвращает:: объект того же типа с произведенной корректировкой, не null
Выбрасывает:: DateTimeException - если вычитание невозможно; ArithmeticException - если произошло переполнение числовых значений

minus

default ChronoLocalDate minus(long amountToSubtract,
                              TemporalUnit unit)

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

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

В некоторых случаях изменение поля не полностью определено. Например, если целевой объект является датой, представляющей 31 марта, то вычитание одного месяца будет неясно. В таких случаях поле отвечает за разрешение результата. Обычно оно выбирает предыдущую допустимую дату, которая в данном примере будет последним допустимым днем февраля.

Определено в:: minus в интерфейсе Temporal
Параметры:: amountToSubtract - количество указанной единицы для вычитания, может быть отрицательным; unit - единица количества для вычитания, не null
Возвращает:: объект того же типа с вычтенным указанным периодом, не null
Выбрасывает:: DateTimeException - если единицу нельзя вычесть; UnsupportedTemporalTypeException - если единица не поддерживается; ArithmeticException - если произошло переполнение числовых значений

query

default <R> R query(TemporalQuery<R> query)

Запрашивает эту дату, используя указанный запрос.

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

Результат этого метода получается путем вызова метода TemporalQuery.queryFrom(TemporalAccessor) на указанном запросе, передав this в качестве аргумента.

Определено в:: query в интерфейсе TemporalAccessor
Параметры типа:: R - тип результата
Параметры:: query - запрос для вызова, не null
Возвращает:: результат запроса, может быть null (определено запросом)
Выбрасывает:: DateTimeException - если запрос не удается (определено запросом); ArithmeticException - если происходит переполнение числовых значений (определено запросом)

adjustInto

default Temporal adjustInto(Temporal temporal)

Корректирует указанный временной объект, чтобы он имел ту же дату, что и этот объект.

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

Корректировка эквивалентна использованию Temporal.with(TemporalField, long), передавая ChronoField.EPOCH_DAY в качестве поля.

В большинстве случаев яснее использовать обратный порядок вызова, используя Temporal.with(TemporalAdjuster):

// these two lines are equivalent, but the second approach is recommended
   temporal = thisLocalDate.adjustInto(temporal);
   temporal = temporal.with(thisLocalDate);

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

Определено в:: adjustInto в интерфейсе TemporalAdjuster
Параметры:: temporal - целевой объект, подлежащий корректировке, не null
Возвращает:: скорректированный объект, не null
Выбрасывает:: DateTimeException - если корректировка невозможна; ArithmeticException - если произошло переполнение числовых значений

until

long until(Temporal endExclusive,
           TemporalUnit unit)

Вычисляет количество времени до другой даты в терминах указанной единицы.

Это вычисляет количество времени между двумя ChronoLocalDate объектами в терминах одной TemporalUnit. Начальная и конечная точки — this и указанная дата. Результат будет отрицательным, если конечная точка стоит до начальной. Temporal , переданный в этот метод, преобразуется в ChronoLocalDate с помощью Chronology.date(TemporalAccessor). Вычисление возвращает целое число, представляющее количество полных единиц между двумя датами. Например, количество дней между двумя датами можно вычислить, используя startDate.until(endDate, DAYS).

Существует два равнозначных способа использования этого метода. Первый — вызвать этот метод. Второй — использовать TemporalUnit.between(Temporal, Temporal):

// these two lines are equivalent
   amount = start.until(end, MONTHS);
   amount = MONTHS.between(start, end);

Выбор следует делать, исходя из того, что делает код более удобочитаемым.

Вычисление реализовано в этом методе для ChronoUnit. Единицы DAYS, WEEKS, MONTHS, YEARS, DECADES, CENTURIES, MILLENNIA и ERAS должны быть поддержаны всеми реализациями. Другие значения ChronoUnit будут вызывать исключение.

Если единица не является ChronoUnit, то результат этого метода получается путем вызова TemporalUnit.between(Temporal, Temporal) , передав this в качестве первого аргумента и преобразованный входной временной объект в качестве второго аргумента.

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

Определено в:: until в интерфейсе Temporal
Параметры:: endExclusive - конечная дата, исключая, которая преобразуется в ChronoLocalDate в той же хронологии, не null; unit - единица измерения количества, не null
Возвращает:: количество времени между этой датой и конечной датой
Выбрасывает:: DateTimeException - если количество не может быть вычислено, или конечный временной объект не может быть преобразован в ChronoLocalDate; UnsupportedTemporalTypeException - если единица не поддерживается; ArithmeticException - если произошел переполнение числовых значений

until

ChronoPeriod until(ChronoLocalDate endDateExclusive)

Вычисляет период между этой датой и другой датой как ChronoPeriod.

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

Начальная и конечная точки — this и указанная дата. Результат будет отрицательным, если конечная точка стоит до начальной. Знак минус будет одинаковым для года, месяца и дня.

Вычисление выполняется с использованием хронологии этой даты. При необходимости входная дата будет преобразована в соответствии.

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

Параметры:: endDateExclusive - конечная дата, исключая, которая может быть в любой хронологии, не null
Возвращает:: период между этой датой и конечной датой, не null
Выбрасывает:: DateTimeException - если период не может быть вычислен; ArithmeticException - если произошел переполнение числовых значений

format

default String format(DateTimeFormatter formatter)

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

Эта дата будет передана форматировщику для получения строки.

Реализация по умолчанию должна действовать следующим образом:

return formatter.format(this);

Параметры:: formatter - используемый форматировщик, не null
Возвращает:: строка отформатированной даты, не null
Выбрасывает:: DateTimeException - если произошла ошибка во время печати

atTime

default ChronoLocalDateTime<?> atTime(LocalTime localTime)

Объединяет эту дату со временем для создания ChronoLocalDateTime.

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

Параметры:: localTime - используемое местное время, не null
Возвращает:: локальная дата и время, сформированные из этой даты и указанного времени, не null

toEpochDay

default long toEpochDay()

Преобразует эту дату в эпохальный день.

Значение Epoch Day count представляет собой простое нарастающее число дней, где день 0 — 1970-01-01 (ISO). Это определение одинаково для всех хронологий, что позволяет выполнять преобразования.

Это реализация по умолчанию обращается к полю EPOCH_DAY.

Возвращает:: эпохальный день, соответствующий этой дате

compareTo

default int compareTo(ChronoLocalDate other)

Сравнивает эту дату с другой датой, включая хронологию.

Сравнение основано сначала на дате на основной временной оси, а затем на хронологии. Оно «согласуется с equals», как определено в Comparable.

Например, порядок сравнения следующий:

2012-12-03 (ISO)
2012-12-04 (ISO)
2555-12-04 (ThaiBuddhist)
2012-12-05 (ISO)

Значения #2 и #3 представляют одну и ту же дату на временной оси. Когда два значения представляют одну и ту же дату, сравнивается идентификатор хронологии, чтобы отличить их. Этот шаг необходим для того, чтобы порядок «согласовывался с equals».

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

Эта реализация по умолчанию выполняет указанное выше сравнение.

Определено в:: compareTo в интерфейсе Comparable<ChronoLocalDate>
Параметры:: other - другая дата для сравнения, не null
Возвращает:: значение компаратора, отрицательное, если меньше, положительное, если больше

isAfter

default boolean isAfter(ChronoLocalDate other)

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

Этот метод отличается от сравнения в compareTo(java.time.chrono.ChronoLocalDate) тем, что он сравнивает только основную дату, а не хронологию. Это позволяет сравнивать даты в разных календарных системах по их положению на временной оси. Это эквивалентно использованию date1.toEpochDay() > date2.toEpochDay().

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

Параметры:: other - другая дата для сравнения, не null
Возвращает:: true, если эта дата после указанной даты

isBefore

default boolean isBefore(ChronoLocalDate other)

Проверяет, является ли эта дата до указанной даты, игнорируя хронологию.

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

Параметры:: other - другая дата для сравнения, не null
Возвращает:: true, если эта дата до указанной даты

isEqual

default boolean isEqual(ChronoLocalDate other)

Проверяет, равна ли эта дата указанной дате, игнорируя хронологию.

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

Параметры:: other - другая дата для сравнения, не null
Возвращает:: true, если основная дата равна указанной дате

equals

boolean equals(Object obj)

Проверяет, равна ли эта дата другой дате, включая хронологию.

Сравнивает эту дату с другой, гарантируя, что дата и хронология одинаковы.

Для сравнения дат двух TemporalAccessor объектов, включая даты в двух разных хронологиях, используйте ChronoField.EPOCH_DAY в качестве компаратора.

Переопределяет:: 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/ChronoLocalDate.html