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

Temporal.PlainDateTime.prototype.until()メソッドは、Temporal.PlainDateTimeのインスタンスに適用され、ある日付と時刻から別の特定の日付と時刻までの期間を計算するメソッドです。具体的には、このメソッドを呼び出したPlainDateTimeオブジェクトから、引数として渡された別のPlainDateTimeオブジェクトまでの時間の隔たりを測定します。その結果は、年、月、日、時間、分、秒、ミリ秒などの各要素からなるTemporal.Durationオブジェクトとして返されます。

このメソッドは、比較対象となるPlainDateTimeインスタンスを必須の引数として受け取ります。さらに、期間の計算単位（例えば、年単位で差を出すか、日単位で差を出すか）や、計算結果の丸め方を指定するためのオプションオブジェクトも任意で受け入れることができます。これにより、例えばイベントまでの残り期間を正確に「X年Yヶ月Z日」として求めたり、タスクの開始から完了までの経過時間を「A時間B分C秒」として算出したりする際に非常に便利です。複雑な日付時刻の差分計算を、開発者が手動で行うことなく、信頼性と高い精度で実行できるため、システムのスケジュール管理やリマインダー機能の実装などで活用されます。

Copy
1const plainDateTime = new Temporal.PlainDateTime(2023, 1, 1);
2const otherPlainDateTime = new Temporal.PlainDateTime(2023, 1, 15);
3
4// Temporal.PlainDateTime.prototype.until() の構文例
5plainDateTime.until(otherPlainDateTime, { largestUnit: 'day' });

other, options

• other: Temporal.PlainDateTime, Temporal.ZonedDateTime, Temporal.PlainDate, Temporal.ZonedDateTime.ISO, Temporal.PlainTime, Temporal.TimeZone, Temporal.Instant, Temporal.Duration, bigint, number, string: 期間の計算対象となる日時または時間、またはそれらを表現する値
• options: object = undefined: 期間の計算方法を制御するオプションオブジェクト

Temporal.Duration

Temporal.PlainDateTime.prototype.until() メソッドは、呼び出し元の Temporal.PlainDateTime オブジェクトと、引数として渡された別の Temporal.PlainDateTime オブジェクトとの間の時間的な差を Temporal.Duration オブジェクトとして返します。