Temporal.Duration

Duration-Objekte können unter Verwendung des ISO 8601-Dauerformats (mit einigen von ECMAScript spezifizierten Erweiterungen) serialisiert und geparst werden. Der String hat die folgende Form (Leerzeichen dienen nur der Lesbarkeit und sollten im tatsächlichen String nicht vorhanden sein):

±P nY nM nW nD T nH nM nS

± Optional

Ein optionales Vorzeichenzeichen (+ oder -), das eine positive oder negative Dauer darstellt. Standard ist positiv.

P

Ein literales Zeichen P oder p, das für "Periode" steht.

nY, nM, nW, nD, nH, nM, nS

Eine Zahl gefolgt von einem literalen Zeichen, das die Anzahl der Jahre (Y), Monate (M), Wochen (W), Tage (D), Stunden (H), Minuten (M) oder Sekunden (S) darstellt. Alle außer der letzten existierenden Komponente müssen ganzzahlig sein. Die letzte Komponente, wenn sie eine Zeitkomponente ist (Stunden, Minuten oder Sekunden), kann einen Bruchteil von 1 bis 9 Stellen haben, die mit einem Punkt oder Komma eingeleitet werden, wie z. B. PT0.0021S oder PT1.1H. Alle Komponenten mit dem Wert Null können weggelassen werden, aber mindestens eine Komponente sollte vorhanden sein (auch wenn sie den Wert Null hat, in diesem Fall ist die Dauer null).

T

Ein literales Zeichen T oder t, das den Datumsteil vom Zeitteil trennt und nur vorhanden sein sollte, wenn mindestens eine Komponente nach ihm vorhanden ist.

Hier sind einige Beispiele:

Beim Serialisieren respektiert die Ausgabe die gespeicherten Komponenten so weit wie möglich und bewahrt unausgeglichene Komponenten. Subsekunden-Komponenten werden jedoch als einzelne Bruchteile von Sekunden serialisiert, sodass ihre genauen Werte, wenn unausgeglichen, möglicherweise verloren gehen. Das Pluszeichen wird bei positiven Dauern weggelassen. Die Null-Dauer wird immer als PT0S serialisiert.

Eine Kalenderdauer ist eine, die eine der Kalendereinheiten: Wochen, Monate und Jahre enthält. Eine Nicht-Kalenderdauer ist portabel und kann ohne jegliche Kalenderinformationen an Datum-/Uhrzeitarithmetik teilnehmen, da sie eindeutig eine feste Zeitmenge repräsentiert. Eine Kalenderdauer ist jedoch nicht portabel, da die Anzahl der Tage in einem Monat oder Jahr vom Kalendersystem und dem Referenzzeitpunkt abhängt. Daher führt der Versuch, jegliche arithmetische Operation auf Kalenderdauern durchzuführen, zu einem Fehler, da Dauern selbst keinen Kalender verfolgen. Zum Beispiel, wenn wir im Mai des gregorianischen Kalenders sind, dann ist "1 Monat" "31 Tage", aber wenn wir im April sind, dann wird "1 Monat" zu "30 Tagen". Um Kalenderdauern zu addieren oder zu subtrahieren, müssen Sie sie stattdessen zu Daten hinzufügen:

const dur1 = Temporal.Duration.from({ years: 1 });
const dur2 = Temporal.Duration.from({ months: 1 });

dur1.add(dur2); // RangeError: for calendar duration arithmetic, use date arithmetic relative to a starting point

const startingPoint = Temporal.PlainDate.from("2021-01-01"); // ISO 8601 calendar
startingPoint.add(dur1).add(dur2).since(startingPoint); // "P396D"

Andere Operationen, round(), total() und compare(), nehmen eine relativeTo-Option, um die notwendigen Kalender- und Referenzzeitinformationen bereitzustellen. Diese Option kann ein Temporal.PlainDate, Temporal.PlainDateTime, Temporal.ZonedDateTime oder anderweitig ein Objekt oder String sein, das konvertierbar ist unter Verwendung von Temporal.ZonedDateTime.from() (wenn die timeZone-Option bereitgestellt wird oder der String Zeitzonenanmerkungen enthält) oder Temporal.PlainDate.from().

Beachten Sie, dass die Umwandlung von Tagen zu Stunden auch technisch mehrdeutig ist, da die Länge eines Tages durch Offsetänderungen wie die Sommerzeit variieren kann. Sie können ein zonenbezogenes relativeTo bereitstellen, um diese Änderungen zu berücksichtigen; andernfalls werden Tage mit 24 Stunden angenommen.

