Temporal.Instant.prototype.round()

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The round() method of Temporal.Instant instances returns a new Temporal.Instant object representing this instant rounded to the given unit.

Syntax

js
round(smallestUnit)
round(options)

Parameters

smallestUnit

A string representing the smallestUnit option. This is a convenience overload, so round(smallestUnit) is equivalent to round({ smallestUnit }), where smallestUnit is a string.

options

An object containing some or all of the following properties (in the order they are retrieved and validated):

roundingIncrement Optional

A number (truncated to an integer) representing the rounding increment in the given smallestUnit. Defaults to 1. The increment and the smallestUnit must evenly divide 24 hours; for example, 45 seconds is a divisor of 86400 seconds, and 100 minutes is a divisor of 3600 minutes. This is slightly less strict than the round() method of the other classes, which all require the increment to be a divisor of the maximum value of the unit.

roundingMode Optional

A string specifying how to round off the fractional part of smallestUnit. See Intl.NumberFormat(). Defaults to "halfExpand".

smallestUnit

A string representing the smallest unit to include in the output. The value must be one of the following: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", or their plural forms. For units larger than "nanosecond", fractional parts of the smallestUnit will be rounded according to the roundingIncrement and roundingMode settings.

Return value

A new Temporal.Instant object representing this instant rounded to the given unit, where all units smaller than smallestUnit are zeroed out.

Exceptions

RangeError

Thrown if any of the options is invalid.

Examples

Rounding off small units

js
const instant = Temporal.Instant.fromEpochMilliseconds(1000);
const roundedInstant = instant.round("second");
console.log(roundedInstant.epochMilliseconds); // 1000

const instant2 = instant.round("minute");
console.log(instant2.epochMilliseconds); // 0

Specifications

Specification
Temporal proposal
# sec-temporal.instant.prototype.round

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
round
Experimental

Legend

Tip: you can click/tap on a cell for more information.

In development. Supported in a pre-release version.
In development. Supported in a pre-release version.
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.
User must explicitly enable this feature.

See also