Temporal.PlainYearMonth.prototype.add()

Syntax

add(duration)
add(duration, options)

Parameter

duration

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

options Optional

Ein Objekt, das die folgende Eigenschaft enthält:

overflow Optional

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

"constrain" (Standard)

Die Datumskomponente wird beschränkt, um innerhalb des gültigen Bereichs zu liegen.

"reject"

Ein RangeError wird ausgelöst, wenn die Datumskomponente außerhalb des gültigen Bereichs liegt.

Rückgabewert

Ein neues Temporal.PlainYearMonth Objekt, das den durch das ursprüngliche PlainYearMonth und die Dauer spezifizierten Jahr-Monat darstellt.

Ausnahmen

RangeError

Wird ausgelöst, wenn das Ergebnis nicht im darstellbaren Bereich liegt, der ±(10⁸ + 1) Tage oder etwa ±273.972,6 Jahre von der Unix-Epoche beträgt.

Beschreibung

Die duration wird wie folgt verarbeitet:

• Vorwärts bewegen um die Anzahl der Jahre, wobei der monthCode gleich bleibt. Wenn der monthCode im resultierenden Jahr ungültig ist (unmöglich für den gregorianischen und ISO 8601 Kalender, aber möglich für Kalender mit Schaltmonaten), passen wir basierend auf der overflow Option an: für constrain wählen wir einen anderen Monat gemäß den kulturellen Konventionen der Benutzer dieses Kalenders. Da der Schaltmonat normalerweise als Duplikat eines anderen Monats angesehen wird, können wir den Monat wählen, von dem er ein Duplikat ist.
• Vorwärts bewegen um die Anzahl der Monate, wobei das Jahr falls notwendig angepasst wird.
• Für alle Einheiten kleiner als months (Wochen, Tage, Stunden, Minuten, Sekunden, Millisekunden, Mikrosekunden, Nanosekunden) werden diese in die Anzahl der Tage konvertiert. Alle allgemein unterstützten Kalender verwenden Wochen mit fester Länge, daher wird die Anzahl der Wochen einfach in die Anzahl der Tage umgewandelt. Wenn die Regel komplexer ist, können wir einen Ansatz ähnlich dem Verschieben von Monaten wählen. Dann bewegen wir uns um diese Anzahl von Tagen vorwärts, beginnend am ersten Tag des Monats, wobei der Monat und das Jahr bei Bedarf angepasst werden. Dauern, die kürzer sind als die Länge des aktuellen Monats, haben daher keine Auswirkung.

Der interne Referenztag wird dann als erster gültiger Tag des Monats gewählt, unabhängig vom ursprünglichen Referenztag oder der Anzahl der Tage in der Dauer. Für den gregorianischen Kalender kann kein Überlauf auftreten, da jedes Jahr immer 12 Monate hat und jede Erhöhung um weniger als einen Monat einfach ignoriert wird.

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

Beispiele

Hinzufügen einer Dauer im ISO 8601 Kalender

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

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

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

Hinzufügen einer Dauer in einem nicht-ISO Kalender

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

// Adding an extra day has no effect at all
const end2 = start.add({ months: 1, days: 1 });
console.log(end2.toLocaleString("en-US", { calendar: "chinese" })); // 1/2021
// The reference day doesn't change, because it's always the first day of the Chinese month
console.log(end2.toString()); // 2021-02-12[u-ca=chinese]

// Start in a leap month
const start2 = Temporal.PlainYearMonth.from({
  year: 5730,
  monthCode: "M05L",
  calendar: "hebrew",
});
console.log(start2.toLocaleString("en-US", { calendar: "hebrew" })); // Adar I 5730
// End in another leap month
const end3 = start2.add({ years: 3 });
console.log(end3.toLocaleString("en-US", { calendar: "hebrew" })); // Adar I 5733

Hinzufügen einer Dauer mit Überlauf

Wenn wir einige Jahre vorwärts gehen und der entsprechende Monat in diesem Jahr ungültig ist, passen wir den Monat basierend auf der overflow Option an.

// Start in a leap month
const start = Temporal.PlainYearMonth.from({
  year: 5730,
  monthCode: "M05L",
  calendar: "hebrew",
});
// Hebrew leap years occur every 2 or 3 years, and 5731 is not a leap year
const end = start.add({ years: 1 });
console.log(end.toLocaleString("en-US", { calendar: "hebrew" })); // Adar 5731
console.log(end.monthCode); // M06
console.log(end.toString()); // 1971-02-26[u-ca=hebrew]

// Any further month additions are based on the clamped year-month
const end2 = start.add({ years: 1, months: 2 });
console.log(end2.monthCode); // M08
console.log(end2.toString()); // 1971-04-26[u-ca=hebrew]

// Compare with the same addition in a different order that results in no overflow:
const end3 = start.add({ months: 2 }).add({ years: 1 });
console.log(end3.monthCode); // M07
console.log(end3.toString()); // 1971-03-27[u-ca=hebrew]

Beachten Sie, dass es sich hierbei nicht um einen Überlauf handelt, da das Jahr einfach inkrementieren kann:

const start = Temporal.PlainYearMonth.from("2021-01");
const end = start.add({ months: 100 });
console.log(end.toString()); // 2029-05

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

const start = Temporal.PlainYearMonth.from({
  year: 5730,
  monthCode: "M05L",
  calendar: "hebrew",
});
const end = start.add({ years: 1 }, { overflow: "reject" }); // RangeError: invalid "monthCode" calendar field: M05L

Spezifikationen

Browser-Kompatibilität

Siehe auch

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