Temporal.Instant.prototype.valueOf()

The valueOf() method of {{jsxref("Temporal.Instant")}} instances throws a {{jsxref("TypeError")}}, which prevents Temporal.Instant instances from being implicitly converted to primitives when used in arithmetic or comparison operations.

Syntax#

valueOf()

Parameters#

None.

Return value#

None.

Exceptions#

• {{jsxref("TypeError")}}
• : Always thrown.

Description#

Because both primitive conversion and number conversion call valueOf() before toString(), if valueOf() is absent, then an expression like instant1 > instant2 would implicitly compare them as strings, which may have unexpected results. By throwing a TypeError, Temporal.Instant instances prevent such implicit conversions. You need to explicitly convert them to numbers using {{jsxref("Temporal/Instant/epochNanoseconds", "Temporal.Instant.prototype.epochNanoseconds")}}, or use the {{jsxref("Temporal/Instant/compare", "Temporal.Instant.compare()")}} static method to compare them.

Examples#

Arithmetic and comparison operations on Temporal.Instant#

All arithmetic and comparison operations on Temporal.Instant instances should use the dedicated methods or convert them to primitives explicitly.

const instant1 = Temporal.Instant.fromEpochMilliseconds(0);
const instant2 = Temporal.Instant.fromEpochMilliseconds(1000);
instant1 > instant2; // TypeError: can't convert Instant to primitive type
instant1.epochNanoseconds > instant2.epochNanoseconds; // false
Temporal.Instant.compare(instant1, instant2); // -1

instant2 - instant1; // TypeError: can't convert Instant to primitive type
instant2.since(instant1).toString(); // "PT1S"

Specifications#

{{Specifications}}

Browser compatibility#

{{Compat}}

See also#

• {{jsxref("Temporal.Instant")}}
• {{jsxref("Temporal/Instant/toString", "Temporal.Instant.prototype.toString()")}}
• {{jsxref("Temporal/Instant/toJSON", "Temporal.Instant.prototype.toJSON()")}}
• {{jsxref("Temporal/Instant/toLocaleString", "Temporal.Instant.prototype.toLocaleString()")}}