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

Signatur

Temporal.Duration.compare(duration1, duration2, options)

Beschreibung

Temporal.Duration.compare() ist eine statische Methode. Sie vergleicht zwei Zeitspannen nach ihrer tatsächlichen Länge, nicht nach ihrer Schreibweise. PT90M und PT1H30M gelten also als gleich lang. Da Temporal.Duration keine equals()-Methode hat, prüfst du mit compare() auch auf Gleichheit.

Die Rückgabewerte passen genau zu dem, was eine Vergleichsfunktion liefern muss. Du kannst die Methode deshalb direkt an Array.prototype.sort() übergeben, zum Beispiel um Laufzeiten, Timeouts oder Fahrtdauern zu sortieren. Als Argumente sind Temporal.Duration-Objekte, ISO-8601-Zeichenketten wie "PT2H" und einfache Objekte wie { hours: 2 } erlaubt.

Enthält eine der beiden Dauern Kalendereinheiten (Jahre, Monate oder Wochen), musst du die Option relativeTo angeben. Ein Monat ist nicht immer gleich lang, deshalb braucht die Methode ein Startdatum. Ohne relativeTo rechnet sie einen Tag als genau 24 Stunden. Übergibst du ein Temporal.ZonedDateTime, beachtet sie Zeitzonen-Übergänge wie die Sommerzeitumstellung.

Parameter

Name	Typ	Default	Beschreibung
$duration1 Pflicht	Temporal.Duration \| string \| Object		Erste Dauer. Wird wie bei `Temporal.Duration.from()` umgewandelt.
$duration2 Pflicht	Temporal.Duration \| string \| Object		Zweite Dauer, mit der die erste verglichen wird.
$options	Object	undefined	Optionsobjekt mit der Eigenschaft `relativeTo`. Erlaubt sind `Temporal.ZonedDateTime`, `Temporal.PlainDate`, `Temporal.PlainDateTime` sowie passende Zeichenketten oder Objekte. Pflicht, sobald Jahre, Monate oder Wochen vorkommen.

Beispiele

Gleichheit trotz anderer Schreibweise

const a = Temporal.Duration.from({ hours: 1, minutes: 30 });
const b = Temporal.Duration.from('PT90M');

console.log(Temporal.Duration.compare(a, b));
console.log(Temporal.Duration.compare('PT45M', 'PT1H'));

0 -1

Laufzeiten sortieren

const laufzeiten = ['PT2H', 'PT45M', 'P1DT1H', 'PT1H30M']
  .map((d) => Temporal.Duration.from(d));

laufzeiten.sort(Temporal.Duration.compare);
console.log(laufzeiten.map(String));

["PT45M", "PT1H30M", "PT2H", "P1DT1H"]

Monate vergleichen mit relativeTo

const monat = { months: 1 };
const tage = { days: 30 };

// Februar 2024 hat 29 Tage
console.log(Temporal.Duration.compare(monat, tage, {
  relativeTo: Temporal.PlainDate.from('2024-02-01'),
}));

// Januar hat 31 Tage
console.log(Temporal.Duration.compare(monat, tage, {
  relativeTo: '2024-01-01',
}));

try {
  Temporal.Duration.compare(monat, tage);
} catch (err) {
  console.log(err.name);
}

-1 1 RangeError

Sommerzeitumstellung berücksichtigen

const start = Temporal.ZonedDateTime.from('2024-03-31T00:00[Europe/Berlin]');

// Ohne relativeTo: 1 Tag = 24 Stunden
console.log(Temporal.Duration.compare({ days: 1 }, { hours: 24 }));

// Am 31.03.2024 hat der Tag in Berlin nur 23 Stunden
console.log(Temporal.Duration.compare({ days: 1 }, { hours: 24 }, { relativeTo: start }));

0 -1

// Wichtig · Fallstricke

RangeError ohne relativeTo: Die Methode wirft einen Fehler, sobald eine der Dauern Jahre, Monate oder Wochen ungleich 0 enthält und relativeTo fehlt.
Tage ohne Bezugspunkt: Ohne relativeTo zählt ein Tag immer als 24 Stunden. Brauchst du wegen der Sommerzeit ein genaues Ergebnis, übergib ein Temporal.ZonedDateTime.
Kein ===: Zwei Duration-Objekte sind nie identisch, auch wenn ihr Inhalt gleich ist. Auch ein Vergleich per toString() erkennt PT90M und PT1H30M nicht als gleich. Nutze dafür compare() === 0.
Kein Vergleich mit < oder >: valueOf() wirft bei Duration einen TypeError. Verwende deshalb immer compare().
Browser-Unterstützung: Temporal ist noch nicht überall verfügbar, derzeit in Firefox ab 139 und Chrome ab 144. In Safari und älteren Umgebungen brauchst du ein Polyfill wie @js-temporal/polyfill.

Siehe auch

Temporal.Duration Temporal.Duration.from() Temporal.PlainDate.compare() Array.prototype.sort() Temporal.Instant.compare()