Temporal.PlainMonthDay.from()

Статический метод Temporal.PlainMonthDay.from() создает новый объект Temporal.PlainMonthDay из другого объекта Temporal.PlainMonthDay, объекта со свойствами месяца и дня, или из строки RFC 9557.

Синтаксис

Temporal.PlainMonthDay.from(info)
Temporal.PlainMonthDay.from(info, options)

Параметры

info

Одно из следующего:

• Экземпляр Temporal.PlainMonthDay, который создает копию этого экземпляра.
• Строка RFC 9557, содержащая дату и, опционально, календарь. Если календарь не является iso8601, требуется год.
• Объект, содержащий следующие свойства (в порядке, в котором они извлекаются и проверяются):

  calendar Необязательно

  Строка, соответствующая свойству calendarId. По умолчанию используется "iso8601". Все остальные свойства интерпретируются в этой календарной системе (в отличие от конструктора Temporal.PlainMonthDay(), который интерпретирует значения в календарной системе ISO). Список часто поддерживаемых типов календарей см. в разделе Intl.supportedValuesOf().

  day

  Целое число, соответствующее свойству day. Должно быть положительным независимо от опции overflow.

  era и eraYear

  Строка и целое число, которые можно использовать вместо year. См. era и eraYear в PlainDate. Используются только в том случае, если календарная система имеет эры. era и eraYear должны быть предоставлены одновременно. Если указано month, необходимо предоставить по крайней мере одно из eraYear (вместе с era) или year. Если предоставлены все era, eraYear и year, они должны быть согласованы.

  month

  Положительное целое число, которое можно использовать вместо monthCode. См. month в PlainDate. Должно быть положительным независимо от опции overflow. Если указано month, а календарь не является iso8601, то также должно быть указано year (или eraYear вместе с era в качестве замены), поскольку один и тот же month может быть сопоставлен нескольким возможным значениям monthCode в разные годы. Необходимо указать хотя бы один из month или monthCode. Если предоставлены оба month и monthCode, они должны быть согласованы.

  monthCode

  Соответствует свойству monthCode. Необходимо указать хотя бы один из month или monthCode. Если предоставлены оба month и monthCode, они должны быть согласованы.

  year

  Целое число, используемое для устранения неоднозначности month, если оно предоставлено, поскольку для некоторых календарей одно и то же month может означать разные monthCode в разные годы. См. year в PlainDate. Если год предоставлен, то опция overflow проверяет месяц-день в данном году, а не в любом. Если указано month, необходимо предоставить по крайней мере один из eraYear (вместе с era) или year. Если предоставлены все era, eraYear и year, они должны быть согласованы.

options Необязательно

Объект, содержащий следующее свойство:

overflow Необязательно

Строка, определяющая поведение, когда компонент даты выходит за пределы диапазона (при использовании объекта info). Возможные значения:

"constrain" (по умолчанию)

Компонент даты ограничивается допустимым диапазоном.

"reject"

Генерируется RangeError, если компонент даты выходит за пределы диапазона.

Возвращаемое значение

Новый объект Temporal.PlainMonthDay, представляющий месяц и день, указанные info в указанном calendar.

Каждый PlainMonthDay внутренне хранит полную дату ISO 8601, которая имеет тот же месяц-день в целевом календаре, что и предоставляется. Ссылочный год виден при преобразовании в строку с помощью toString(), который выводит дату ISO. Ссылочный год выбирается произвольно, но последовательно (то есть каждая пара (monthCode, day) всегда сопоставляется одному и тому же ссылочному году ISO). Он не использует год, предоставленный на входе. Вместо этого ссылочный год выбирается путем нахождения самой последней даты до 31 декабря 1972 года, которая имеет тот же месяц-день в целевом календаре, или самой ранней даты после 31 декабря 1972 года, если такая дата не существует.

Например, для календарей, производных от григорианского, ссылочный год — 1972. Для еврейского календаря ссылочный год — 1972 в григорианском календаре, но если месяц — Адар I (M05L), который является високосным месяцем, ссылочный год — 1970 (5730 в еврейском календаре), потому что следующий високосный год — 1973 (5733 в еврейском календаре), который наступает после 1972 года.

Канонизация ссылочного года гарантирует, что equals() может напрямую сравнивать базовые даты ISO без дополнительных вычислений.

