Temporal.ZonedDateTime.prototype.round()

Метод round() экземпляров Temporal.ZonedDateTime возвращает новый объект Temporal.ZonedDateTime, представляющий эту дату-время, округленную до заданной единицы.

Синтаксис

round(smallestUnit)
round(options)

Параметры

smallestUnit

Строка, представляющая опцию smallestUnit. Это удобная перегрузка, поэтому round(smallestUnit) эквивалентно round({ smallestUnit }), где smallestUnit является строкой.

options

Объект, содержащий некоторые или все из следующих свойств (в порядке их получения и проверки):

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

Число (усеченное до целого), представляющее приращение округления в заданной smallestUnit. По умолчанию используется 1. Для всех значений smallestUnit, кроме "day", приращение должно быть делителем максимального значения единицы; например, если единица — часы, приращение должно быть делителем 24, но не 24; это означает, что оно может быть 1, 2, 3, 4, 6, 8 или 12. Для "day" приращение должно быть 1.

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

Строка, указывающая, как округлять дробную часть smallestUnit. См. Intl.NumberFormat(). По умолчанию используется "halfExpand".

smallestUnit

Строка, представляющая наименьшую единицу, которую следует включить в вывод. Значение должно быть одним из следующих: "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", или их формы множественного числа. Для единиц, больших чем "nanosecond", дробные части smallestUnit будут округлены в соответствии с настройками roundingIncrement и roundingMode.

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

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

Если smallestUnit равно "day", возвращаемая дата-время будет началом дня этой даты или следующего дня, в зависимости от roundingMode и расстояния до этих двух моментов. В противном случае округление сначала выполняется над его PlainDateTime (так же, как Temporal.PlainDateTime.prototype.round()), а затем повторно интерпретируется в том же часовом поясе, с disambiguation: "compatible", offset: "prefer". См. неоднозначность и пробелы при переходе от местного времени к времени UTC и неоднозначность смещения.

Исключения

RangeError

Генерируется, если какой-либо из параметров неверен.

Примеры

Округление меньших единиц

const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:34:56.123456789[America/New_York]",
);
const nearestMillisecond = zdt.round("millisecond");
console.log(nearestMillisecond.toString()); // 2021-07-01T12:34:56.123-04:00[America/New_York]

const nearestHalfHour = zdt.round({
  smallestUnit: "minute",
  roundingIncrement: 30,
});
console.log(nearestHalfHour.toString()); // 2021-07-01T12:30:00-04:00[America/New_York]

const nextDay = zdt.round({ smallestUnit: "day", roundingMode: "ceil" });
console.log(nextDay.toString()); // 2021-07-02T00:00:00-04:00[America/New_York]

Неоднозначность после округления

Возможно, что округленная дата-время является неоднозначной в заданном часовом поясе. Неоднозначность всегда разрешается с помощью disambiguation: "compatible", offset: "prefer". Вот краткий пример:

const zdt = Temporal.ZonedDateTime.from(
  "2024-03-10T01:00:00-05:00[America/New_York]",
);
const rounded = zdt.round({ smallestUnit: "hour", roundingIncrement: 2 });
// The result is supposed to be 2024-03-10T02:00:00-05:00[America/New_York],
// but this time does not exist. `disambiguation: "compatible"` tells us to move
// forward by 1 hour.
console.log(rounded.toString()); // 2024-03-10T03:00:00-04:00[America/New_York]

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

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

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

• Temporal.ZonedDateTime