Класс YearMonth

public static YearMonth now()

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

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

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

public static YearMonth now(ZoneId zone)

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

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

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

public static YearMonth now(Clock clock)

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

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

public static YearMonth of(int year, Month month)

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

public static YearMonth of(int year, int month)

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

public static YearMonth from(TemporalAccessor temporal)

Создает экземпляр YearMonth на основе временного объекта.

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

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

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

public static YearMonth parse(CharSequence text)

Создает экземпляр YearMonth на основе текстовой строки, например 2007-12.

Строка должна представлять допустимую комбинацию года и месяца. Формат должен быть uuuu-MM. Перед годами, выходящими за диапазон от 0000 до 9999, должен стоять знак плюса или минуса.

public static YearMonth parse(CharSequence text, DateTimeFormatter formatter)

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

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

public boolean isSupported(TemporalField field)

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

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

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

• MONTH_OF_YEAR
• PROLEPTIC_MONTH
• YEAR_OF_ERA
• YEAR
• ERA

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

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

public boolean isSupported(TemporalUnit unit)

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

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

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

• MONTHS
• 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 возвращает допустимые значения на основе этого года-месяца, за исключением PROLEPTIC_MONTH, значение которого слишком велико для представления в int и для которого выбрасывается DateTimeException. Для всех остальных экземпляров ChronoField выбрасывается UnsupportedTemporalTypeException.

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

public long getLong(TemporalField field)

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

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

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

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

public int getYear()

Получает поле года.

Этот метод возвращает примитивное значение int для года.

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

public int getMonthValue()

Получает поле месяца года в диапазоне от 1 до 12.

Этот метод возвращает месяц в виде int в диапазоне от 1 до 12. Код приложения часто становится понятнее, если использовать перечисление Month, вызывая getMonth().

public Month getMonth()

Получает поле месяца года с использованием перечисления Month.

Этот метод возвращает для месяца значение перечисления Month. Это позволяет избежать неоднозначности значений int. Если требуется доступ к примитивному значению int, перечисление предоставляет метод int value.

public boolean isLeapYear()

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

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

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

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

public boolean isValidDay(int dayOfMonth)

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

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

public int lengthOfMonth()

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

Возвращает продолжительность месяца в днях. Например, для даты в январе будет возвращено 31.

public int lengthOfYear()

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

Возвращает продолжительность года в днях: 365 или 366.

public YearMonth with(TemporalAdjuster adjuster)

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

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

Простой корректировщик может просто установить значение одного из полей, например года. Более сложный корректировщик может установить год-месяц, соответствующий следующему сближению кометы Галлея с Землей.

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

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

public YearMonth with(TemporalField field, long newValue)

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

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

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

• MONTH_OF_YEAR — возвращает YearMonth с указанным месяцем года. Год остается неизменным.
• PROLEPTIC_MONTH — возвращает YearMonth с указанным пролептическим месяцем. Поля года и месяца этого объекта полностью заменяются.
• YEAR_OF_ERA — возвращает YearMonth с указанным годом эры. Месяц и эра остаются неизменными.
• YEAR — возвращает YearMonth с указанным годом. Месяц остается неизменным.
• ERA — возвращает YearMonth с указанной эрой. Месяц и год эры остаются неизменными.

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

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

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

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

public YearMonth withYear(int year)

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

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

public YearMonth withMonth(int month)

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

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

public YearMonth plus(TemporalAmount amountToAdd)

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

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

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

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

public YearMonth plus(long amountToAdd, TemporalUnit unit)

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

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

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

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

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

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

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

public YearMonth plusYears(long yearsToAdd)

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

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

public YearMonth plusMonths(long monthsToAdd)

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

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

public YearMonth minus(TemporalAmount amountToSubtract)

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

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

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

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

public YearMonth minus(long amountToSubtract, TemporalUnit unit)

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

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

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

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

public YearMonth minusYears(long yearsToSubtract)

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

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

public YearMonth minusMonths(long monthsToSubtract)

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

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

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

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

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

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

public Temporal adjustInto(Temporal temporal)

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

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

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

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

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

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

public long until(Temporal endExclusive, TemporalUnit unit)

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

Вычисляет промежуток времени между двумя объектами YearMonth в единицах одной TemporalUnit. Начальная и конечная точки — это this и указанный год-месяц. Если конечная точка предшествует начальной, результат будет отрицательным. Переданный этому методу объект Temporal преобразуется в YearMonth с помощью from(TemporalAccessor). Например, промежуток в годах между двумя годами-месяцами можно вычислить с помощью startYearMonth.until(endYearMonth, YEARS).

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

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

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

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

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

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

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

public String format(DateTimeFormatter formatter)

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

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

public LocalDate atDay(int dayOfMonth)

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

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

Значение дня месяца должно быть допустимым для данного года-месяца.

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

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

public LocalDate atEndOfMonth()

Возвращает LocalDate на конец месяца.

Возвращает LocalDate на основе этого года-месяца. День месяца устанавливается в последний допустимый день месяца с учетом високосных лет.

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

 LocalDate date = year.atMonth(month).atEndOfMonth();

public int compareTo(YearMonth other)

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

Сначала сравниваются значения года, затем значения месяца. Результат согласован с equals («consistent with equals»), как определено в Comparable.

public boolean isAfter(YearMonth other)

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

public boolean isBefore(YearMonth other)

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

public boolean equals(Object obj)

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

Сравнение выполняется по положению года-месяца на временной шкале.

public int hashCode()

Хеш-код этого года-месяца.

public String toString()

Выводит этот год-месяц в виде String, например 2007-12.

Вывод будет представлен в формате uuuu-MM: