Temporal.PlainDate.prototype.add()

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Die add()-Methode von Temporal.PlainDate-Instanzen gibt ein neues Temporal.PlainDate-Objekt zurück, das dieses Datum um eine angegebene Dauer nach vorne verschiebt (in einer Form, die durch Temporal.Duration.from() konvertierbar ist).

Syntax

js
add(duration)
add(duration, options)

Parameter

duration

Ein String, ein Objekt oder eine Temporal.Duration-Instanz, die eine zu diesem Datum hinzuzufügende Dauer darstellt. Sie wird mit dem gleichen Algorithmus wie Temporal.Duration.from() in ein Temporal.Duration-Objekt konvertiert.

options Optional

Ein Objekt, das folgende Eigenschaft enthält:

overflow Optional

Ein String, der das Verhalten spezifiziert, wenn eine Datumskomponente außer Reichweite ist. Mögliche Werte sind:

"constrain" (Standard)

Die Datumskomponente wird eingeschränkt auf den gültigen Bereich.

"reject"

Ein RangeError wird ausgelöst, wenn die Datumskomponente außer Reichweite ist.

Rückgabewert

Ein neues Temporal.PlainDate-Objekt, das das Datum darstellt, das durch das ursprüngliche PlainDate plus die Dauer angegeben wird.

Ausnahmen

RangeError

Wird ausgelöst, wenn das Ergebnis nicht im darstellbaren Bereich liegt, der ±(108 + 1) Tage oder etwa ±273.972,6 Jahre ab dem Unix-Epoch umfasst.

Beschreibung

Die duration wird wie folgt behandelt:

  • Vorwärtsverschiebung um die Anzahl der Jahre, wobei der monthCode und der day gleich bleiben. Wenn der monthCode im resultierenden Jahr ungültig ist (unmöglich für Gregorianisch und ISO 8601, aber möglich für Kalender mit Schaltmonaten), passen wir basierend auf der overflow-Option an: Bei constrain wählen wir einen anderen Monat gemäß den kulturellen Konventionen der Benutzer dieses Kalenders. Zum Beispiel, weil der Schaltmonat normalerweise als Duplikat eines anderen Monats betrachtet wird, können wir den Monat wählen, dessen Duplikat es ist.
  • Vorwärtsverschiebung um die Anzahl der Monate, bei Bedarf Anpassung des Jahres, wobei der day gleich bleibt. Wenn der day im resultierenden Monat ungültig ist (z.B. 30. Februar), passen wir basierend auf der overflow-Option an: Bei constrain wählen wir den nächstgelegenen gültigen Tag (z.B. 28. oder 29. Februar).
  • Alle allgemein unterstützten Kalender verwenden Wochen mit fester Länge, sodass die Anzahl der Wochen einfach in die Anzahl der Tage umgerechnet wird. Wenn die Regel komplexer ist, passen wir möglicherweise einen Ansatz ähnlich dem Verschieben von Monaten an.
  • Bei allen nicht-kalenderbezogenen Einheiten (Tage, Stunden, Minuten, Sekunden, Millisekunden, Mikrosekunden, Nanosekunden) werden sie in die Anzahl der Tage umgerechnet. Der Bruchteil eines Tages wird ignoriert. Dann bewegen wir uns um diese Anzahl an Tagen vorwärts, wobei wir bei Bedarf den Monat und das Jahr anpassen.

Das Hinzufügen einer Dauer entspricht dem Subtrahieren ihrer Negation.

Beispiele

Hinzufügen einer Dauer im ISO 8601-Kalender

js
const start = Temporal.PlainDate.from("2021-01-01");
const end = start.add({ years: 1, months: 2, weeks: 3, days: 4 });
console.log(end.toString()); // 2022-03-26

const end2 = start.add({ years: -1, months: -2, weeks: -3, days: -4 });
console.log(end2.toString()); // 2019-10-07

const distance = Temporal.PlainDate.from("2020-01-01").until("2021-01-01"); // 366 days
const end3 = start.add(distance);
console.log(end3.toString()); // 2022-01-02

Hinzufügen einer Dauer in einem Nicht-ISO-Kalender

js
const start = Temporal.PlainDate.from("2021-01-01[u-ca=chinese]");
console.log(start.toLocaleString("en-US", { calendar: "chinese" })); // 11/18/2020
const end = start.add({ months: 1 });
console.log(end.toLocaleString("en-US", { calendar: "chinese" })); // 12/18/2020

Hinzufügen einer Dauer mit Überlauf

Wenn wir uns ein paar Monate nach vorne bewegen und der entsprechende Tag in diesem Monat ungültig ist, passen wir den Tag basierend auf der overflow-Option an.

js
const start = Temporal.PlainDate.from("2021-01-31");
const end = start.add({ months: 1 });
console.log(end.toString()); // 2021-02-28

// Any further day additions are based on the clamped month-day:
const end2 = start.add({ months: 1, days: 31 });
console.log(end2.toString()); // 2021-03-31

// Compare with the same addition in a different order that results in no overflow:
const end3 = start.add({ days: 31 }).add({ months: 1 });
console.log(end3.toString()); // 2021-04-03

Ein Überlauf kann auch für den Monat auftreten, bei Kalendern, bei denen verschiedene Jahre unterschiedliche Monatszahlen haben (normalerweise aufgrund von Schaltmonaten).

js
const start = Temporal.PlainDate.from("2023-04-01[u-ca=chinese]");
console.log(start.toLocaleString("en-US", { calendar: "chinese" })); // 2bis/11/2023; "bis" means leap month
const end = start.add({ years: 1 });
console.log(end.toLocaleString("en-US", { calendar: "chinese" })); // 3/11/2024

// Compare:
const start = Temporal.PlainDate.from("2023-04-30[u-ca=chinese]");
console.log(start.toLocaleString("en-US", { calendar: "chinese" })); // 3/11/2023
const end = start.add({ years: 1 });
console.log(end.toLocaleString("en-US", { calendar: "chinese" })); // 3/11/2024; same day as above!

Beachten Sie, dass das Folgende kein Überlauf ist, da der Monat einfach inkrementiert werden kann:

js
const start = Temporal.PlainDate.from("2021-01-01");
const end = start.add({ days: 100 });
console.log(end.toString()); // 2021-04-11

Sie können auch einen Fehler auslösen, wenn die Datumskomponente außerhalb des Bereichs liegt:

js
const start = Temporal.PlainDate.from("2021-01-31");
const end = start.add({ months: 1 }, { overflow: "reject" }); // RangeError: date value "day" not in 1..28: 31

const start = Temporal.PlainDate.from("2023-04-01[u-ca=chinese]");
const end = start.add({ years: 1 }, { overflow: "reject" }); // RangeError: invalid "monthCode" calendar field: M02L

Hinzufügen von Zeitdauern

Bruchteile eines Tages werden ignoriert.

js
const start = Temporal.PlainDate.from("2021-01-01");
const end = start.add({ hours: 25 }); // Same as adding 1 day
console.log(end.toString()); // 2021-01-02

Spezifikationen

Specification
Temporal proposal
# sec-temporal.plaindate.prototype.add

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch