Класс MonthDay

java.lang.Object

java.time.MonthDay

Все реализованные интерфейсы:: Serializable, Comparable<MonthDay>, TemporalAccessor, TemporalAdjuster

public final class MonthDay extends Object implements TemporalAccessor, TemporalAdjuster, Comparable<MonthDay>, Serializable

Месяц и день в системе календаря ISO-8601, например, --12-03.

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

Этот класс не хранит и не представляет год, время или часовой пояс. Например, значение «3 декабря» может храниться в MonthDay.

Поскольку у MonthDay нет года, високосный день 29 февраля считается допустимым.

Этот класс реализует TemporalAccessor, а не Temporal. Это связано с тем, что нельзя определить, является ли 29 февраля допустимым или нет без внешней информации, что препятствует реализации операций сложения/вычитания. В связи с этим, MonthDay предоставляет только доступ для запроса и установки полей MONTH_OF_YEAR и DAY_OF_MONTH.

Система календаря ISO-8601 — это современная гражданская система календаря, используемая сегодня в большинстве стран мира. Она эквивалентна пролептической системе григорианского календаря, в которой современные правила високосных лет применяются для всех времен. Для большинства современных приложений правила ISO-8601 полностью подходят. Однако любое приложение, использующее исторические даты и требующее их точности, обнаружит, что подход ISO-8601 не подходит.

Это бессвязный класс; программисты должны рассматривать экземпляры, которые равны, как взаимозаменяемые и не должны использовать экземпляры для синхронизации, иначе может произойти непредсказуемое поведение. Например, в будущих версиях синхронизация может не сработать. Для сравнений следует использовать метод equals.

Требования к реализации:

Этот класс неизменяемый и потокобезопасный.

С:

1.8

См. также:

Краткое описание методов

Модификатор и тип	Метод	Описание
`Temporal`	`adjustInto(Temporal temporal)`	Настраивает указанный временной объект так, чтобы он соответствовал этому месяцу и дню.
`LocalDate`	`atYear(int year)`	Объединяет этот месяц и день с годом, чтобы создать `LocalDate`.
`int`	`compareTo(MonthDay other)`	Сравнивает этот месяц и день с другим месяцем и днем.
`boolean`	`equals(Object obj)`	Проверяет, равен ли этот месяц и день другому месяцу и дню.
`String`	`format(DateTimeFormatter formatter)`	Форматирует этот месяц и день с использованием указанного форматера.
`static MonthDay`	`from(TemporalAccessor temporal)`	Получает экземпляр `MonthDay` из временного объекта.
`int`	`get(TemporalField field)`	Возвращает значение указанного поля из этого месяца и дня как `int`.
`int`	`getDayOfMonth()`	Возвращает поле день месяца.
`long`	`getLong(TemporalField field)`	Возвращает значение указанного поля из этого месяца и дня как `long`.
`Month`	`getMonth()`	Возвращает поле месяц года, используя перечисление `Month`.
`int`	`getMonthValue()`	Возвращает поле месяц года от 1 до 12.
`int`	`hashCode()`	Код хэша для этого месяца и дня.
`boolean`	`isAfter(MonthDay other)`	Проверяет, предшествует ли этот месяц и день указанному месяцу и дню.
`boolean`	`isBefore(MonthDay other)`	Проверяет, следует ли этот месяц и день за указанным месяцем и днем.
`boolean`	`isSupported(TemporalField field)`	Проверяет, поддерживается ли указанное поле.
`boolean`	`isValidYear(int year)`	Проверяет, допустим ли год для этого месяца и дня.
`static MonthDay`	`now()`	Получает текущий месяц и день из системных часов в стандартном часовом поясе.
`static MonthDay`	`now(Clock clock)`	Получает текущий месяц и день из указанных часов.
`static MonthDay`	`now(ZoneId zone)`	Получает текущий месяц и день из системных часов в указанном часовом поясе.
`static MonthDay`	`of(int month, int dayOfMonth)`	Получает экземпляр `MonthDay`.
`static MonthDay`	`of(Month month, int dayOfMonth)`	Получает экземпляр `MonthDay`.
`static MonthDay`	`parse(CharSequence text)`	Получает экземпляр `MonthDay` из текстовой строки, например, `--12-03`.
`static MonthDay`	`parse(CharSequence text, DateTimeFormatter formatter)`	Получает экземпляр `MonthDay` из текстовой строки, используя определённый форматер.
`<R> R`	`query(TemporalQuery<R> query)`	Запрашивает этот месяц и день, используя указанный запрос.
`ValueRange`	`range(TemporalField field)`	Возвращает диапазон допустимых значений для указанного поля.
`String`	`toString()`	Выводит этот месяц и день как `String`, например, `--12-03`.
`MonthDay`	`with(Month month)`	Возвращает копию этого `MonthDay` с изменённым месяцем года.
`MonthDay`	`withDayOfMonth(int dayOfMonth)`	Возвращает копию этого `MonthDay` с изменённым днём месяца.
`MonthDay`	`withMonth(int month)`	Возвращает копию этого `MonthDay` с изменённым месяцем года.

