Temporal.PlainYearMonth.prototype.equals() — Methode · JavaScript-Referenz

Signatur

Temporal.PlainYearMonth.prototype.equals(other)

Beschreibung

Die Methode equals() vergleicht eine Temporal.PlainYearMonth-Instanz mit einem anderen Jahr-Monat und gibt true zurück, wenn beide denselben Wert haben. Das Argument darf eine Temporal.PlainYearMonth-Instanz sein oder etwas, das Temporal.PlainYearMonth.from() akzeptiert, zum Beispiel ein ISO-String wie "2024-03" oder ein Objekt wie { year: 2024, month: 3 }.

Verglichen werden intern das ISO-Referenzdatum (Jahr, Monat und Referenztag) und der Kalender. Zwei Jahr-Monate, die denselben Zeitraum beschreiben, aber in verschiedenen Kalendern angelegt sind (etwa iso8601 und gregory), gelten deshalb nicht als gleich.

Verwende equals(), wenn du wissen willst, ob zwei Temporal-Objekte denselben Wert haben. Der Operator === vergleicht dagegen nur Objektreferenzen, also ob es sich um dasselbe Objekt handelt. Zum Sortieren oder für „früher/später“-Vergleiche ist Temporal.PlainYearMonth.compare() gedacht.

Parameter

Name	Typ	Default	Beschreibung
$other Pflicht	Temporal.PlainYearMonth \| string \| Object		Der Jahr-Monat, mit dem verglichen wird. Er wird wie bei `Temporal.PlainYearMonth.from()` umgewandelt, zum Beispiel aus `"2024-03"` oder `{ year: 2024, month: 3 }`.

Beispiele

Einfacher Vergleich mit Instanz, String und Objekt

const ym = Temporal.PlainYearMonth.from("2024-03");

console.log(ym.equals(Temporal.PlainYearMonth.from({ year: 2024, month: 3 })));
console.log(ym.equals("2024-03"));
console.log(ym.equals({ year: 2024, month: 4 }));

true true false

equals() statt === verwenden

const a = Temporal.PlainYearMonth.from("2025-12");
const b = Temporal.PlainYearMonth.from("2025-12");

console.log(a === b);      // verschiedene Objekte
console.log(a.equals(b));  // gleicher Wert

false true

Praxis: Prüfen, ob eine Rechnung zum aktuellen Abrechnungsmonat gehört

const aktuellerMonat = Temporal.Now.plainDateISO().toPlainYearMonth();

const rechnungen = [
  { nr: "R-101", datum: "2024-03-15" },
  { nr: "R-102", datum: "2024-04-02" }
];

const imAktuellenMonat = rechnungen.filter(({ datum }) =>
  Temporal.PlainDate.from(datum).toPlainYearMonth().equals(aktuellerMonat)
);

console.log(imAktuellenMonat.map((r) => r.nr));

// z. B. im April 2024: ["R-102"]

Verschiedene Kalender sind nie gleich

const iso = Temporal.PlainYearMonth.from({ year: 2024, month: 3 });
const greg = Temporal.PlainYearMonth.from({ year: 2024, month: 3, calendar: "gregory" });

console.log(iso.equals(greg));
// Vergleich ohne Kalender über compare():
console.log(Temporal.PlainYearMonth.compare(iso, greg) === 0);

false true

// Wichtig · Fallstricke

Kalender zählt mit: equals() berücksichtigt den Kalender. Temporal.PlainYearMonth.compare() vergleicht dagegen nur die ISO-Referenzdaten. Wenn du ohne Kalender vergleichen willst, nimm compare(a, b) === 0 oder wandle beide vorher mit withCalendar() in denselben Kalender um.
Kein Ersatz für ===: Temporal-Objekte sind unveränderlich, aber jedes ist ein eigenes Objekt. ===, Set und Map-Schlüssel arbeiten mit Referenzen. Für Nachschlagetabellen eignet sich toString() als Schlüssel.
Ungültige Argumente: Kann other nicht umgewandelt werden, wirft die Methode einen TypeError (falscher Typ, zum Beispiel null) oder einen RangeError (zum Beispiel \"2024-13\").
Andere Typen: Übergibst du ein Temporal.PlainDate, wird es in einen Jahr-Monat umgewandelt. Der Tag spielt beim ISO-Kalender dann keine Rolle.
Kompatibilität: Temporal ist eine neue API und wird noch nicht von allen Browsern unterstützt (u. a. Firefox ab Version 139). In älteren Umgebungen brauchst du einen Polyfill wie @js-temporal/polyfill.

Siehe auch

Temporal.PlainYearMonth Temporal.PlainYearMonth.compare() Temporal.PlainYearMonth.from() Temporal.PlainDate.prototype.equals() Temporal.PlainYearMonth.prototype.valueOf()