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

Temporal.Instant.prototype.add()メソッドは、既存のTemporal.Instantオブジェクトに指定された期間を加算し、その結果として新しいTemporal.Instantオブジェクトを生成して返すメソッドです。Temporal.Instantは、グリニッジ標準時（GMT）の1970年1月1日0時0分0秒からの経過時間をナノ秒精度で表す絶対的な「瞬間」の値であり、特定のタイムゾーンに依存しない特性を持っています。

このメソッドを利用することで、ある瞬間から特定の時間量だけ未来の瞬間を計算するといった操作を簡単に行えます。引数として、加算したい期間を表すTemporal.Durationオブジェクトを指定します。Temporal.Durationオブジェクトは、年、月、日、時間、分、秒、ミリ秒、マイクロ秒、ナノ秒などの要素を用いて、柔軟な期間を表現することが可能です。

特筆すべきは、このadd()メソッドが元のTemporal.Instantオブジェクト自体を変更せず、常に加算結果として新しいTemporal.Instantオブジェクトを返す点です。これは、Temporal APIにおけるオブジェクトの不変性（イミュータブル）という重要な設計原則に基づいています。また、Temporal.Instantはタイムゾーン情報を持たないため、このメソッドによる加算もタイムゾーンを考慮しません。もし、タイムゾーンを考慮した日付や時刻の計算が必要な場合は、Temporal.ZonedDateTimeなど、タイムゾーン情報を持つ他のTemporalオブジェクトの使用を検討することが適切です。このメソッドは、タイムゾーンに影響されない純粋な時間間隔の計算において、非常に正確で信頼性の高い機能を提供します。

Copy
1const baseInstant = Temporal.Instant.from('2023-10-27T10:00:00Z');
2const futureInstant = baseInstant.add({ days: 1, hours: 3, minutes: 15 });

duration

• duration: Temporal.Duration: 追加する期間を指定する Temporal.Duration オブジェクト

Temporal.Instant

指定された時間間隔を加算した、新しいTemporal.Instantオブジェクトを返します。