</> programmierung.net
Start · Sprachen · JavaScript · Referenz · Temporal.PlainTime.prototype.since()

Temporal.PlainTime.prototype.since()

Methode

Gibt ein <code>Temporal.Duration</code> zurück, das die Zeitspanne von <code>other</code> bis zu dieser Uhrzeit angibt. Das Ergebnis ist positiv, wenn <code>other</code> früher liegt.

seit JavaScript Temporal (TC39-Proposal); Firefox 139+, Chrome/Edg Kategorie: method-property

Signatur

Temporal.PlainTime.prototype.since(other, options)

Beschreibung

Die Methode since() berechnet den Abstand zwischen zwei Uhrzeiten ohne Datum und ohne Zeitzone. Sie rechnet this − other. Liegt other vor der aktuellen Instanz, ist die zurückgegebene Temporal.Duration positiv, sonst negativ. Sie ist das Gegenstück zu until(), das die Richtung umkehrt.

Typische Einsätze sind Arbeitszeit- und Pausenberechnungen, Öffnungszeiten oder Stoppuhr-Anzeigen innerhalb eines Tages. Als other geht alles, was Temporal.PlainTime.from() annimmt: eine PlainTime-Instanz, ein ISO-Zeitstring wie "09:15" oder ein Objekt wie { hour: 9, minute: 15 }.

Über options legst du fest, in welchen Einheiten das Ergebnis ausgedrückt und wie es gerundet wird. Standardmäßig ist die größte Einheit "hour" und die kleinste "nanosecond". Es wird also nicht gerundet. Weil eine PlainTime kein Datum kennt, liegt das Ergebnis immer zwischen −24 und +24 Stunden. Tage oder größere Einheiten gibt es hier nicht.

Parameter

Name Typ Default Beschreibung
$other Pflicht Temporal.PlainTime | string | object Die Vergleichszeit, also der Startpunkt der Zeitspanne. Sie wird über Temporal.PlainTime.from() umgewandelt.
$options object {} Optionales Objekt mit Einstellungen für Einheiten und Rundung (siehe folgende Einträge).
$options.largestUnit string "auto" (entspricht "hour") Größte Einheit im Ergebnis: "hour", "minute", "second", "millisecond", "microsecond" oder "nanosecond". Singular- und Pluralformen sind beide erlaubt.
$options.smallestUnit string "nanosecond" Kleinste Einheit im Ergebnis. Alles, was kleiner ist, wird nach roundingMode gerundet.
$options.roundingIncrement number 1 Rundungsschritt in smallestUnit, z. B. 15 für Viertelstunden. Der Wert muss die nächstgrößere Einheit ohne Rest teilen.
$options.roundingMode string "trunc" Rundungsart: "ceil", "floor", "expand", "trunc", "halfCeil", "halfFloor", "halfExpand", "halfTrunc" oder "halfEven".

Rückgabewert

Typ
Temporal.Duration
Beschreibung
Ein neues Temporal.Duration-Objekt mit der Zeitspanne von other bis zur aktuellen Uhrzeit. Liegt other später, ist es negativ.

Beispiele

Arbeitszeit eines Tages berechnen

const feierabend = Temporal.PlainTime.from("17:30");
const arbeitsbeginn = "09:15";

const dauer = feierabend.since(arbeitsbeginn);
console.log(dauer.toString());
console.log(`${dauer.hours} h ${dauer.minutes} min`);
PT8H15M 8 h 15 min

Ergebnis in Minuten statt Stunden

const ende = Temporal.PlainTime.from("17:30");
const start = Temporal.PlainTime.from({ hour: 9, minute: 15 });

const inMinuten = ende.since(start, { largestUnit: "minute" });
console.log(inMinuten.toString());
console.log(inMinuten.minutes);
PT495M 495

Auf Viertelstunden runden (Abrechnung)

const ende = Temporal.PlainTime.from("12:34:56.789");

const exakt = ende.since("10:00");
const abgerechnet = ende.since("10:00", {
  smallestUnit: "minute",
  roundingIncrement: 15,
  roundingMode: "ceil"
});

console.log(exakt.toString());
console.log(abgerechnet.toString());
PT2H34M56.789S PT2H45M

Negative Dauer und Nachtschicht über Mitternacht

const start = Temporal.PlainTime.from("22:00");
const ende = Temporal.PlainTime.from("06:00");

// Ohne Datum ist 06:00 "früher" als 22:00
console.log(ende.since(start).toString());

// Richtig über Mitternacht: mit Datum rechnen
const tag = Temporal.PlainDate.from("2024-05-10");
const s = tag.toPlainDateTime(start);
const e = tag.add({ days: 1 }).toPlainDateTime(ende);
console.log(e.since(s).toString());
-PT16H PT8H

// Wichtig · Fallstricke

  • Kein Umbruch über Mitternacht: PlainTime kennt kein Datum. Deshalb gibt Temporal.PlainTime.from("06:00").since("22:00") -PT16H zurück und nicht PT8H. Für Schichten über Mitternacht nimmst du Temporal.PlainDateTime oder Temporal.ZonedDateTime.
  • Keine Zeitzonen oder Sommerzeit: Die Differenz ist reine Uhrzeit-Arithmetik. Eine Zeitumstellung am selben Tag wird nicht berücksichtigt. Dafür ist ZonedDateTime.prototype.since() da.
  • RangeError tritt auf, wenn largestUnit oder smallestUnit eine Datumseinheit ist ("day", "week", "month", "year"), wenn smallestUnit größer als largestUnit ist oder wenn roundingIncrement die nächstgrößere Einheit nicht ohne Rest teilt. Ein ungültiger String für other löst ebenfalls einen RangeError aus, ein ungeeigneter Typ einen TypeError.
  • Standardrundung ist "trunc", es wird also zur Null hin abgeschnitten. Für kaufmännisches Runden setzt du roundingMode: "halfExpand".
  • a.since(b) gibt dieselbe Dauer zurück wie a.until(b).negated(). Bei der Rundung kann es an Grenzfällen trotzdem Unterschiede geben, weil die Richtung beim Runden eine Rolle spielt.
  • Kompatibilität: Temporal gibt es bisher nur in neueren Browsern (Firefox 139+, Chromium 144+). Für Safari, ältere Browser und viele Node.js-Versionen brauchst du einen Polyfill wie @js-temporal/polyfill.

Siehe auch

Temporal.PlainDate.prototype.since() Temporal.PlainDateTime.prototype.since() Temporal.PlainTime.prototype.with() Temporal.PlainTime.prototype.add() Temporal.PlainTime.prototype.round() Temporal.PlainTime.prototype.valueOf()
← Vorheriger Eintrag Temporal.PlainTime.prototype.second