</> programmierung.net
Start · Sprachen · JavaScript · Referenz · Temporal.PlainDateTime.prototype.subtract()

Temporal.PlainDateTime.prototype.subtract()

Methode

Gibt ein neues <code>Temporal.PlainDateTime</code> zurück, das um die angegebene Dauer in die Vergangenheit verschoben ist. Das Original bleibt unverändert.

seit JavaScript ES2026 (Temporal); Firefox 139+, Chrome 144+, Safa Kategorie: method-property

Signatur

Temporal.PlainDateTime.prototype.subtract(duration, options)

Beschreibung

Die Methode subtract() verschiebt ein Temporal.PlainDateTime (Datum und Uhrzeit ohne Zeitzone) um eine Dauer nach hinten und liefert dabei ein neues Objekt. Wie alle Temporal-Typen ist PlainDateTime unveränderlich, die ursprüngliche Instanz wird also nie verändert.

Als Dauer akzeptiert die Methode ein Temporal.Duration-Objekt, ein Objekt mit Dauer-Feldern (z. B. { days: 3, hours: 2 }) oder einen ISO-8601-Dauer-String wie "P1M2DT3H". Die Rechnung läuft zuerst über den Kalender: Jahre und Monate werden kalenderbewusst abgezogen, danach Wochen und Tage und zum Schluss die Zeitanteile. Ein Übertrag über Mitternacht wird dabei korrekt auf das Datum umgerechnet.

Weil PlainDateTime keine Zeitzone kennt, spielen Sommerzeitumstellungen hier keine Rolle: Ein Tag entspricht immer genau 24 Stunden. Brauchen Sie echte verstrichene Zeit in einer bestimmten Zeitzone, verwenden Sie Temporal.ZonedDateTime.

dt.subtract(d) liefert dasselbe Ergebnis wie dt.add(d.negated()).

Parameter

Name Typ Default Beschreibung
$duration Pflicht Temporal.Duration | object | string Die abzuziehende Dauer: eine Temporal.Duration, ein Objekt mit Feldern wie years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds oder ein ISO-8601-Dauer-String. Die Umwandlung läuft über Temporal.Duration.from().
$options object { overflow: "constrain" } Optionales Objekt mit der Eigenschaft overflow: "constrain" (Standard) setzt ungültige Tage auf den nächsten gültigen Wert, z. B. 31. März minus 1 Monat ergibt 28./29. Februar. Bei "reject" wird stattdessen ein RangeError geworfen.

Rückgabewert

Typ
Temporal.PlainDateTime
Beschreibung
Ein neues Temporal.PlainDateTime, das um duration früher liegt als die ursprüngliche Instanz. Kalender und Genauigkeit bleiben erhalten.

Beispiele

Einfache Subtraktion mit Objekt und String

const termin = Temporal.PlainDateTime.from("2024-03-15T10:30");

// Objekt mit Dauer-Feldern
console.log(termin.subtract({ days: 2, hours: 3 }).toString());

// ISO-8601-Dauer-String
console.log(termin.subtract("PT45M").toString());

// Original bleibt unverändert
console.log(termin.toString());
2024-03-13T07:30:00 2024-03-15T09:45:00 2024-03-15T10:30:00

Übertrag über Mitternacht

const start = Temporal.PlainDateTime.from("2024-01-01T01:15");
const frueher = start.subtract({ hours: 2, minutes: 30 });
console.log(frueher.toString());
2023-12-31T22:45:00

Monatsende: overflow constrain und reject

const ende = Temporal.PlainDateTime.from("2024-03-31T12:00");

// Standard: auf den letzten gültigen Tag begrenzen (2024 ist ein Schaltjahr)
console.log(ende.subtract({ months: 1 }).toString());

try {
  ende.subtract({ months: 1 }, { overflow: "reject" });
} catch (err) {
  console.log(err.constructor.name);
}
2024-02-29T12:00:00 RangeError

Praxis: Erinnerung 90 Minuten vor einem Termin

const meeting = Temporal.PlainDateTime.from({
  year: 2024, month: 6, day: 10, hour: 9, minute: 0
});
const dauer = Temporal.Duration.from({ minutes: 90 });
const erinnerung = meeting.subtract(dauer);

console.log(`Erinnerung um ${erinnerung.toPlainTime()} am ${erinnerung.toPlainDate()}`);
Erinnerung um 07:30:00 am 2024-06-10

// Wichtig · Fallstricke

  • Browser-Unterstützung: Temporal ist erst in neueren Browsern verfügbar (Firefox 139+, Chrome 144+). Safari und ältere Node.js-Versionen unterstützen es noch nicht. Für den Einsatz in der Produktion brauchen Sie ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill.
  • Keine Zeitzone: Sommerzeitwechsel werden ignoriert. Wenn Sie 24 Stunden über eine Zeitumstellung hinweg abziehen, ergibt das bei PlainDateTime immer denselben Wandzeit-Wert am Vortag. Für echte Zeitzonen-Arithmetik ist Temporal.ZonedDateTime das richtige Werkzeug.
  • Reihenfolge ist nicht umkehrbar: Weil Monate unterschiedlich lang sind, ergibt dt.subtract({ months: 1 }).add({ months: 1 }) nicht immer wieder dt. Beispiel: 31.03. → 29.02. → 29.03.
  • Eine Dauer mit gemischten Vorzeichen, z. B. { days: 1, hours: -2 }, ist ungültig und wirft einen RangeError. Eine negative Dauer ist dagegen erlaubt und verschiebt das Datum nach vorn.
  • Liegt das Ergebnis außerhalb des unterstützten Bereichs (ungefähr ±271.821 Jahre), wird ein RangeError geworfen.
  • Um die Differenz zwischen zwei Zeitpunkten zu berechnen, verwenden Sie since() oder until(), nicht subtract().

Siehe auch

Temporal.PlainDateTime.prototype.add() Temporal.PlainDateTime.prototype.since() Temporal.PlainDateTime.prototype.until() Temporal.PlainDateTime Temporal.Duration Temporal.ZonedDateTime.prototype.subtract()
← Vorheriger Eintrag Temporal.PlainDateTime.prototype.since()