Методы, объявленные в классе java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Подробное описание методов

now

public static MonthDay now()

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

Это обратится к system clock в часовом поясе по умолчанию, чтобы получить текущее число месяца.

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

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

now

public static MonthDay now(ZoneId zone)

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

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

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

now

public static MonthDay now(Clock clock)

Получает текущее число месяца с указанных часов.

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

Параметры:: clock - используемые часы, не null
Возвращает:: текущее число месяца, не null

of

public static MonthDay of(Month month, int dayOfMonth)

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

Число месяца должно быть допустимым для месяца в високосный год. Таким образом, для февраля день 29 допустим.

Например, передача апреля и дня 31 вызовет исключение, так как никогда не может быть 31 апреля в любом году. Напротив, передача 29 февраля допустима, так как этот день месяца иногда может быть допустимым.

Параметры:: month - месяц для представления, не null; dayOfMonth - число месяца для представления, от 1 до 31
Возвращает:: число месяца, не null
Выбрасывает:: DateTimeException - если значение любого поля находится за пределами допустимого диапазона или если число месяца недопустимо для месяца

of

public static MonthDay of(int month, int dayOfMonth)

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

Число месяца должно быть допустимым для месяца в високосный год. Таким образом, для месяца 2 (февраль) день 29 допустим.

Например, передача месяца 4 (апрель) и дня 31 вызовет исключение, так как никогда не может быть 31 апреля в любом году. Напротив, передача 29 февраля допустима, так как этот день месяца иногда может быть допустимым.

Параметры:: month - месяц для представления, от 1 (январь) до 12 (декабрь); dayOfMonth - число месяца для представления, от 1 до 31
Возвращает:: число месяца, не null
Выбрасывает:: DateTimeException - если значение любого поля находится за пределами допустимого диапазона или если число месяца недопустимо для месяца

from

public static MonthDay from(TemporalAccessor temporal)

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

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

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

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

Параметры:: temporal - временной объект для преобразования, не null
Возвращает:: число месяца, не null
Выбрасывает:: DateTimeException - если невозможно выполнить преобразование в MonthDay

parse

public static MonthDay parse(CharSequence text)

Получает экземпляр MonthDay из текстовой строки, например, --12-03.

Строка должна представлять допустимое число месяца. Формат --MM-dd.

Параметры:: text - текст для разбора, например "--12-03", не null
Возвращает:: разборённое число месяца, не null
Выбрасывает:: DateTimeParseException - если текст не может быть разборён

parse

public static MonthDay parse(CharSequence text, DateTimeFormatter formatter)

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

Текст анализируется с помощью форматера, возвращая число месяца.

Параметры:: text - текст для разбора, не null; formatter - используемый форматер, не null
Возвращает:: разборённое число месяца, не null
Выбрасывает:: DateTimeParseException - если текст не может быть разборён

isSupported

public boolean isSupported(TemporalField field)

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

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

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

MONTH_OF_YEAR
YEAR

Все другие ChronoField экземпляры вернут false.

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

Определено в:: isSupported в интерфейсе TemporalAccessor
Параметры:: field - проверяемое поле, null возвращает false
Возвращает:: true, если поле поддерживается этим числом месяца, false — если нет

range

public ValueRange range(TemporalField field)

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

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

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

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

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

get

public int get(TemporalField field)

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

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

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

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

Определено в:: get в интерфейсе TemporalAccessor
Параметры:: field - поле для получения, не null
Возвращает:: значение для поля
Выбрасывает:: DateTimeException - если значение для поля получить невозможно или значение находится вне диапазона допустимых значений для поля; UnsupportedTemporalTypeException - если поле не поддерживается или диапазон значений превышает int; ArithmeticException - если происходит переполнение численного типа

getLong

public long getLong(TemporalField field)

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

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

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

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

