Temporal/Instant

Browserunterstützung
caniuse.com

Ein Temporal.Instant-Objekt repräsentiert einen eindeutigen Zeitpunkt, in Nanosekundengenauigkeit (im Rahmen der Möglichkeiten des verwendeten Computers). Genau wie Date stellt Instant einen Zeitpunkt als die Zeitdifferenz zum Bezugsmoment der Unix-Epoche – 01.01.1970, Mitternacht – dar.

Instant-Objekte kennen weder Zeitzone noch Kalendersystem, sie sind immer als UTC-Zeitpunkte aufzufassen. Aus diesem Grund kennt ein Instant-Objekt auch keine Eigenschaften oder Methoden, die Zeit- oder Datumsinformationen liefern. Solche Informationen erfordern Zeitzone und/oder Kalender, und dafür hat kann ein Instant mit der Methode toZonedDateTimeISO() in ein ZonedDateTime-Objekt umgewandelt werden.

Erzeugen eines Temporal.Instant

Um ein Instant-Objekt zu erhalten, kann man

• Mittels Temporal.Instant.from() einen anderen Instant oder den zu Grunde liegenden Instant eines ZonedDateTime-Objekts klonen
• Mittels Temporal.Instant.from() einen RFC 9557-String in einen Instant konvertieren
• Mittels Temporal.Instant.fromEpochMilliseconds() oder Temporal.Instant.fromEpochNanoseconds() die Zeitdifferenz zur Unix-Epoche in einen Instant umrechnen
• auf einem klassischen Date-Objekt die Methode toTemporalInstant() aufrufen
• von Temporal.Now.instant() den aktuellen Zeitpunkt erhalten
• von einem ZonedDateTime-Objekt mittels toInstant() den zu Grunde liegenden Instant abrufen

Hinweis:

fromEpochNanoseconds erwartet einen BigInt-Wert als Argument. fromEpochMilliseconds ist lediglich eine Komfortfunktion, die ihren Parameter in einen BigInt umwandelt und mit 1 000 000 multipliziert, um dann fromEpochNanoseconds aufzurufen.

Was kann man damit machen?

Nicht viel. Instant-Objekte sind universelle Zeitpunkte ohne direkten Bezug zur menschlichen Welt. Als solche kann man sie vergleichen, und – in Grenzen – mit ihnen rechnen.

Darüber hinaus lässt sich über die Methode toZonedDateTimeISO() aus einem Instant ein ZonedDateTime-Objekt (mit ISO-Kalender) erzeugen.

Eigenschaften und Vererbung

Der Prototyp für Temporal.Instant-Objekte erbt die Methoden von Object.prototype.

Darüber hinaus definiert er zwei Eigenschaften um die interne Darstellung des Zeitpunkts als Millisekunden oder Nanosekunden seit der Unix-Epoche zu liefern. Sie heißen dementsprechend epochMilliseconds und epochNanoseconds.

Diese Eigenschaften sind im Prototypen als Accessor-Propertys ohne Setter definiert, deshalb kann man ihnen keinen Wert zuweisen.

Vergleichen

Die statische Methode Temporal.Instant.compare(instant1, instant2) vergleicht zwei Instants und liefert den Wert -1, 0 oder 1, je nach dem, ob instant1 kleiner, gleich oder größer als instant2 ist. instant1 und instant2 können Instant-Objekte sein oder Werte, die von Temporal.Instant.from() konvertiert werden können.

Die compare()-Methode kann, um ein Array von Instant-Objekten (oder geeigneten Strings) zu sortieren, direkt an die Array-Methode sort übergeben werden.

Darüber hinaus unterstützen Instant-Objekte (wie alle Temporal-Objekte) eine equals()-Methode, die true oder false zurückgibt. Sie akzeptiert als Argument alles, was auch von Temporal.Instant.from() akzeptiert wird.

Arithmetik

Man kann zu einem Instant eine Duration addieren oder subtrahieren, und man kann aus dem Zeitunterschied zweier Instance-Objekte eine Duration erzeugen.