Es gibt viele Möglichkeiten, dieselbe Dauer darzustellen: zum Beispiel sind "1 Minute und 30 Sekunden" und "90 Sekunden" gleichwertig. Abhängig vom Kontext ist jedoch eine Darstellung möglicherweise angemessener als die andere. Daher bewahrt das Duration-Objekt im Allgemeinen die Eingabewerte so weit wie möglich, sodass es beim Formatieren so angezeigt wird, wie Sie es erwarten.

Jede Komponente einer Dauer hat ihren optimalen Bereich; Stunden sollten von 0 bis 23, Minuten von 0 bis 59, usw. sein. Wenn eine Komponente ihren optimalen Bereich überschreitet, kann der Überschuss in die nächsthöhere Komponente "übertragen" werden. Um zu übertragen, müssen wir die Frage beantworten: "Wie viele X sind in einem Y?", was eine komplizierte Frage für Kalendereinheiten ist, daher wird in diesem Fall ein Kalender benötigt. Beachten Sie auch, dass standardmäßig Tage direkt in Monate übertragen werden; die Wocheneinheit wird nur übertragen, wenn explizit angefordert. Wenn wir so viel wie möglich übertragen, wird das endgültige Ergebnis, bei dem alle Komponenten innerhalb ihres optimalen Bereichs liegen, als "ausgeglichene" Dauer bezeichnet. Unaustarierte Dauern kommen in der Regel in Form von "oben schwer" vor, bei der die größte Einheit unaustariert ist (z. B. "27 Stunden und 30 Minuten"); andere Formen, wie "23 Stunden und 270 Minuten", sind selten zu sehen.

Die round()-Methode balanciert die Dauer immer in die Form "oben schwer" aus, bis zur Option largestUnit. Mit einer manuellen largestUnit-Option, die groß genug ist, können Sie die Dauer vollständig ausbalancieren. Ebenso balancieren die add()- und subtract()-Methoden die Ertragsdauer zur größten Einheit der Eingabedauern aus.

Beachten Sie, dass das ISO 8601-Dauerformat Subsekundenkomponenten als eine einzige Bruchzahl darstellt, so dass es nicht möglich ist, unaustarierte Subsekundenkomponenten während Serialisierung unter Verwendung des Standardformats zu bewahren. Zum Beispiel wird "1000 Millisekunden" als "PT1S" serialisiert und dann als "1 Sekunde" deserialisiert. Wenn Sie die Größenordnungen der Subsekundenkomponenten bewahren müssen, müssen Sie sie manuell als ein JSON-Objekt serialisieren (da standardmäßig die toJSON()-Methode die Dauer im ISO 8601-Format serialisiert).

Da eine Dauer ein Unterschied zwischen zwei Zeitpunkten ist, kann sie positiv, negativ oder null sein. Zum Beispiel, wenn Sie Ereigniszeiten in relativen Zeiten darstellen, können negative Dauern Ereignisse in der Vergangenheit und positive Dauern solche in der Zukunft repräsentieren. In unserer Darstellung mit einer Kombination von Zeitkomponenten wird das Vorzeichen in jeder Komponente gespeichert: eine negative Dauer hat immer alle Komponenten negativ (oder null), und eine positive Dauer hat immer alle Komponenten positiv (oder null). Das Erstellen einer Dauer mit Komponenten gemischter Vorzeichen ist ungültig und wird vom Konstruktor oder der with()-Methode abgelehnt. Die Methoden add() und subtract() balancieren die Ergebnisdauer, um gemischte Vorzeichen zu vermeiden.

Temporal.Duration() Experimentell

Erstellt ein neues Temporal.Duration-Objekt, indem die zugrunde liegenden Daten direkt bereitgestellt werden.

Temporal.Duration.compare() Experimentell

Gibt eine Zahl (-1, 0 oder 1) zurück, die anzeigt, ob die erste Dauer kürzer, gleich oder länger als die zweite ist.

Temporal.Duration.from() Experimentell

Erstellt ein neues Temporal.Duration-Objekt aus einem anderen Temporal.Duration-Objekt, einem Objekt mit Dauereigenschaften oder einem ISO 8601-String.

Diese Eigenschaften sind auf Temporal.Duration.prototype definiert und werden von allen Temporal.Duration-Instanzen geteilt.

Temporal.Duration.prototype.blank Experimentell

Gibt einen booleschen Wert zurück, der true ist, wenn diese Dauer eine Null-Dauer repräsentiert, und false ansonsten. Entspricht duration.sign === 0.

Temporal.Duration.prototype.constructor

Die Konstruktorfunktion, die das Instanzobjekt erstellt hat. Für Temporal.Duration-Instanzen ist der Anfangswert der Temporal.Duration()-Konstruktor.

Temporal.Duration.prototype.days Experimentell

