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

Temporal.PlainYearMonth.prototype.subtract()メソッドは、特定の「年」と「月」のみを表現するTemporal.PlainYearMonthオブジェクトから、指定された期間を減算して新しいTemporal.PlainYearMonthオブジェクトを生成するメソッドです。このメソッドは、現在保持している年月情報から、引数として渡されるTemporal.Durationオブジェクト、または期間を表す文字列やオブジェクトで指定された期間（年、月、週、日など）を減らします。

例えば、ある年月から数ヶ月前、あるいは数年前の年月を計算したい場合に非常に有用です。引数には、減算したい期間を正確に記述したTemporal.Durationインスタンスを渡すことが一般的です。このメソッドの大きな特徴は、元のTemporal.PlainYearMonthオブジェクト自体を変更しない「イミュータブル」な操作である点です。減算の結果は常に新しいTemporal.PlainYearMonthオブジェクトとして返されるため、元のデータが意図せず変更される心配がありません。

システム開発において、例えば請求サイクルの遡及計算や、過去のデータ集計期間の指定など、日付と月の期間を柔軟に操作する必要がある場面で活用されます。日付や時刻の複雑な計算を正確かつ安全に行うためのTemporal APIの一部として、初心者の方でも直感的に使えるよう設計されています。これにより、複雑な日付計算のロジックを簡潔に記述し、バグのリスクを低減することができます。

Copy
1const plainYearMonth = Temporal.PlainYearMonth.from('2023-05');
2const newPlainYearMonth = plainYearMonth.subtract({ years: 1, months: 2 });

durationLike, options

• durationLike: 減算する期間を指定します。Temporal.Durationオブジェクト、または年、月、週、日数、時間、分、秒、ミリ秒、マイクロ秒、ナノ秒のいずれかのプロパティを持つオブジェクトを指定できます。
• options: オプションを指定するオブジェクトです。overflow プロパティで、オーバーフロー時の処理方法を指定できます (例: "reject" または "constrain")。

Temporal.PlainYearMonth

指定された期間を減算した新しい Temporal.PlainYearMonth オブジェクトを返します。