Temporal.PlainDate.prototype.add()

Syntax

add(duration)
add(duration, options)

Parameter

duration

Ein String, ein Objekt oder eine Temporal.Duration-Instanz, die eine Dauer darstellt, die zu diesem Datum hinzugefügt werden soll. Es wird mit demselben Algorithmus in ein Temporal.Duration-Objekt konvertiert wie bei Temporal.Duration.from().

options Optional

Ein Objekt, das folgende Eigenschaft enthält:

overflow Optional

Ein String, der das Verhalten angibt, wenn eine Datumskomponente außerhalb des Bereichs liegt. Mögliche Werte sind:

"constrain" (Standard)

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

"reject"

Es wird ein RangeError ausgelöst, wenn die Datumskomponente außerhalb des Bereichs liegt.

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 ±(10⁸ + 1) Tage oder etwa ±273.972,6 Jahre ab der Unix-Epoche beträgt.

Beschreibung

Mit der duration wird wie folgt umgegangen:

• Vorwärtsbewegung um die Anzahl der Jahre, wobei monthCode und day gleich bleiben. Wenn der monthCode im resultierenden Jahr ungültig ist (unmöglich für Gregorianische und ISO 8601-Kalender, aber möglich für Kalender mit Schaltmonaten), passen wir basierend auf der overflow-Option an: Bei constrain wählen wir einen anderen Monat nach den kulturellen Konventionen der Benutzer dieses Kalenders. Zum Beispiel, weil der Schaltmonat normalerweise als Duplikat eines anderen Monats angesehen wird, können wir den Monat wählen, von dem er ein Duplikat ist.
• Vorwärtsbewegung um die Anzahl der Monate, wobei das Jahr bei Bedarf angepasst wird, und 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 häufig unterstützen Kalender verwenden Wochen mit fester Länge, sodass die Anzahl der Wochen einfach in die Anzahl der Tage umgewandelt wird. Ist die Regel komplexer, können wir einen Ansatz ähnlich der Monatsverschiebung durchführen.
• Für alle nicht-kalenderbezogenen Einheiten (Tage, Stunden, Minuten, Sekunden, Millisekunden, Mikrosekunden, Nanosekunden) werden sie in die Anzahl der Tage umgewandelt. Der Bruchteil eines Tages wird ignoriert. Dann bewegen wir uns um diese Anzahl von Tagen nach vorne und passen den Monat bzw. das Jahr bei Bedarf an.

Das Hinzufügen einer Dauer ist gleichbedeutend mit dem Subtrahieren ihrer Negation.

Beispiele

Hinzufügen einer Dauer im ISO 8601-Kalender

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

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 einige Monate vorwärts bewegen und der entsprechende Tag in diesem Monat ungültig ist, passen wir den Tag basierend auf der overflow-Option an.

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, in denen verschiedene Jahre unterschiedliche Anzahlen an Monaten haben (meistens aufgrund von Schaltmonaten).

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 erhöht werden kann:

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:

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.

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

Browser-Kompatibilität

Siehe auch

• Temporal.PlainDate
• Temporal.Duration
• Temporal.PlainDate.prototype.subtract()