Класс 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.with(TemporalField, long) с передачей ChronoField.YEAR в качестве поля. Если указанный объект времени не использует календарную систему 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 в качестве первого аргумента, а преобразованного входного объекта времени — в качестве второго аргумента.

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

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.