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

Temporal.Duration.prototype.subtract()メソッドは、JavaScriptの新しい日付と時刻APIであるTemporalが提供する、期間を扱うTemporal.Durationクラスのインスタンスに対して、別の期間を減算するためのメソッドです。

このメソッドは、呼び出し元のTemporal.Durationインスタンス（減算される側）から、引数として渡されたTemporal.Durationインスタンス（減算する側）の期間を差し引きます。減算は、年、月、週、日、時間、分、秒、ミリ秒、マイクロ秒、ナノ秒といった、期間を構成するそれぞれの時間単位ごとに数値的に行われます。例えば、「3日と5時間」の期間から「1日と2時間」を引くと、「2日と3時間」を表す新しいDurationオブジェクトが生成されます。

この操作の重要な特徴は、元のTemporal.Durationインスタンスは変更されず、常に減算結果を保持する新しいTemporal.Durationインスタンスが返される「不変性」にあります。これにより、既存の期間データが意図せず変更されることを防ぎ、アプリケーションの信頼性とコードの見通しを向上させることができます。

システム開発において、ある処理に要した期間から特定の待機時間を差し引く、または複数の期間の差分を正確に計算する際など、期間の調整が必要な様々な場面でこのメソッドが活用されます。引数にはTemporal.Durationオブジェクトを渡し、他の型の値は受け付けません。ただし、このメソッドは日付のコンテキスト（開始日や終了日）を持たないため、月や年といった日数が可変の単位を含む期間の減算では、純粋な期間の構成要素としての数値計算が行われます。そのため、例えば「ある特定の日付から見て何ヶ月前」といった暦日ベースの厳密な計算が必要な場合は、他のTemporalオブジェクト（Temporal.InstantやTemporal.ZonedDateTimeなど）と組み合わせて使用することが推奨されます。

Copy
1const durationInstance = Temporal.Duration.from({ hours: 2, minutes: 30 });
2const otherDurationLike = Temporal.Duration.from({ minutes: 45 });
3
4const resultDuration = durationInstance.subtract(otherDurationLike);

other, options = {}

• other: Temporal.Duration | temporal-plain-date, duration: 減算する期間または日付を指定します。
• options: object = {}: 減算の動作を制御するオプションを指定します。

Temporal.Duration

このメソッドは、現在の Temporal.Duration オブジェクトから別の Temporal.Duration オブジェクトで表される期間を減算した結果を、新しい Temporal.Duration オブジェクトとして返します。