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

Temporal.PlainDate.prototype.withCalendar()メソッドは、既存のTemporal.PlainDateオブジェクトに設定されている暦（カレンダー）を変更し、新しいTemporal.PlainDateオブジェクトを生成するメソッドです。このメソッドは、特定の日付を異なる暦体系で表現したり、処理したりする必要がある場合に非常に役立ちます。

例えば、現在ISO 8601暦で表現された日付を、和暦やグレゴリオ暦など、他の国際的な暦体系に変換して扱いたい場面で利用されます。メソッドが実行されると、元のTemporal.PlainDateオブジェクトが持つ年、月、日の情報は変更されずに保持されますが、その日付を解釈するための暦のシステムだけが指定されたものに切り替わります。

引数には、新しい暦を識別するための文字列（例えば、'iso8601'や'japanese', 'gregory'など）を渡すか、またはTemporal.Calendarのインスタンスを直接指定することができます。このメソッドの重要な特徴として、元のTemporal.PlainDateオブジェクトは一切変更されず、常に新しいTemporal.PlainDateオブジェクトが返される「不変性」が挙げられます。これにより、データの整合性を保ちながら、複数の暦体系が混在する複雑なアプリケーションにおいても、日付データを柔軟かつ安全に管理することが可能となります。

Copy
1const existingPlainDate = new Temporal.PlainDate(2023, 10, 26, 'iso8601');
2const newPlainDate = existingPlainDate.withCalendar('japanese');

calendar

• calendar: Temporal.CalendarLike: 新しい日付オブジェクトに適用するカレンダーを指定します。Temporal.Calendar, Temporal.TimeZone, またはカレンダー名を表す文字列を指定できます。

Temporal.PlainDate

このメソッドは、指定された日付の年、月、日、またはカレンダーを変更した新しいTemporal.PlainDateインスタンスを返します。元のインスタンスは変更されません。