Класс Year

public static final int MIN_VALUE

Минимальный поддерживаемый год: «-999,999,999».

public static final int MAX_VALUE

Максимальный поддерживаемый год: «+999,999,999».

public static Year now()

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

Для получения текущего года выполняется запрос к system clock в часовом поясе по умолчанию.

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

public static Year now(ZoneId zone)

Получает текущий год по системным часам в указанном часовом поясе.

Для получения текущего года выполняется запрос к system clock. Указание часового пояса позволяет избежать зависимости от часового пояса по умолчанию.

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

public static Year now(Clock clock)

Получает текущий год по указанным часам.

Для получения текущего года выполняется запрос к указанным часам. Этот метод позволяет использовать альтернативные часы для тестирования. Альтернативные часы можно создать с помощью dependency injection.

public static Year of(int isoYear)

Получает экземпляр Year.

Этот метод принимает значение года в пролептической календарной системе ISO.

Год 2 н. э. представлен числом 2.
Год 1 н. э. представлен числом 1.
Год 1 до н. э. представлен числом 0.
Год 2 до н. э. представлен числом -1.

public static Year from(TemporalAccessor temporal)

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

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

Преобразование извлекает поле year. Извлечение допускается только в том случае, если временной объект использует хронологию ISO или может быть преобразован в LocalDate.

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

public static Year parse(CharSequence text)

Получает экземпляр Year из текстовой строки, например 2007.

Строка должна представлять допустимый год.

public static Year parse(CharSequence text, DateTimeFormatter formatter)

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

Текст разбирается с помощью форматировщика, и возвращается год.

public static boolean isLeap(long year)

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

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

Например, 1904 год високосный, поскольку делится на 4. 1900 год не был високосным, поскольку делится на 100, однако 2000 год был високосным, поскольку делится на 400.

Вычисление является пролептическим: те же правила применяются в далеком будущем и далеком прошлом. Это исторически неточно, но соответствует стандарту ISO-8601.

public int getValue()

Получает значение года.

Год, возвращаемый этим методом, является пролептическим в соответствии с get(YEAR).

public boolean isSupported(TemporalField field)

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

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

Если поле является ChronoField, запрос обрабатывается здесь. Поддерживаются следующие поля:

• YEAR_OF_ERA
• YEAR
• ERA

Для всех остальных экземпляров ChronoField будет возвращено false.

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

public boolean isSupported(TemporalUnit unit)

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

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

Если единица измерения является ChronoUnit, запрос обрабатывается здесь. Поддерживаются следующие единицы измерения:

• YEARS
• DECADES
• CENTURIES
• MILLENNIA
• ERAS

Для всех остальных экземпляров ChronoUnit будет возвращено false.

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

public ValueRange range(TemporalField field)

Получает диапазон допустимых значений указанного поля.

Объект диапазона содержит минимальное и максимальное допустимые значения поля. Этот год используется для повышения точности возвращаемого диапазона. Если вернуть диапазон невозможно, поскольку поле не поддерживается или по какой-либо другой причине, выбрасывается исключение.

Если поле является ChronoField, запрос обрабатывается здесь. Метод supported fields возвращает соответствующие экземпляры диапазона. Для всех остальных экземпляров ChronoField будет выброшено исключение UnsupportedTemporalTypeException.

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

public int get(TemporalField field)

Получает значение указанного поля этого года в виде int.

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

Если поле является ChronoField, запрос обрабатывается здесь. Метод supported fields возвращает допустимые значения с учетом этого года. Для всех остальных экземпляров ChronoField будет выброшено исключение UnsupportedTemporalTypeException.

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

public long getLong(TemporalField field)

Получает значение указанного поля этого года в виде long.

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

Если поле является ChronoField, запрос обрабатывается здесь. Метод supported fields возвращает допустимые значения с учетом этого года. Для всех остальных экземпляров ChronoField будет выброшено исключение UnsupportedTemporalTypeException.

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

public boolean isLeap()

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

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

Например, 1904 год високосный, поскольку делится на 4. 1900 год не был високосным, поскольку делится на 100, однако 2000 год был високосным, поскольку делится на 400.

Вычисление является пролептическим: те же правила применяются в далеком будущем и далеком прошлом. Это исторически неточно, но соответствует стандарту ISO-8601.

public boolean isValidMonthDay(MonthDay monthDay)

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

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

public int length()

Получает длину этого года в днях.

public Year with(TemporalAdjuster adjuster)

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

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

Результат этого метода получается вызовом метода TemporalAdjuster.adjustInto(Temporal) у указанного корректировщика с аргументом this.

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

public Year with(TemporalField field, long newValue)

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

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

Если поле является ChronoField, корректировка выполняется здесь. Поддерживаемые поля обрабатываются следующим образом:

• YEAR_OF_ERA — возвращает Year с указанным годом эры. Эра останется неизменной.
• YEAR — возвращает Year с указанным годом. Это полностью заменяет дату и эквивалентно вызову of(int).
• ERA — возвращает Year с указанной эрой. Год эры останется неизменным.

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

Для всех остальных экземпляров ChronoField будет выброшено исключение UnsupportedTemporalTypeException.

