Temporal.Duration.prototype.round()

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

Синтаксис

round(smallestUnit)
round(options)

Параметры

smallestUnit

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

options

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

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

Любая из темпоральных единиц: "years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds", "microseconds", "nanoseconds", или их формы единственного числа, или значение "auto", которое означает наибольший ненулевой компонент этой продолжительности или smallestUnit, в зависимости от того, что больше. По умолчанию используется "auto". Результат не будет содержать единиц, больших, чем эта; например, если наибольшая единица — "minutes", то "1 hour 30 minutes" станет "90 minutes".

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

Дата(время) с часовым поясом или без, которая предоставляет информацию о времени и календаре для разрешения календарных продолжительностей (см. ссылку для общего толкования этой опции). Требуется, если либо this, либо other является календарной продолжительностью, либо smallestUnit является календарной единицей.

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

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

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

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

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

Любая из темпоральных единиц: "years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds", "microseconds", "nanoseconds", или их формы единственного числа. По умолчанию используется "nanoseconds". Для единиц, больших, чем "nanoseconds", дробные части smallestUnit будут округлены в соответствии с настройками roundingIncrement и roundingMode. Должно быть меньше или равно largestUnit. Должен быть предоставлен хотя бы один из smallestUnit и largestUnit.

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

Новый объект Temporal.Duration, где наибольшая единица не превышает опции largestUnit, а наименьшая единица не меньше опции smallestUnit. Дробные части smallestUnit округляются в соответствии с настройками roundingIncrement и roundingMode.

Исключения

RangeError

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

Описание

Метод round() выполняет две операции: округление и балансировку. Он делает следующее:

1. Он гарантирует, что продолжительность сбалансирована. Если компонент превышает свой предпочтительный максимум (24 часа в сутки, 60 минут в час и т. д.), избыток переносится на следующую большую единицу, пока мы не достигнем largestUnit. Например, "24 hours 90 minutes" становится "25 hours 30 minutes", если largestUnit — это "auto", и "1 day 1 hour 30 minutes", если largestUnit — это "days".
2. Для всех компонентов, больших, чем largestUnit, они переносятся вниз в largestUnit; например, "2 hours 30 minutes" становится "150 minutes", если largestUnit — это "minutes".
3. Для всех компонентов, меньших, чем smallestUnit, они переносятся вверх в smallestUnit как дробная часть, а затем округляются в соответствии с настройками roundingIncrement и roundingMode. Например, "1 hour 30 minutes" становится "1.5 hours", если smallestUnit — это "hours", а затем округляется до "2 hours" с использованием настроек по умолчанию.

Календарные единицы имеют неравномерную длину. Их длина определяется относительно начальной точки. Например, продолжительность "2 years" в григорианском календаре может составлять 730 или 731 день, в зависимости от того, проходит ли она через високосный год. При округлении до календарной единицы мы сначала получаем точную дату и время, представленные relativeTo + duration, затем округляем их вниз и вверх в соответствии с smallestUnit и roundingIncrement, чтобы получить двух кандидатов. Затем мы выбираем кандидата в соответствии с настройкой roundingMode и, наконец, вычитаем relativeTo, чтобы получить окончательную продолжительность.

Примеры

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

const duration = Temporal.Duration.from({ hours: 1, minutes: 30, seconds: 15 });
const roundedDuration = duration.round("minutes");
console.log(roundedDuration.toString()); // "PT1H30M"

Избегание более крупных единиц

const duration = Temporal.Duration.from({
  days: 3,
  hours: 1,
  minutes: 41,
  seconds: 5,
});
const roundedDuration = duration.round({ largestUnit: "hours" });
console.log(
  `Time spent on this problem: ${roundedDuration.toLocaleString("en-US", { style: "digital" })}`,
);
// Time spent on this problem: 73:41:05

Округление до целого числа часов

const duration = Temporal.Duration.from({ days: 1, hours: 1, minutes: 30 });
const roundedDuration = duration.round({
  largestUnit: "hours",
  smallestUnit: "hours",
  roundingMode: "floor",
});
console.log(roundedDuration.hours); // 25

Округление с приращением 15 минут

const duration = Temporal.Duration.from({ hours: 1, minutes: 17 });
const roundedDuration = duration.round({
  smallestUnit: "minutes",
  roundingIncrement: 15,
});
console.log(
  `The queue will take approximately ${roundedDuration.toLocaleString("en-US")}`,
);
// The queue will take approximately 1 hr, 15 min

Разрешение календарных продолжительностей

Если либо начальная продолжительность, либо наибольшая/наименьшая единица содержит календарную единицу, вы должны предоставить опцию relativeTo для разрешения календарных продолжительностей.

const duration = Temporal.Duration.from({ months: 1, days: 1, hours: 1 });
const roundedDuration = duration.round({
  largestUnit: "days",
  smallestUnit: "days",
  relativeTo: Temporal.PlainDateTime.from("2022-01-01"),
});
console.log(roundedDuration); // "P32D"

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

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

См. также

• Temporal.Duration
• Temporal.Duration.prototype.total()