Specified by:: getLong в интерфейсе TemporalAccessor
Parameters:: field - поле для получения, не null
Returns:: значение для поля
Throws:: DateTimeException - если значение для поля получить невозможно; UnsupportedTemporalTypeException - если поле не поддерживается; ArithmeticException - если происходит переполнение числовых значений

getMonthValue

public int getMonthValue()

Получает поле месяца от 1 до 12.

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

Returns:

месяц, от 1 до 12

See Also:

getMonth

public Month getMonth()

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

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

Returns:

месяц, не null

See Also:

getDayOfMonth

public int getDayOfMonth()

Получает поле дня месяца.

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

Returns:: день месяца, от 1 до 31

isValidYear

public boolean isValidYear(int year)

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

Этот метод проверяет, образуют ли этот месяц, день и введённый год допустимую дату. Возвращает false только для 29 февраля.

Parameters:

year - год для проверки

Returns:

true, если год допустим для этого месяца-дня

See Also:

withMonth

public MonthDay withMonth(int month)

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

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

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

Parameters:: month - месяц для установки в возвращаемом месяце-дне, от 1 (январь) до 12 (декабрь)
Returns:: месяц-день на основе этого месяца-дня с запрошенным месяцем, не null
Throws:: DateTimeException - если значение месяца неверно

with

public MonthDay with(Month month)

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

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

Parameters:: month - месяц для установки в возвращаемом месяце-дне, не null
Returns:: месяц-день на основе этого месяца-дня с запрошенным месяцем, не null

withDayOfMonth

public MonthDay withDayOfMonth(int dayOfMonth)

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

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

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

Parameters:: dayOfMonth - день месяца для установки в возвращаемом месяце-дне, от 1 до 31
Returns:: месяц-день на основе этого месяца-дня с запрошенным днём, не null
Throws:: DateTimeException - если значение дня месяца неверно или если день месяца недопустим для месяца

query

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

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

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

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

Specified by:: query в интерфейсе TemporalAccessor
Type Parameters:: R - тип результата
Parameters:: query - запрос для вызова, не null
Returns:: результат запроса, может быть null (определяется запросом)
Throws:: DateTimeException - если запрос выполнить не удалось (определяется запросом); ArithmeticException - если происходит переполнение числовых значений (определяется запросом)

adjustInto

public Temporal adjustInto(Temporal temporal)

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

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

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

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

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

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

Specified by:: adjustInto в интерфейсе TemporalAdjuster
Parameters:: temporal - целевой объект для корректировки, не null
Returns:: скорректированный объект, не null
Throws:: DateTimeException - если корректировка невозможна; ArithmeticException - если происходит переполнение числовых значений

format

public String format(DateTimeFormatter formatter)

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

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

Parameters:: formatter - используемый форматер, не null
Returns:: строка отформатированного месяца-дня, не null
Throws:: DateTimeException - если произошла ошибка при печати

atYear

public LocalDate atYear(int year)

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

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

Месяц-день 29 февраля будет скорректирован на 28 февраля в полученной дате, если год не високосный.

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

Parameters:: year - используемый год, от MIN_YEAR до MAX_YEAR
Returns:: локальная дата, сформированная из этого месяца-дня и указанного года, не null
Throws:: DateTimeException - если год находится вне допустимого диапазона годов

compareTo

public int compareTo(MonthDay other)

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

Сравнение основано сначала на значении месяца, затем на значении дня. Оно "совместимо с equals", как определено в Comparable.

Specified by:

compareTo в интерфейсе Comparable<MonthDay>

Parameters:

other - другой месяц-день для сравнения, не null

Returns:

значение сравнения, меньше нуля, если этот месяц-день раньше other, ноль, если они равны, больше нуля, если этот месяц-день позже other

See Also:

isAfter

public boolean isAfter(MonthDay other)

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

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

isBefore

public boolean isBefore(MonthDay other)

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

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

equals

public boolean equals(Object obj)

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

Сравнение основано на временном положении дня месяца в году.

Переопределяет:

equals в классе Object

Параметры:

obj - объект для проверки, null возвращает false

Возвращает:

true, если этот день месяца равен другому

См. также:

hashCode

public int hashCode()

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

Переопределяет:

hashCode в классе Object

Возвращает:

подходящий хэш-код

См. также:

toString

public String toString()

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

Вывод будет в формате --MM-dd:

Переопределяет:: toString в классе Object
Возвращает:: строковое представление этого дня месяца, не null

© 1993, 2023, 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/21/docs/api/java.base/java/time/MonthDay.html