Temporal.PlainYearMonth.prototype.add()

Метод add() экземпляров Temporal.PlainYearMonth возвращает новый объект Temporal.PlainYearMonth, представляющий данный год-месяц, сдвинутый вперед на заданную продолжительность (в форме, конвертируемой с помощью Temporal.Duration.from()).

Синтаксис

add(duration)
add(duration, options)

Параметры

duration

Строка, объект или экземпляр Temporal.Duration, представляющий продолжительность, которую нужно добавить к этому году-месяцу. Он преобразуется в объект Temporal.Duration с использованием того же алгоритма, что и Temporal.Duration.from().

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

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

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

Строка, указывающая поведение, когда компонент даты находится вне допустимого диапазона. Возможные значения:

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

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

"reject"

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

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

Новый объект Temporal.PlainYearMonth, представляющий год-месяц, указанный исходным PlainYearMonth, плюс продолжительность.

Исключения

RangeError

Генерируется, если результат не входит в представимый диапазон, который составляет ±(10⁸ + 1) дней, или около ±273 972,6 лет, от эпохи Unix.

Описание

Обработка duration происходит следующим образом:

• Сдвигаемся вперед на количество лет, сохраняя monthCode тем же. Если monthCode недопустим в результирующем году (невозможно для григорианского календаря и ISO 8601, но возможно для календарей с високосными месяцами), мы корректируем его на основе опции overflow: для constrain мы выбираем другой месяц в соответствии с культурными обычаями пользователей этого календаря. Например, поскольку високосный месяц обычно считается дубликатом другого месяца, мы можем выбрать месяц, дубликатом которого он является.
• Сдвигаемся вперед на количество месяцев, корректируя год при необходимости.
• Для всех единиц измерения, меньших months (недели, дни, часы, минуты, секунды, миллисекунды, микросекунды, наносекунды), они преобразуются в количество дней. Все обычно поддерживаемые календари используют недели фиксированной длины, поэтому количество недель просто преобразуется в количество дней. Если правило более сложное, мы можем применить подход, аналогичный сдвигу месяцев. Затем мы сдвигаемся вперед на это количество дней, начиная с первого дня месяца, корректируя месяц и год при необходимости. Таким образом, продолжительность, меньшая длины текущего месяца, не имеет эффекта.

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

Добавление продолжительности эквивалентно вычитанию её отрицания.

Примеры

Добавление продолжительности в календаре ISO 8601

const start = Temporal.PlainYearMonth.from("2021-01");
const end = start.add({ years: 1, months: 2, weeks: 3, days: 4 });
console.log(end.toString()); // 2022-03

const end2 = start.add({ years: -1, months: -2, weeks: -3, days: -4 });
console.log(end2.toString()); // 2019-11

const distance = Temporal.PlainYearMonth.from("2020-01").until("2021-01"); // 366 days
const end3 = start.add(distance);
console.log(end3.toString()); // 2022-01

Добавление продолжительности в календаре, отличном от ISO

const start = Temporal.PlainYearMonth.from("2021-02-01[u-ca=chinese]");
console.log(start.toLocaleString("en-US", { calendar: "chinese" })); // 12/2020
console.log(start.toString()); // 2021-01-13[u-ca=chinese]
const end = start.add({ months: 1 });
console.log(end.toLocaleString("en-US", { calendar: "chinese" })); // 1/2021
console.log(end.toString()); // 2021-02-12[u-ca=chinese]

// Adding an extra day has no effect at all
const end2 = start.add({ months: 1, days: 1 });
console.log(end2.toLocaleString("en-US", { calendar: "chinese" })); // 1/2021
// The reference day doesn't change, because it's always the first day of the Chinese month
console.log(end2.toString()); // 2021-02-12[u-ca=chinese]

// Start in a leap month
const start2 = Temporal.PlainYearMonth.from({
  year: 5730,
  monthCode: "M05L",
  calendar: "hebrew",
});
console.log(start2.toLocaleString("en-US", { calendar: "hebrew" })); // Adar I 5730
// End in another leap month
const end3 = start2.add({ years: 3 });
console.log(end3.toLocaleString("en-US", { calendar: "hebrew" })); // Adar I 5733

Добавление продолжительности с переполнением

Если мы сдвигаемся на несколько лет, и соответствующий месяц недопустим в этом году, мы корректируем месяц на основе опции overflow.

// Start in a leap month
const start = Temporal.PlainYearMonth.from({
  year: 5730,
  monthCode: "M05L",
  calendar: "hebrew",
});
// Hebrew leap years occur every 2 or 3 years, and 5731 is not a leap year
const end = start.add({ years: 1 });
console.log(end.toLocaleString("en-US", { calendar: "hebrew" })); // Adar 5731
console.log(end.monthCode); // M06
console.log(end.toString()); // 1971-02-26[u-ca=hebrew]

// Any further month additions are based on the clamped year-month
const end2 = start.add({ years: 1, months: 2 });
console.log(end2.monthCode); // M08
console.log(end2.toString()); // 1971-04-26[u-ca=hebrew]

// Compare with the same addition in a different order that results in no overflow:
const end3 = start.add({ months: 2 }).add({ years: 1 });
console.log(end3.monthCode); // M07
console.log(end3.toString()); // 1971-03-27[u-ca=hebrew]

Обратите внимание, что следующее не является переполнением, поскольку год может просто увеличиться:

const start = Temporal.PlainYearMonth.from("2021-01");
const end = start.add({ months: 100 });
console.log(end.toString()); // 2029-05

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

const start = Temporal.PlainYearMonth.from({
  year: 5730,
  monthCode: "M05L",
  calendar: "hebrew",
});
const end = start.add({ years: 1 }, { overflow: "reject" }); // RangeError: invalid "monthCode" calendar field: M05L

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

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

Смотрите также

• Temporal.PlainYearMonth
• Temporal.Duration
• Temporal.PlainYearMonth.prototype.subtract()