Temporal.Duration.prototype.negated() — Methode · JavaScript-Referenz

Signatur

Temporal.Duration.prototype.negated()

Beschreibung

negated() kehrt das Vorzeichen einer Dauer um: Aus PT2H30M wird -PT2H30M und umgekehrt. Die Beträge der einzelnen Felder (years, months, days, hours usw.) ändern sich nicht. Es wird auch nichts umgerechnet oder ausgeglichen. Eine Dauer wie { hours: 25 } bleibt also nach dem Negieren { hours: -25 }.

Wie alle Temporal-Objekte ist Temporal.Duration unveränderlich. Die Methode ändert das ursprüngliche Objekt nicht, sondern gibt immer eine neue Instanz zurück.

Nützlich ist negated(), wenn man eine Dauer in die andere Richtung anwenden will, etwa um mit derselben Frist sowohl vorwärts als auch rückwärts zu rechnen. Außerdem kann man damit eine Differenz aus until()/since() umdrehen oder Dauern mit Vorzeichen vergleichen. Soll das Ergebnis immer positiv sein, verwendet man stattdessen abs().

Rückgabewert

Typ

Temporal.Duration

Beschreibung

Eine neue Temporal.Duration mit umgekehrtem Vorzeichen. Ist die ursprüngliche Dauer null (blank === true), ist auch das Ergebnis wieder eine Nulldauer.

Beispiele

Vorzeichen einer Dauer umkehren

const dauer = Temporal.Duration.from({ hours: 2, minutes: 30 });
const negativ = dauer.negated();

console.log(dauer.toString());
console.log(negativ.toString());
console.log(negativ.sign, negativ.hours, negativ.minutes);
// Doppeltes Negieren ergibt wieder den Ausgangswert
console.log(negativ.negated().toString());

PT2H30M -PT2H30M -1 -2 -30 PT2H30M

Dieselbe Frist vorwärts und rückwärts anwenden

const frist = Temporal.Duration.from({ days: 10 });
const stichtag = Temporal.PlainDate.from('2024-03-15');

const spaetestens = stichtag.add(frist);
const fruehestens = stichtag.add(frist.negated()); // entspricht subtract(frist)

console.log(`Zeitraum: ${fruehestens} bis ${spaetestens}`);

Zeitraum: 2024-03-05 bis 2024-03-25

Differenz umdrehen und mit abs() vergleichen

const start = Temporal.PlainTime.from('09:00');
const ende = Temporal.PlainTime.from('17:45');

const rueckwaerts = ende.until(start); // negative Dauer
console.log(rueckwaerts.toString());
console.log(rueckwaerts.negated().toString());
console.log(rueckwaerts.abs().toString());

// Nulldauer bleibt Nulldauer
console.log(Temporal.Duration.from('PT0S').negated().toString());

-PT8H45M PT8H45M PT8H45M PT0S

// Wichtig · Fallstricke

Browser-Unterstützung: Temporal ist noch nicht Baseline. Es wird ab Firefox 139 und Chrome/Edge 144 unterstützt, Safari unterstützt es derzeit nicht. In Produktivumgebungen braucht man meist einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill.
negated() ist nicht dasselbe wie abs(). negated() macht aus einer negativen Dauer eine positive und aus einer positiven eine negative. abs() liefert immer eine positive Dauer.
Es findet kein Ausgleich (Balancing) statt. Wer { minutes: 90 } negiert, bekommt { minutes: -90 } und nicht -PT1H30M. Zum Normalisieren verwendet man round().
Eine Temporal.Duration kann keine gemischten Vorzeichen enthalten. Deshalb ist das Negieren immer eindeutig und erzeugt nie einen RangeError.
date.add(d.negated()) entspricht date.subtract(d). Die Variante mit subtract() ist meist besser lesbar.

Siehe auch

Temporal.Duration.prototype.abs() Temporal.Duration.prototype.sign Temporal.Duration.prototype.blank Temporal.Duration.prototype.subtract() Temporal.Duration.prototype.round() Temporal.Duration