Temporal.PlainDate.prototype.since()

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 since()-Methode von Temporal.PlainDate-Instanzen gibt ein neues Temporal.Duration-Objekt zurück, das die Dauer von einem anderen Datum (in einer Form, die durch Temporal.PlainDate.from() konvertierbar ist) bis zu diesem Datum darstellt. Die Dauer ist positiv, wenn das andere Datum vor diesem Datum liegt, und negativ, wenn es danach liegt.

Diese Methode führt this - other aus. Um other - this auszuführen, verwenden Sie die until()-Methode.

Syntax

since(other)
since(other, options)

Parameter

other: Ein String, ein Objekt oder eine Temporal.PlainDate-Instanz, die ein Datum darstellt, das von diesem Datum subtrahiert werden soll. Es wird mit demselben Algorithmus wie Temporal.PlainDate.from() in ein Temporal.PlainDate-Objekt konvertiert. Es muss den gleichen Kalender wie this haben.
options Optional: Ein Objekt, das die Optionen für Temporal.Duration.prototype.round() enthält, welche largestUnit, roundingIncrement, roundingMode und smallestUnit beinhalten. largestUnit und smallestUnit akzeptieren nur die Einheiten: "years", "months", "weeks", "days" oder deren Einzahlformen. Für largestUnit bedeutet der Standardwert "auto" entweder "days" oder smallestUnit, je nachdem, welcher größer ist. Für smallestUnit ist der Standardwert "days". Das aktuelle Datum wird als die Option relativeTo verwendet. Beachten Sie, dass die Verwendung von Einheiten größer als "days" die Dauer möglicherweise nicht portierbar für andere Kalender oder Daten macht.

Rückgabewert

Ein neues Temporal.Duration-Objekt, das die Dauer seit other bis zu diesem Datum darstellt. Die Dauer ist positiv, wenn other vor diesem Datum liegt, und negativ, wenn danach.

Ausnahmen

RangeError

Wird in einem der folgenden Fälle ausgelöst:

other hat einen anderen Kalender als this.
Eine der Optionen ist ungültig.

Beispiele

Verwendung von since()

const date = Temporal.PlainDate.from("2022-12-25");
const now = Temporal.Now.plainDateISO();
const duration = now.since(date);
const formatter = new Intl.DurationFormat("en-US", { style: "long" });
console.log(`It's been ${formatter.format(duration)} since that Christmas...`);
// Expected output: "It's been [number] days since that Christmas..."

const duration2 = now.since(date, { smallestUnit: "months" });
console.log(`It's been ${formatter.format(duration2)} since that Christmas...`);
// Expected output: "It's been [number] months since that Christmas..."

const duration3 = now.since(date, {
  largestUnit: "years",
  smallestUnit: "months",
});
console.log(`It's been ${formatter.format(duration3)} since that Christmas...`);
// Expected output: "It's been [number] years, [number] months since that Christmas..."

Das Ergebnis runden

Standardmäßig wird der Bruchteil von smallestUnit abgeschnitten. Sie können ihn mithilfe der Optionen roundingIncrement und roundingMode aufrunden.

const date1 = Temporal.PlainDate.from("2022-01-01");
const date2 = Temporal.PlainDate.from("2022-01-28");
const duration = date2.since(date1, {
  smallestUnit: "days",
  roundingIncrement: 5,
  roundingMode: "ceil",
});
console.log(duration.toString()); // "P30D"

Vergleich verschiedener Kalender

Standardmäßig müssen die beiden Daten denselben Kalender haben. Dies dient dazu, Mehrdeutigkeiten in der Bedeutung von Monaten und Jahren zu vermeiden. Wenn Sie Daten aus verschiedenen Kalendern vergleichen möchten, können Sie diese zuerst in denselben Kalender konvertieren.

const date1 = Temporal.PlainDate.from("2022-01-01");
const date2 = Temporal.PlainDate.from("2022-01-28[u-ca=chinese]");
const duration = date2.withCalendar("iso8601").since(date1);
console.log(duration.toString()); // "P27D"

Spezifikationen

Specification
Temporal # sec-temporal.plaindate.prototype.since