Temporal.Instant.prototype.round()

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

Syntax

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 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

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

Browser compatibility

See also

• Instant