Signatur
Beschreibung
round() erledigt zwei Aufgaben, einzeln oder zusammen: Runden über smallestUnit, roundingIncrement und roundingMode sowie Ausbalancieren über largestUnit. Beim Ausbalancieren werden überzählige kleine Einheiten in größere umgerechnet (z. B. PT130M → PT2H10M). Es geht auch umgekehrt: Große Einheiten lassen sich in kleinere aufteilen (z. B. PT2H → PT120M mit largestUnit: "minutes").
Temporal.Duration ist unveränderlich. Das ursprüngliche Objekt bleibt also gleich, und Sie bekommen immer eine neue Instanz zurück. Übergeben Sie nur einen String, etwa duration.round("minutes"), ist das eine Kurzform für { smallestUnit: "minutes" }. Im Options-Objekt müssen Sie mindestens smallestUnit oder largestUnit angeben.
Typische Anwendungsfälle:
- Arbeitszeiten für die Abrechnung auf 15 Minuten aufrunden
- Laufzeiten lesbar darstellen (Sekunden in Tage, Stunden und Minuten umrechnen)
- Überflüssige Genauigkeit wie Milli- oder Nanosekunden entfernen
Ohne Bezugspunkt zählt ein Tag immer als 24 Stunden. Jahre, Monate und Wochen sind dagegen unterschiedlich lang. Für diese Einheiten brauchen Sie deshalb einen Bezugspunkt in relativeTo, also ein Temporal.PlainDate oder ein Temporal.ZonedDateTime. Mit einem Temporal.ZonedDateTime werden zusätzlich Zeitzonenwechsel wie die Umstellung auf Sommerzeit berücksichtigt. Ein Tag kann dann 23 oder 25 Stunden haben.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $smallestUnit | string | Kurzform: Nur die kleinste Einheit als String, z. B. "minutes". Entspricht { smallestUnit: "minutes" }. |
|
| $options.smallestUnit | string | "nanoseconds" | Kleinste Einheit im Ergebnis, auf die gerundet wird: "years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds", "microseconds", "nanoseconds". Die Einzahl wird ebenfalls akzeptiert. |
| $options.largestUnit | string | "auto" | Größte Einheit im Ergebnis. "auto" nimmt die größere von zwei Einheiten: die größte Einheit, die in der Dauer nicht null ist, oder smallestUnit. Darf nicht kleiner als smallestUnit sein. |
| $options.roundingIncrement | number | 1 | Schrittweite beim Runden, z. B. 15 für Viertelstunden. Bei Zeiteinheiten muss sie die nächstgrößere Einheit ohne Rest teilen (z. B. 15 teilt 60 Minuten). |
| $options.roundingMode | string | "halfExpand" | Rundungsverfahren: "ceil", "floor", "expand", "trunc", "halfCeil", "halfFloor", "halfExpand", "halfTrunc", "halfEven". |
| $options.relativeTo | Temporal.PlainDate | Temporal.ZonedDateTime | string | object | Bezugspunkt für Jahre, Monate und Wochen und für Tage, die nicht genau 24 Stunden lang sind. Pflicht, sobald die Dauer oder smallestUnit/largestUnit Kalendereinheiten enthalten. Strings wie "2024-01-15" werden automatisch umgewandelt. |
Rückgabewert
Temporal.Duration. Die ursprüngliche Instanz bleibt unverändert.