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

Temporal.ZonedDateTime.prototype.subtract()メソッドは、指定された期間を現在のTemporal.ZonedDateTimeオブジェクトから減算し、その結果として新しいTemporal.ZonedDateTimeオブジェクトを生成するメソッドです。このメソッドを使用することで、特定の日時とタイムゾーンの組み合わせから、一定の期間だけ過去の日時を正確に計算できます。

引数としては、減算したい期間を表すオブジェクトを受け取ります。この期間は、Temporal.Durationオブジェクトのインスタンスであるか、あるいは年、月、日、時間などの各単位で期間を指定するプレーンなJavaScriptオブジェクトの形式で渡すことが可能です。例えば、「3日と12時間」や「2ヶ月」といった期間を指定できます。

このメソッドが返すのは、計算結果を示す新しいTemporal.ZonedDateTimeオブジェクトであり、元のTemporal.ZonedDateTimeオブジェクトは一切変更されません。これは、JavaScriptのTemporal APIがイミュータブル（不変）なオブジェクトを扱う設計になっているためです。計算時には、対象となるタイムゾーンの夏時間（サマータイム）の切り替わりやうるう秒などのルールが自動的に考慮されるため、複雑な日付と時刻の減算処理も正確に行うことができます。この機能は、スケジュールの管理やイベントの逆算など、タイムゾーンを考慮した厳密な日時計算が必要なアプリケーション開発において非常に役立ちます。

Copy
1const initialZonedDateTime = Temporal.ZonedDateTime.from('2023-10-27T10:00:00[America/New_York]');
2const durationToSubtract = { hours: 5, minutes: 30 };
3const resultZonedDateTime = initialZonedDateTime.subtract(durationToSubtract);

durationLike

• durationLike: 減算する期間を指定するオブジェクト。Temporal.Duration、または期間を表すオブジェクトリテラル（例: { years: 1, months: 2 }）を指定できます。

Temporal.ZonedDateTime

このメソッドは、指定された期間を元の Temporal.ZonedDateTime オブジェクトから減算した結果として、新しい Temporal.ZonedDateTime オブジェクトを返します。