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

Temporal.Instant.prototype.until()メソッドは、あるTemporal.Instantオブジェクトから別のTemporal.Instantオブジェクトまでの期間（時間差）を計算するメソッドです。

Temporal.Instantは、日付やタイムゾーン情報を含まず、協定世界時（UTC）のエポックからの経過時間として特定の瞬間を表現するオブジェクトです。このため、タイムゾーンに依存しない絶対的な時点を示します。このメソッドは、呼び出し元のインスタンスから、引数として指定された別のTemporal.Instantインスタンスまでの時間を計測します。

引数には、比較対象となるTemporal.Instantオブジェクトに加え、オプションとして期間の計算単位やオーバーフローの処理方法などを細かく制御するためのオブジェクトを渡すことができます。これにより、例えば「秒単位で期間を求めるが、小数点以下は切り捨てる」といった柔軟な指定が可能です。

計算結果は、年、月、日、時間、分、秒、ミリ秒、マイクロ秒、ナノ秒といった各時間単位で期間の長さを保持するTemporal.Durationオブジェクトとして返されます。

この機能は、システムの処理時間のベンチマーク、イベント間の厳密な時間間隔の測定、期限までの残り時間の計算など、タイムゾーンの影響を受けない正確な時間差が必要なアプリケーション開発において非常に役立ちます。開発者はこのメソッドを活用することで、時間に関する複雑な計算を簡潔かつ正確に実装できるようになります。

Copy
1const instant1 = Temporal.Instant.from('2023-01-01T00:00:00Z');
2const instant2 = Temporal.Instant.from('2023-01-01T01:30:00Z');
3const duration = instant1.until(instant2);

other, options = {}

• other: Temporal.Instant: 比較対象となるTemporal.Instantオブジェクト
• options: object = {}: オプションを指定するオブジェクト。以下のプロパティを持つことができます。
  • largestUnit: "year", "quarter", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond": 結果の単位として使用する最大の単位を指定します。
  • smallestUnit: "year", "quarter", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond": 結果の単位として使用する最小の単位を指定します。
  • roundingMode: "ceil", "floor", "trunc", "half-expand": 丸めモードを指定します。
  • roundingIncrement: number: 丸めの増分を指定します。

Temporal.Duration

Temporal.Instant.prototype.until() メソッドは、呼び出し元である Temporal.Instant オブジェクトから引数として渡された Temporal.Instant オブジェクトまでの期間を Temporal.Duration オブジェクトとして返します。