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

Temporal.ZonedDateTime.prototype.add()メソッドは、タイムゾーン情報を持つ特定の日時を表すTemporal.ZonedDateTimeオブジェクトに、指定された期間を加算し、新しいTemporal.ZonedDateTimeオブジェクトを生成するメソッドです。このメソッドを使用することで、現在の日時を基準に、将来の特定の日時を正確に計算することが可能になります。例えば、今日の3ヶ月後の日付や、現在の時刻の5時間後の時刻などを、タイムゾーンを考慮した上で簡単に求めることができます。

特に、サマータイムのようなタイムゾーンのルール変更が発生する期間をまたがる計算や、異なるタイムゾーン間での日時計算が必要な場合に、このメソッドは非常に有用です。開発者は、複雑なタイムゾーンのロジックを自身で実装することなく、標準化された方法で堅牢な日時計算を行えます。

add()メソッドは、元のTemporal.ZonedDateTimeオブジェクトの内容を変更しない「不変性（イミュータビリティ）」の原則に従います。つまり、このメソッドを呼び出すたびに、加算結果を表す新しいTemporal.ZonedDateTimeオブジェクトが返され、元のオブジェクトはそのままの状態を保持します。これにより、プログラムの予期せぬ副作用を防ぎ、より安全で予測可能なコードの記述を促進します。引数にはTemporal.Durationオブジェクト、またはそれに変換可能なオブジェクトを指定します。

Copy
1const zonedDateTimeInstance = Temporal.ZonedDateTime.from('2023-01-01T10:00:00[America/New_York]');
2const newZonedDateTime = zonedDateTimeInstance.add({ hours: 1, minutes: 30 });

durationLike, options

• durationLike: 追加する期間を表すオブジェクト。Temporal.Duration、または年、月、週、日、時、分、秒、ミリ秒、マイクロ秒、ナノ秒を表す数値プロパティを持つオブジェクト。
• options: オプションを指定するオブジェクト。largestUnit (追加する期間の最大の単位) や smallestUnit (追加する期間の最小の単位) などを指定できます。

Temporal.ZonedDateTime

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