Temporal.ZonedDateTime.compare()
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 Temporal.ZonedDateTime.compare() static method returns a number (-1, 0, or 1) indicating whether the first date-time comes before, is the same as, or comes after the second date-time. It is equivalent to comparing the epochNanoseconds of the two date-times.
Syntax
Temporal.ZonedDateTime.compare(dateTime1, dateTime2)
Parameters
dateTime1-
A string, an object, or a
Temporal.ZonedDateTimeinstance representing the first date-time to compare. It is converted to aTemporal.ZonedDateTimeobject using the same algorithm asTemporal.ZonedDateTime.from(). dateTime2-
The second date-time to compare, converted to a
Temporal.ZonedDateTimeobject using the same algorithm asdateTime1.
Return value
Returns -1 if dateTime1 comes before dateTime2, 0 if they are the same, and 1 if dateTime1 comes after dateTime2. They are compared by their underlying instant values, ignoring their calendars or time zones.
Examples
Using Temporal.ZonedDateTime.compare()
const dt1 = Temporal.ZonedDateTime.from("2021-08-01T01:00:00[Europe/London]");
const dt2 = Temporal.ZonedDateTime.from("2021-08-02T00:00:00[Europe/London]");
console.log(Temporal.ZonedDateTime.compare(dt1, dt2)); // -1
const dt3 = Temporal.ZonedDateTime.from("2021-08-01T00:00:00[Europe/London]");
console.log(Temporal.ZonedDateTime.compare(dt1, dt3)); // 1
Sorting an array of date-times
The purpose of this compare() function is to act as a comparator to be passed to Array.prototype.sort() and related functions.
const dateTimes = [
Temporal.ZonedDateTime.from("2021-08-01T00:00:00[America/New_York]"),
Temporal.ZonedDateTime.from("2021-08-01T00:00:00[Asia/Hong_Kong]"),
Temporal.ZonedDateTime.from("2021-08-01T00:00:00[Europe/London]"),
];
dateTimes.sort(Temporal.ZonedDateTime.compare);
console.log(dateTimes.map((d) => d.toString()));
// [ "2021-08-01T00:00:00+08:00[Asia/Hong_Kong]", "2021-08-01T00:00:00+01:00[Europe/London]", "2021-08-01T00:00:00-04:00[America/New_York]" ]
Note that they are compared by their instant values. In the very rare case where you want to compare them by their wall-clock times, convert them to PlainDateTime first.
const dateTimes = [
Temporal.ZonedDateTime.from("2021-08-01T00:00:00[America/New_York]"),
Temporal.ZonedDateTime.from("2021-08-01T00:00:00[Asia/Hong_Kong]"),
Temporal.ZonedDateTime.from("2021-08-01T00:00:00[Europe/London]"),
];
dateTimes.sort((a, b) =>
Temporal.PlainDateTime.compare(a.toPlainDateTime(), b.toPlainDateTime()),
);
console.log(dateTimes.map((d) => d.toString()));
// [ "2021-08-01T00:00:00-04:00[America/New_York]", "2021-08-01T00:00:00+08:00[Asia/Hong_Kong]", "2021-08-01T00:00:00+01:00[Europe/London]" ]
Specifications
| Specification |
|---|
| Temporal # sec-temporal.zoneddatetime.compare |
Browser compatibility
Loading…