Temporal.PlainDateTime.compare()
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
The Temporal.PlainDateTime.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. Equivalent to first comparing their dates, then comparing their times if the dates are the same.
Syntax
Temporal.PlainDateTime.compare(dateTime1, dateTime2)
Parameters
dateTime1-
A string, an object, or a
Temporal.PlainDateTimeinstance representing the first date-time to compare. It is converted to aTemporal.PlainDateTimeobject using the same algorithm asTemporal.PlainDateTime.from(). dateTime2-
The second date-time to compare, converted to a
Temporal.PlainDateTimeobject 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 date and time values, ignoring their calendars.
Examples
Using Temporal.PlainDateTime.compare()
const dt1 = Temporal.PlainDateTime.from("2021-08-01T01:00:00");
const dt2 = Temporal.PlainDateTime.from("2021-08-02T00:00:00");
console.log(Temporal.PlainDateTime.compare(dt1, dt2)); // -1
const dt3 = Temporal.PlainDateTime.from("2021-08-01T00:00:00");
console.log(Temporal.PlainDateTime.compare(dt1, dt3)); // 1
Comparing dates in different calendars
const dt1 = Temporal.PlainDateTime.from({ year: 2021, month: 8, day: 1 });
const dt2 = Temporal.PlainDateTime.from({
year: 2021,
month: 8,
day: 1,
calendar: "islamic-umalqura",
});
const dt3 = Temporal.PlainDateTime.from({
year: 2021,
month: 8,
day: 1,
calendar: "hebrew",
});
console.log(dt1.toString()); // "2021-08-01T00:00:00"
console.log(dt2.toString()); // "2582-12-17T00:00:00[u-ca=islamic-umalqura]"
console.log(dt3.toString()); // "-001739-04-06T00:00:00[u-ca=hebrew]"
console.log(Temporal.PlainDateTime.compare(dt1, dt2)); // -1
console.log(Temporal.PlainDateTime.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.PlainDateTime.from("2021-08-01"),
Temporal.PlainDateTime.from("2021-08-02"),
Temporal.PlainDateTime.from("2021-08-01T01:00:00"),
];
dateTimes.sort(Temporal.PlainDateTime.compare);
console.log(dateTimes.map((d) => d.toString()));
// [ "2021-08-01T00:00:00", "2021-08-01T01:00:00", "2021-08-02T00:00:00" ]
Specifications
| Specification |
|---|
| Temporal # sec-temporal.plaindatetime.compare |
Browser compatibility
| desktop | mobile | server | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
compare
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- No support
- No support
- See implementation notes.