Gibt eine ganze Zahl zurück, die die Anzahl der Tage in der Dauer repräsentiert.

Temporal.Duration.prototype.hours Experimentell

Gibt eine ganze Zahl zurück, die die Anzahl der Stunden in der Dauer repräsentiert.

Temporal.Duration.prototype.microseconds Experimentell

Gibt eine ganze Zahl zurück, die die Anzahl der Mikrosekunden in der Dauer repräsentiert.

Temporal.Duration.prototype.milliseconds Experimentell

Gibt eine ganze Zahl zurück, die die Anzahl der Millisekunden in der Dauer repräsentiert.

Temporal.Duration.prototype.minutes Experimentell

Gibt eine ganze Zahl zurück, die die Anzahl der Minuten in der Dauer repräsentiert.

Temporal.Duration.prototype.months Experimentell

Gibt eine ganze Zahl zurück, die die Anzahl der Monate in der Dauer repräsentiert.

Temporal.Duration.prototype.nanoseconds Experimentell

Gibt eine ganze Zahl zurück, die die Anzahl der Nanosekunden in der Dauer repräsentiert.

Temporal.Duration.prototype.seconds Experimentell

Gibt eine ganze Zahl zurück, die die Anzahl der Sekunden in der Dauer repräsentiert.

Temporal.Duration.prototype.sign Experimentell

Gibt 1 zurück, wenn diese Dauer positiv ist, -1 wenn negativ, und 0 wenn null.

Temporal.Duration.prototype.weeks Experimentell

Gibt eine ganze Zahl zurück, die die Anzahl der Wochen in der Dauer repräsentiert.

Temporal.Duration.prototype.years Experimentell

Gibt eine ganze Zahl zurück, die die Anzahl der Jahre in der Dauer repräsentiert.

Temporal.Duration.prototype[Symbol.toStringTag]

Der Anfangswert der [Symbol.toStringTag]-Eigenschaft ist der String "Temporal.Duration". Diese Eigenschaft wird in Object.prototype.toString() verwendet.

Temporal.Duration.prototype.abs() Experimentell

Gibt ein neues Temporal.Duration-Objekt mit dem Absolutwert dieser Dauer zurück (alle Felder behalten die gleiche Größe, aber das Vorzeichen wird positiv).

Temporal.Duration.prototype.add() Experimentell

Gibt ein neues Temporal.Duration-Objekt mit der Summe dieser Dauer und einer gegebenen Dauer zurück (in einer Form konvertierbar durch Temporal.Duration.from()). Das Ergebnis ist ausgeglichen.

Temporal.Duration.prototype.negated() Experimentell

Gibt ein neues Temporal.Duration-Objekt mit dem negierten Wert dieser Dauer zurück (alle Felder behalten die gleiche Größe, aber das Vorzeichen wird umgekehrt).

Temporal.Duration.prototype.round() Experimentell

Gibt ein neues Temporal.Duration-Objekt mit der auf die gegebene kleinste Einheit gerundeten Dauer und/oder ausgeglichen zur gegebenen größten Einheit zurück.

Temporal.Duration.prototype.subtract() Experimentell

Gibt ein neues Temporal.Duration-Objekt mit dem Unterschied zwischen dieser Dauer und einer gegebenen Dauer zurück (in einer Form konvertierbar durch Temporal.Duration.from()). Entspricht dem Hinzufügen des negierten Wertes der anderen Dauer.

Temporal.Duration.prototype.toJSON() Experimentell

Gibt einen String zurück, der diese Dauer in demselben ISO 8601-Format darstellt, wie beim Aufrufen von toString(). Soll implizit durch JSON.stringify() aufgerufen werden.

Temporal.Duration.prototype.toLocaleString() Experimentell

Gibt einen String mit einer sprachsensitiven Darstellung dieser Dauer zurück. In Implementierungen mit Unterstützung für die Intl.DurationFormat API delegiert diese Methode an Intl.DurationFormat.

Temporal.Duration.prototype.toString() Experimentell

Gibt einen String zurück, der diese Dauer im ISO 8601-Format darstellt.

Temporal.Duration.prototype.total() Experimentell

Gibt eine Zahl zurück, die die Gesamtdauer in der angegebenen Einheit repräsentiert.

Temporal.Duration.prototype.valueOf() Experimentell

Wirft einen TypeError, der verhindert, dass Temporal.Duration-Instanzen implizit in primitive Werte konvertiert werden, wenn sie in arithmetischen oder Vergleichsoperationen verwendet werden.

Temporal.Duration.prototype.with() Experimentell

Gibt ein neues Temporal.Duration-Objekt zurück, das diese Dauer mit einigen durch neue Werte ersetzten Feldern repräsentiert.

• Temporal