</> programmierung.net
Start · Sprachen · JavaScript · Referenz · Temporal.PlainYearMonth.prototype.since()

Temporal.PlainYearMonth.prototype.since()

Methode

Gibt eine <code>Temporal.Duration</code> zurück, die die Zeitspanne von einem anderen Jahr-Monat (<code>other</code>) bis zu diesem Jahr-Monat in Jahren und Monaten angibt.

seit JavaScript Temporal (TC39, Stage 3) – Firefox 139+, Chrome/Ed Kategorie: method-property

Signatur

Temporal.PlainYearMonth.prototype.since(other, options)

Beschreibung

since() berechnet, wie viel Zeit seit dem Jahr-Monat other bis zum aktuellen Objekt (this) vergangen ist. Liegt other vor this, ist die Dauer positiv, sonst negativ. Das Argument kann ein Temporal.PlainYearMonth, ein String wie "2021-02" oder ein Objekt wie { year: 2021, month: 2 } sein – also alles, was Temporal.PlainYearMonth.from() akzeptiert.

Da ein PlainYearMonth keinen Tag enthält, arbeitet die Methode nur mit den Einheiten Jahre und Monate. Standardmäßig wird das Ergebnis mit Jahren als größter Einheit ausgegeben (z. B. P3Y6M). Über largestUnit: "month" erhält man stattdessen die Gesamtzahl der Monate, über smallestUnit und roundingMode lässt sich das Ergebnis auf ganze Jahre runden.

Typische Einsatzfälle sind Laufzeiten von Verträgen und Abonnements, Betriebszugehörigkeit, Altersangaben in Monaten oder Abrechnungszeiträume – überall dort, wo Tage keine Rolle spielen. a.since(b) entspricht im Ergebnis weitgehend b.until(a); die Richtung wirkt sich aber auf das Runden aus.

Parameter

Name Typ Default Beschreibung
$other Pflicht Temporal.PlainYearMonth | string | Object Der Jahr-Monat, von dem aus gemessen wird. Wird wie bei Temporal.PlainYearMonth.from() umgewandelt.
$options Object {} Optionales Objekt mit Einstellungen für Einheiten und Rundung (siehe folgende Einträge).
$options.largestUnit "auto" | "year" | "month" (auch Plural) "auto" (= "year") Größte Einheit im Ergebnis. Mit "month" werden Jahre in Monate umgerechnet.
$options.smallestUnit "year" | "month" (auch Plural) "month" Kleinste Einheit im Ergebnis; kleinere Anteile werden gerundet. Darf nicht größer als largestUnit sein.
$options.roundingIncrement number 1 Rundungsschritt in smallestUnit, z. B. 3 für Quartale bei smallestUnit: "month".
$options.roundingMode "ceil" | "floor" | "expand" | "trunc" | "halfCeil" | "halfFloor" | "halfExpand" | "halfTrunc" | "halfEven" "trunc" Rundungsmodus für den abgeschnittenen Rest. Standard ist Abschneiden Richtung null.

Rückgabewert

Typ
Temporal.Duration
Beschreibung
Eine neue Temporal.Duration, die nur years und months enthält. Sie ist positiv, wenn other vor this liegt, und negativ, wenn other danach liegt.

Beispiele

Vertragslaufzeit in Jahren und Monaten

const vertragsbeginn = Temporal.PlainYearMonth.from("2021-02");
const heute = Temporal.PlainYearMonth.from("2024-08");

const laufzeit = heute.since(vertragsbeginn);
console.log(laufzeit.toString());
console.log(`${laufzeit.years} Jahre, ${laufzeit.months} Monate`);

// Umgekehrte Richtung ergibt eine negative Dauer
console.log(vertragsbeginn.since(heute).toString());
P3Y6M 3 Jahre, 6 Monate -P3Y6M

Gesamtzahl der Monate für eine Abrechnung

const abo = Temporal.PlainYearMonth.from({ year: 2022, month: 11 });
const aktuell = Temporal.PlainYearMonth.from("2025-03");

const monate = aktuell.since(abo, { largestUnit: "month" }).months;
const preisProMonat = 9.99;
console.log(`${monate} Monate × ${preisProMonat} € = ${(monate * preisProMonat).toFixed(2)} €`);
28 Monate × 9.99 € = 279.72 €

Auf ganze Jahre runden (Betriebszugehörigkeit)

const eintritt = Temporal.PlainYearMonth.from("2019-03");
const stichtag = Temporal.PlainYearMonth.from("2024-10");

// Standard: abschneiden
console.log(stichtag.since(eintritt, { smallestUnit: "year" }).toString());

// Kaufmännisch runden (ab 6 Monaten aufrunden)
console.log(
  stichtag.since(eintritt, { smallestUnit: "year", roundingMode: "halfExpand" }).toString()
);

// String als Argument ist ebenfalls erlaubt
console.log(stichtag.since("2024-01").toString());
P5Y P6Y P9M

// Wichtig · Fallstricke

  • Nur Jahre und Monate: Einheiten wie "week", "day" oder "hour" für largestUnit/smallestUnit werfen einen RangeError. Wenn du Tage brauchst, wandle vorher mit toPlainDate({ day: 1 }) um und nutze Temporal.PlainDate.prototype.since().
  • Kalender müssen übereinstimmen: Haben this und other unterschiedliche Kalender (z. B. iso8601 und hebrew), wird ein RangeError geworfen.
  • Richtung beachten: a.since(b) misst von b nach a. Wer die Reihenfolge vertauscht, bekommt ein negatives Ergebnis – prüfe gegebenenfalls duration.sign oder nutze duration.abs().
  • Rundung: Standard ist "trunc", also wird immer abgeschnitten. Bei negativen Dauern verhalten sich "floor"/"ceil" anders als "trunc"/"expand".
  • Kompatibilität: Temporal ist noch nicht in allen Browsern verfügbar (Safari fehlt bislang, ältere Chrome- und Node.js-Versionen ebenfalls). Für den produktiven Einsatz empfiehlt sich ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainYearMonth.prototype.with() Temporal.PlainYearMonth.prototype.add() Temporal.PlainYearMonth.prototype.until() Temporal.PlainYearMonth.prototype.equals() Temporal.PlainYearMonth.prototype.subtract()
← Vorheriger Eintrag Temporal.PlainYearMonth.prototype.monthsInYear