【JavaScript ECMAScript】Temporal::Temporal.Duration.prototype.negatedインスタンスメソッドの使い方

Temporal.Duration.prototype.negated()メソッドは、Temporal.Durationオブジェクトが表す時間量の符号を反転させた新しいTemporal.Durationオブジェクトを生成し、返すメソッドです。

このメソッドは、呼び出し元のTemporal.Durationインスタンスが保持する年、月、週、日、時間、分、秒、ミリ秒、マイクロ秒、ナノ秒といった各時間単位の値の符号を反転させます。例えば、正の時間量（例: 5時間30分）であれば負の時間量（例: -5時間-30分）に、負の時間量（例: -2日）であれば正の時間量（例: 2日）に変換されます。

negated()メソッドの重要な特徴は、元のTemporal.Durationオブジェクトの内部状態を一切変更しない点です。常に、符号が反転された全く新しいTemporal.Durationインスタンスを生成して返します。これにより、元の期間情報が誤って変更される心配がありません。

この機能は、時間量の加算や減算を行う際に、特定の期間を「差し引く」という意図で扱いたい場合や、時間経過の方向を逆転させて表現したい場合に非常に役立ちます。Temporal APIが提供する期間操作の柔軟性を高めるための重要なメソッドの一つであり、正確な時間管理を必要とするシステム開発において、時間量の符号を効率的に制御する手段を提供します。

Copy
1const duration = Temporal.Duration.from({ hours: 1, minutes: 30 });
2const negatedDuration = duration.negated();

引数なし

引数はありません

Temporal.Duration

このメソッドは、元の Temporal.Duration オブジェクトの各成分（年、月、日、時、分、秒、ミリ秒、マイクロ秒、ナノ秒）を反転させた新しい Temporal.Duration オブジェクトを返します。