Temporal.ZonedDateTime.prototype.since()

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

Этот метод this - other. Для other - this используйте метод until().

Синтаксис

since(other)
since(other, options)

Параметры

other

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

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

Объект, содержащий параметры для Temporal.Duration.prototype.round(), который включает largestUnit, roundingIncrement, roundingMode и smallestUnit. largestUnit и smallestUnit принимают все возможные единицы. Для largestUnit значение по умолчанию "auto" означает "hours" или smallestUnit, в зависимости от того, что больше. Для smallestUnit значение по умолчанию равно "nanoseconds". Текущая дата используется как параметр relativeTo. Обратите внимание, что использование единиц, больших чем "hours", может сделать продолжительность несовместимой с другими календарями, датами или часовыми поясами.

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

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

Исключения

RangeError

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

• other имеет календарь, отличный от this.
• Любой из параметров недействителен.
• other имеет часовой пояс, отличный от this, и largestUnit имеет значение "days" или выше.

Описание

Возвращаемая продолжительность является "гибридной". Это означает, что часть даты продолжительности представляет полные календарные дни, как возвращал бы Temporal.PlainDateTime.prototype.since(), в то время как часть времени представляет реальное прошедшее время, как возвращал бы Temporal.Instant.prototype.since(). Этот подход "гибридной продолжительности" автоматически корректируется для летнего времени и соответствует широко принятым отраслевым стандартам, таким как RFC 5545 (iCalendar). См. примеры ниже.

Примеры

Смены смещения

Когда происходят смены, день может не иметь ровно 24 часов.

const start = Temporal.ZonedDateTime.from(
  "2024-11-03T01:00:00-04:00[America/New_York]",
);
const end = Temporal.ZonedDateTime.from(
  "2024-11-04T01:00:00-05:00[America/New_York]",
);
console.log(end.since(start).toString()); // PT25H
console.log(end.since(start, { largestUnit: "days" }).toString()); // PT1D

const start2 = Temporal.ZonedDateTime.from(
  "2024-03-10T01:00:00-05:00[America/New_York]",
);
const end2 = Temporal.ZonedDateTime.from(
  "2024-03-11T01:00:00-04:00[America/New_York]",
);
console.log(end2.since(start2).toString()); // PT23H
console.log(end2.since(start2, { largestUnit: "days" }).toString()); // PT1D

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

Разные часовые пояса

Часть времени возвращаемой продолжительности полностью основана на моментах времени и не зависит от часовых поясов. Однако, если вы хотите включить любые единицы даты, такие как day, то начало и конец должны находиться в одном часовом поясе.

const start = Temporal.ZonedDateTime.from(
  "2024-11-03T01:00:00-04:00[America/New_York]",
);
// Peru does not use DST so its offset remains -05:00 year-round
const end = Temporal.ZonedDateTime.from(
  "2024-11-04T01:00:00-05:00[America/Lima]",
);

end.since(start); // PT25H
end.since(start, { largestUnit: "days" }); // RangeError: time zones "America/Lima" and "America/New_York" aren't compatible

end.withTimeZone("America/New_York").since(start, { largestUnit: "days" }); // P1D
end.since(start.withTimeZone("America/Lima"), { largestUnit: "days" }); // P1D1H

Для получения дополнительных примеров использования since(), особенно с округлением, см. Temporal.PlainDate.prototype.since() и Temporal.PlainTime.prototype.since().

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

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

См. также

• Temporal.ZonedDateTime
• Temporal.Duration
• Temporal.ZonedDateTime.prototype.add()
• Temporal.ZonedDateTime.prototype.subtract()
• Temporal.ZonedDateTime.prototype.until()