Исключения

TypeError

Генерируется в одном из следующих случаев:

• info не является объектом или строкой.
• options не является объектом или undefined.
• Предоставленные свойства недостаточны для однозначного определения даты. Обычно необходимо предоставить year (или era и eraYear), month и day, либо monthCode и day.

RangeError

Генерируется в одном из следующих случаев:

• Предоставленные свойства, которые определяют один и тот же компонент, являются несогласованными.
• Предоставленные нечисловые свойства недействительны; например, если monthCode никогда не является допустимым кодом месяца в этом календаре.
• Предоставленные числовые свойства выходят за пределы диапазона, и options.overflow установлено в "reject".
• Информация не находится в представимом диапазоне, который составляет ±(10⁸ + 1) дней, или примерно ±273 972,6 года, от эпохи Unix.

Примеры

Создание PlainMonthDay из объекта

// Month code + day
const md = Temporal.PlainMonthDay.from({ monthCode: "M05", day: 2 });
console.log(md.toString()); // 05-02

// Month + day (only for ISO calendar)
const md2 = Temporal.PlainMonthDay.from({ month: 7, day: 1 });
console.log(md2.toString()); // 07-01

// Year + month + day
const md3 = Temporal.PlainMonthDay.from({ year: 2021, month: 7, day: 1 });
console.log(md3.toString()); // 07-01

// Year + month + day in a different calendar (where year is required)
const md4 = Temporal.PlainMonthDay.from({
  year: 2021,
  month: 7,
  day: 1,
  calendar: "hebrew",
});
console.log(md4.toString()); // 1972-03-16[u-ca=hebrew]

// Month code + day in a different calendar
const md5 = Temporal.PlainMonthDay.from({
  monthCode: "M05L",
  day: 1,
  calendar: "hebrew",
});
console.log(md5.toString()); // 1970-02-07[u-ca=hebrew]

Управление поведением переполнения

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

• Если комбинация year/month недействительна, month ограничивается для получения действительного monthCode в этом году.
• Если комбинация year/monthCode недействительна, выбирается другой год, чтобы сохранить monthCode как есть.
• day ограничивается в данном году-месяце для получения действительного месяца-дня.

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

// Month always out of range
const md1 = Temporal.PlainMonthDay.from({ month: 13, day: 1 });
console.log(md1.toString()); // 12-01

// Month out of range for the specific year: 5732 is not a Hebrew leap year,
// so month is clamped to 12 to resolve to a valid monthCode
const md2 = Temporal.PlainMonthDay.from({
  year: 5732,
  month: 13,
  day: 1,
  calendar: "hebrew",
});
console.log(md2.toLocaleString("en-US", { calendar: "hebrew" })); // 1 Elul
const underlyingDate = Temporal.PlainDate.from(md2.toString());
console.log(underlyingDate.year, underlyingDate.month); // 5732 12

// Month code exists but not for the specific year: 5731 is not a Hebrew leap year,
// so a different year is chosen to keep the monthCode as M05L
const md3 = Temporal.PlainMonthDay.from({
  year: 5731,
  monthCode: "M05L",
  day: 1,
  calendar: "hebrew",
});
console.log(md3.toLocaleString("en-US", { calendar: "hebrew" })); // 1 Adar I
const underlyingDate2 = Temporal.PlainDate.from(md3.toString());
console.log(underlyingDate2.year, underlyingDate2.monthCode); // 5730 M05L

// Day always out of range
const md4 = Temporal.PlainMonthDay.from({ month: 2, day: 30 });
console.log(md4.toString()); // 02-29

// Day out of range for the specific year-month
const md5 = Temporal.PlainMonthDay.from({ year: 2021, month: 2, day: 29 });
console.log(md5.toString()); // 02-28

Вы можете изменить это поведение, чтобы вместо этого генерировалась ошибка:

Temporal.PlainMonthDay.from(
  { year: 2021, month: 13, day: 1 },
  { overflow: "reject" },
);
// RangeError: date value "month" not in 1..12: 13

Спецификации

Совместимость с браузерами

См. также

• Temporal.PlainMonthDay
• Temporal.PlainMonthDay()
• Temporal.PlainMonthDay.prototype.with()