Temporal.PlainDateTime.compare() — Methode · JavaScript-Referenz

Signatur

Temporal.PlainDateTime.compare(dateTime1, dateTime2)

Beschreibung

Temporal.PlainDateTime.compare() ist eine statische Methode. Sie vergleicht zwei Datum-Uhrzeit-Werte ohne Zeitzone chronologisch: zuerst das Datum (Jahr, Monat, Tag), danach die Uhrzeit bis auf die Nanosekunde. Liegt dateTime1 vor dateTime2, kommt -1 zurück, bei Gleichheit 0 und wenn dateTime1 später liegt, 1.

Die Signatur passt genau zu dem, was Array.prototype.sort() als Vergleichsfunktion erwartet. Du kannst Temporal.PlainDateTime.compare also direkt übergeben, ohne eine eigene Pfeilfunktion zu schreiben. Das ist der typische Weg, um Termine, Logeinträge oder Buchungen chronologisch zu sortieren.

Als Argumente gehen nicht nur Temporal.PlainDateTime-Instanzen. Erlaubt sind alles, was auch Temporal.PlainDateTime.from() annimmt: RFC-9557-/ISO-8601-Zeichenketten wie "2024-03-15T09:30" und Objekte mit Feldern wie { year, month, day, hour }. Solche Werte werden vor dem Vergleich intern umgewandelt.

Wichtig: Der Kalender wird ignoriert. Verglichen wird nur der zugrunde liegende ISO-Zeitpunkt. Brauchst du eine strenge Gleichheit, bei der auch der Kalender übereinstimmen muss, nimm Temporal.PlainDateTime.prototype.equals().

Parameter

Name	Typ	Default	Beschreibung
$dateTime1 Pflicht	Temporal.PlainDateTime \| string \| object		Erster Wert. Zeichenketten und Objekte werden wie bei `Temporal.PlainDateTime.from()` umgewandelt.
$dateTime2 Pflicht	Temporal.PlainDateTime \| string \| object		Zweiter Wert, mit dem `dateTime1` verglichen wird. Er wird genauso umgewandelt.

Rückgabewert

Typ

-1 | 0 | 1

Beschreibung

-1, wenn dateTime1 früher liegt, 0 bei gleichem Datum und gleicher Uhrzeit, 1, wenn dateTime1 später liegt.

Beispiele

Zwei Zeitpunkte vergleichen

const start = Temporal.PlainDateTime.from('2024-03-15T09:30');
const ende = Temporal.PlainDateTime.from('2024-03-15T17:00');

console.log(Temporal.PlainDateTime.compare(start, ende));
console.log(Temporal.PlainDateTime.compare(ende, start));
console.log(Temporal.PlainDateTime.compare(start, '2024-03-15T09:30:00'));

-1 1 0

Termine chronologisch sortieren

const termine = [
  Temporal.PlainDateTime.from('2024-05-02T14:00'),
  Temporal.PlainDateTime.from('2024-04-30T08:15'),
  Temporal.PlainDateTime.from('2024-05-02T09:45'),
];

// compare direkt als Vergleichsfunktion übergeben
termine.sort(Temporal.PlainDateTime.compare);
console.log(termine.map(String));

// absteigend: neueste zuerst
termine.sort((a, b) => Temporal.PlainDateTime.compare(b, a));
console.log(termine[0].toString());

[ '2024-04-30T08:15:00', '2024-05-02T09:45:00', '2024-05-02T14:00:00' ] 2024-05-02T14:00:00

Frist prüfen mit Objekt-Eingabe

const frist = { year: 2024, month: 6, day: 30, hour: 23, minute: 59 };

const istRechtzeitig = (abgabe) =>
  Temporal.PlainDateTime.compare(abgabe, frist) <= 0;

console.log(istRechtzeitig('2024-06-30T22:10'));
console.log(istRechtzeitig('2024-07-01T00:05'));

true false

// Wichtig · Fallstricke

Kalender bleibt unberücksichtigt: Zwei Werte mit gleichem ISO-Zeitpunkt, aber verschiedenem Kalender (z. B. iso8601 und japanese) ergeben 0. equals() liefert für dieselben Werte dagegen false.
Keine Zeitzone: PlainDateTime steht für eine Uhrzeit ohne Zeitzone, wie man sie „an der Wand“ abliest. Für echte Zeitpunkte über Zeitzonen oder Sommerzeit-Wechsel hinweg sind Temporal.ZonedDateTime.compare() oder Temporal.Instant.compare() die richtige Wahl.
Fehler: Ungültige Zeichenketten lösen einen RangeError aus, z. B. "2024-13-01T10:00" oder ein UTC-Kennzeichen Z wie in "2024-01-01T10:00Z". Eine ungültige Eingabe wie null führt zu einem TypeError. Ein Versatz wie +02:00 in der Zeichenkette wird stillschweigend ignoriert.
Nicht mit </> vergleichen: valueOf() wirft bei Temporal-Objekten absichtlich einen TypeError. Relationale Operatoren funktionieren deshalb nicht, nutze immer compare().
Kompatibilität: Temporal gibt es erst in neueren Browsern (Firefox 139+, Chromium 144+). In älteren Umgebungen und derzeit in Safari brauchst du ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainDateTime Temporal.PlainDateTime.prototype.equals() Temporal.PlainDateTime.from() Temporal.PlainDate.compare() Temporal.ZonedDateTime.compare() Array.prototype.sort()