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

Temporal.ZonedDateTime.prototype.since()メソッドは、Temporal.ZonedDateTimeオブジェクトのインスタンスに対して呼び出され、別のTemporal.ZonedDateTimeオブジェクトとの間の時間的な隔たり、すなわち期間を計算し、その結果をTemporal.Durationオブジェクトとして返すメソッドです。

このメソッドは、タイムゾーン情報を持つ特定の日付と時刻の組み合わせである二つのZonedDateTimeインスタンスを受け取り、それらの間にある時間的な差を正確に算出します。計算される期間は、メソッドを呼び出す側のZonedDateTimeから、引数として渡されるZonedDateTimeまでの時間の長さを表します。もし呼び出し元の時刻が引数の時刻よりも後の場合、計算される期間は正の値となり、逆に呼び出し元の時刻が引数の時刻よりも前の場合には負の値となります。

期間の計算においては、オプションオブジェクトを通じて様々な設定を行うことができます。例えば、期間を計算する際の最大の単位を年、月、日、時間、分、秒などから指定したり、期間の端数処理の方法（切り上げ、切り捨て、最も近い値への丸めなど）を細かく制御したりすることが可能です。これにより、特定のビジネスロジックや表示要件に合わせた柔軟な期間計算を実現できます。

システム開発において、タイムゾーンを意識した正確な日付時刻間の期間を測定する必要がある場合に非常に有用です。たとえば、イベント間の経過時間の測定、特定のタスクの実行期間の算出、会計処理における期間計算など、タイムゾーンを伴う複雑な日付時刻の差分計算を堅牢に行う際に活用されます。

Copy
1const startDateTime = Temporal.ZonedDateTime.from('2023-01-01T00:00:00[Europe/Berlin]');
2const endDateTime = Temporal.ZonedDateTime.from('2023-01-02T10:30:00[Europe/Berlin]');
3
4const durationResult = startDateTime.since(endDateTime);

other, options = {}

• other: Temporal.ZonedDateTime: 比較対象となる別のTemporal.ZonedDateTimeオブジェクト
• options: object = {}: オプションを指定するオブジェクト。以下のプロパティを指定できます。
  • largestUnit: "auto", "nanosecond", "microsecond", "millisecond", "second", "minute", "hour", "day", "week", "month", "year", "decade", "century", "millennium": 期間の最大単位を指定します。デフォルトは "auto" です。
  • smallestUnit: "auto", "nanosecond", "microsecond", "millisecond", "second", "minute", "hour", "day", "week", "month", "year", "decade", "century", "millennium": 期間の最小単位を指定します。デフォルトは "auto" です。
  • regularization: "basic", "compatible": 期間の正規化方法を指定します。デフォルトは "basic" です。

Temporal.Duration

このメソッドは、2つの Temporal.ZonedDateTime オブジェクト間の差を Temporal.Duration オブジェクトとして返します。