Если поле не является ChronoField, результат этого метода получается вызовом TemporalField.adjustInto(Temporal, long) с аргументом this. В этом случае поле определяет, следует ли корректировать момент времени и каким образом.

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

public Year plus(TemporalAmount amountToAdd)

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

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

Вычисление делегируется объекту величины путем вызова TemporalAmount.addTo(Temporal). Реализация величины может выполнять сложение любым способом, однако обычно она вызывает plus(long, TemporalUnit). Ознакомьтесь с документацией реализации величины, чтобы определить, можно ли успешно выполнить сложение.

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

public Year plus(long amountToAdd, TemporalUnit unit)

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

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

Если поле является ChronoUnit, сложение выполняется здесь. Поддерживаемые поля обрабатываются следующим образом:

• YEARS — возвращает Year с прибавленным указанным количеством лет. Эквивалентно вызову plusYears(long).
• DECADES — возвращает Year с прибавленным указанным количеством десятилетий. Эквивалентно вызову plusYears(long) с величиной, умноженной на 10.
• CENTURIES — возвращает Year с прибавленным указанным количеством столетий. Эквивалентно вызову plusYears(long) с величиной, умноженной на 100.
• MILLENNIA — возвращает Year с прибавленным указанным количеством тысячелетий. Эквивалентно вызову plusYears(long) с величиной, умноженной на 1 000.
• ERAS — возвращает Year с прибавленным указанным количеством эр. Поддерживаются только две эры, поэтому величина должна быть равна единице, нулю или минус единице. Если величина не равна нулю, год изменяется так, чтобы год эры остался неизменным.

Для всех остальных экземпляров ChronoUnit будет выброшено исключение UnsupportedTemporalTypeException.

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

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

public Year plusYears(long yearsToAdd)

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

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

public Year minus(TemporalAmount amountToSubtract)

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

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

Вычисление делегируется объекту величины путем вызова TemporalAmount.subtractFrom(Temporal). Реализация величины может выполнять вычитание любым способом, однако обычно она вызывает minus(long, TemporalUnit). Ознакомьтесь с документацией реализации величины, чтобы определить, можно ли успешно выполнить вычитание.

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

public Year minus(long amountToSubtract, TemporalUnit unit)

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

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

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

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

public Year minusYears(long yearsToSubtract)

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

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

public <R> R query(TemporalQuery<R> query)

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

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

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

public Temporal adjustInto(Temporal temporal)

Изменяет указанный объект temporal так, чтобы в нем был установлен этот год.

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

Изменение эквивалентно использованию метода Temporal.with(TemporalField, long) с передачей ChronoField.YEAR в качестве поля. Если указанный объект temporal не использует календарную систему ISO, выбрасывается DateTimeException.

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

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

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

public long until(Temporal endExclusive, TemporalUnit unit)

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

Метод вычисляет промежуток времени между двумя объектами Year в единицах одной TemporalUnit. Начальная и конечная точки — это this и указанный год. Результат будет отрицательным, если конечная точка предшествует начальной. Переданная этому методу Temporal преобразуется в Year с помощью from(TemporalAccessor). Например, промежуток в десятилетиях между двумя годами можно вычислить с помощью startYear.until(endYear, DECADES).

Результатом вычисления является целое число, представляющее количество полных единиц между двумя годами. Например, промежуток в десятилетиях между 2012 и 2031 годами составит только одно десятилетие, поскольку до двух десятилетий не хватает одного года.

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

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

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

Вычисление в этом методе реализовано для ChronoUnit. Поддерживаются единицы YEARS, DECADES, CENTURIES, MILLENNIA и ERAS. При использовании других значений ChronoUnit будет выброшено исключение.

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

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

public String format(DateTimeFormatter formatter)

Форматирует этот год с помощью указанного форматировщика.

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

public LocalDate atDay(int dayOfYear)

Объединяет этот год с днем года, чтобы создать LocalDate.

Возвращает LocalDate, сформированный из этого года и указанного дня года.

Значение дня года 366 допустимо только в високосный год.

public YearMonth atMonth(Month month)

Объединяет этот год с месяцем, чтобы создать YearMonth.

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

Этот метод можно использовать как часть цепочки вызовов для формирования даты:

 LocalDate date = year.atMonth(month).atDay(day);

public YearMonth atMonth(int month)

Объединяет этот год с месяцем, чтобы создать YearMonth.

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

Этот метод можно использовать как часть цепочки вызовов для формирования даты:

 LocalDate date = year.atMonth(month).atDay(day);

public LocalDate atMonthDay(MonthDay monthDay)

Объединяет этот год с месяцем и днем, чтобы создать LocalDate.

Возвращает LocalDate, сформированный из этого года и указанного месяца и дня.

Если год не является високосным, то дата 29 февраля будет скорректирована до 28 февраля.

public int compareTo(Year other)

Сравнивает этот год с другим годом.

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

public boolean isAfter(Year other)

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

public boolean isBefore(Year other)

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

public boolean equals(Object obj)

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

Сравнение основано на положении годов на временной шкале.

public int hashCode()

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

public String toString()

Представляет этот год в виде String.