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

Temporal.PlainYearMonth.prototype.until()メソッドは、あるTemporal.PlainYearMonthオブジェクトから別のTemporal.PlainYearMonthオブジェクトまでの期間を計算し、その差をTemporal.Durationオブジェクトとして取得するメソッドです。

Temporal.PlainYearMonthは、日付の中の年と月のみを厳密に表現するオブジェクトであり、日、時間、タイムゾーンといった詳細な情報を含みません。このuntil()メソッドは、このような年と月という単位で、二つのPlainYearMonthオブジェクト間の隔たりを算出する際に利用されます。

具体的には、このメソッドを呼び出す側のPlainYearMonthインスタンスが開始点となり、引数として渡される別のPlainYearMonthインスタンスが終了点となります。例えば、「2023年4月」から「2025年6月」までの期間がどのくらいかを計算したい場合に、このuntil()メソッドを使用することができます。

返されるTemporal.Durationオブジェクトには、計算された年や月の差が保持されます。また、このメソッドにはオプション引数として、期間を計算する際の最大の単位（例えば 'years' や 'months' を指定する largestUnit オプション）や、丸め方（roundingMode オプション）などを指定するオブジェクトを渡すことができます。これにより、求めたい期間を「2年と2ヶ月」のように、より柔軟に表現することが可能です。

システムエンジニアリングにおいて、日付や時刻を扱う場面は多岐にわたりますが、年月の期間計算は特に重要です。このuntil()メソッドは、時間情報を含まない年月の期間を正確かつ簡潔に扱うための、非常に便利な機能として活用されます。

Copy
1const plainYearMonth = new Temporal.PlainYearMonth(2023, 1);
2const otherPlainYearMonth = new Temporal.PlainYearMonth(2024, 6);
3
4const duration = plainYearMonth.until(otherPlainYearMonth);

other, options = {}

• other: Temporal.PlainYearMonth: 比較対象となる別の Temporal.PlainYearMonth オブジェクト
• options: object = {}: オプションを指定するオブジェクト（省略可能）

Temporal.Duration

このメソッドは、呼び出し元の Temporal.PlainYearMonth オブジェクトと引数で指定された Temporal.PlainYearMonth オブジェクトの間の期間を表す Temporal.Duration オブジェクトを返します。