Zum Addieren und Subtrahieren dienen die Methoden add() und subtract eines Instant-Objekts. Sie erwarten als Argument ein Duration-Objekt oder etwas, das von Temporal.Duration.from() verstanden wird.

Diese Duration darf keine höhere Einheit als Stunden enthalten. Wenn Du einen Instant um Tage, Wochen, Monate oder Jahre ändern willst, musst Du ihn zuerst in ein ZonedDateTime-Objekt umwandeln, die Berechnung damit durchführen und das Ergebnis wieder in einen Instant umwandeln. Allerdings gilt auch: alle bekannten Kalender haben feste Umrechnungsfaktoren von Wochen in Tage und von Tagen in Stunden, deshalb kann man diese Einheiten in Stunden umrechnen und die Arithmetik damit füttern.

Beispiel

   const jetzt = Temporal.now.instant();
   const krach = jetzt.add("P2W");                 // RangeError
   const bumm  = jetzt.add("P14D");                // RangeError
   const in_2_wochen = jetzt.add(`PT${2*7*24}H`);  // Geht.

Das letzte Beispiel verwendet ein Template-Literal (oder Stringinterpolation), um 2 Wochen erkennbar in Stunden umzurechnen. 336 ist eine magische Zahl, der man ihren Sinn nicht sofort ansieht.

Zeitdifferenzen lassen sich auf zwei Arten ermitteln. Die Differenz instant2 - instant1 erhält man:

• bezogen auf instant1 mit instant1.until(instant2)
• bezogen auf instant2 mit instant2.since(instant1)

Das Ergebnis ist das Gleiche. Und wann verwendet man was? Beide Methoden akzeptieren alles, was auch die from()-Methode akzeptiert. Wenn man also einen der beiden Instants als Instant-Objekt vorliegen hat und der andere erst noch mittels from() konstruiert werden müsste, dann kann man sich das durch Verwendung der geeigneten Methode ersparen. Ansonsten ist es gleichgültig, welche Methode man benutzt.

Die ermittelte Zeitdifferenz lässt sich direkt runden. Dazu übergibt man an until() bzw. since() als zweites Argument ein Options-Objekt, wie es auch von der round()-Methode von Duration verstanden wird.

Runden

Wenn man den Zeitpunkt nicht auf Nanosekunden genau haben möchte, sondern auf eine größere Einheit runden will, kann man das mit der Methode round() eines Instant-Objekts tun. Man übergibt an round() entweder ein Options-Objekt mit den Eigenschaften roundingIncrement, roundingMode und smallestUnit, oder lediglich eine Zeichenkette mit dem Wert für smallestUnit.

Beachte: Die größte Einheit, auf die Instant-Objekte gerundet werden können, sind Stunden.

Hauptartikel: Runden von Temporal-Objekten

Konvertieren in andere Darstellungen

Zum einen können die generellen Methoden zur Umwandlung in einen String genutzt werden, die auf der Einstiegsseite beschrieben sind.

Darüber hinaus gibt es die Methide toZonedDateTimeISO(zeitzone), die einem Instant eine Zeitzone zuordnet und ein ZonedDateTime-Objekt mit dieser Zeitzone im ISO-Kalender erzeugt. Um die Zeitzone festzulegen, gibt es mehrere Möglichkeiten:

• Eine Zonenangabe, wie sie in einem RFC 9557-String möglich ist
• Ein vollständiger RFC 9557-String, der eine Zeitzonenangabe enthält (als IANA-Angabe oder als Offset)
• Ein Temporal.ZonedDateTime-Objekt, dessen Zeitzone zu verwenden ist.

Da Temporal-Objekte grundsätzlich unveränderlich sind, erzeugt toZonedDateTime() ein neues Objekt.

Zonenzuordnung

const wtc = Temporal.Instant.from("2001-09-11T08:46-04:00");
console.log(wtc.toZonedDateTimeISO("Europe/Berlin").toLocaleString());
// Ausgabe: 11.9.2001, 14:46:00 MESZ