Temporal.PlainDate.prototype.add()

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

Синтаксис

add(duration)
add(duration, options)

Параметры

duration

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

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

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

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

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

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

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

"reject"

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

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

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

Исключения

RangeError

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

Описание

duration обрабатывается следующим образом:

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

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

Примеры

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

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

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

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

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

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

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

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

const start = Temporal.PlainDate.from("2021-01-31");
const end = start.add({ months: 1 });
console.log(end.toString()); // 2021-02-28

// Any further day additions are based on the clamped month-day:
const end2 = start.add({ months: 1, days: 31 });
console.log(end2.toString()); // 2021-03-31

// Compare with the same addition in a different order that results in no overflow:
const end3 = start.add({ days: 31 }).add({ months: 1 });
console.log(end3.toString()); // 2021-04-03

Переполнение также может произойти для месяца в календарях, где разные годы имеют разное количество месяцев (обычно из-за високосных месяцев).

const start = Temporal.PlainDate.from("2023-04-01[u-ca=chinese]");
console.log(start.toLocaleString("en-US", { calendar: "chinese" })); // 2bis/11/2023; "bis" means leap month
const end = start.add({ years: 1 });
console.log(end.toLocaleString("en-US", { calendar: "chinese" })); // 3/11/2024

// Compare:
const start = Temporal.PlainDate.from("2023-04-30[u-ca=chinese]");
console.log(start.toLocaleString("en-US", { calendar: "chinese" })); // 3/11/2023
const end = start.add({ years: 1 });
console.log(end.toLocaleString("en-US", { calendar: "chinese" })); // 3/11/2024; same day as above!

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

const start = Temporal.PlainDate.from("2021-01-01");
const end = start.add({ days: 100 });
console.log(end.toString()); // 2021-04-11

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

const start = Temporal.PlainDate.from("2021-01-31");
const end = start.add({ months: 1 }, { overflow: "reject" }); // RangeError: date value "day" not in 1..28: 31

const start = Temporal.PlainDate.from("2023-04-01[u-ca=chinese]");
const end = start.add({ years: 1 }, { overflow: "reject" }); // RangeError: invalid "monthCode" calendar field: M02L

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

Дробные части дня игнорируются.

const start = Temporal.PlainDate.from("2021-01-01");
const end = start.add({ hours: 25 }); // Same as adding 1 day
console.log(end.toString()); // 2021-01-02

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

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

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

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