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

Temporal.ZonedDateTime.prototype.withCalendar()メソッドは、既存のTemporal.ZonedDateTimeオブジェクトの暦法（カレンダーシステム）を変更し、新しいTemporal.ZonedDateTimeオブジェクトを生成するメソッドです。

Temporal.ZonedDateTimeオブジェクトは、特定の日時、タイムゾーン、そして日時をどのように解釈し表示するかを決定する暦法（カレンダーシステム）の3つの要素を持っています。このメソッドは、引数として指定された新しい暦法を受け取り、元のZonedDateTimeオブジェクトの持つ日時とタイムゾーンを保持したまま、その暦法を置き換えます。

例えば、現在グレゴリオ暦で表現されている日時を、和暦やその他の暦法で表現したい場合にこのメソッドが役立ちます。元のZonedDateTimeオブジェクトが指す地球上での特定の瞬間（タイムスタンプ）は変わりませんが、新しい暦法に基づいて年、月、日などの日付フィールドの値が再計算され、異なる表現のZonedDateTimeオブジェクトが返されます。

このメソッドは元のZonedDateTimeオブジェクトを直接変更するのではなく、常に新しいインスタンスを返します。そのため、元のオブジェクトのデータは安全に保たれます。多様な暦法間で日時を柔軟に扱いたいシステムにおいて、正確な日時情報を維持しつつ表示形式を切り替える際に非常に有用です。

Copy
1const zonedDateTime = Temporal.ZonedDateTime.from('2023-10-26T10:00:00+02:00[Europe/Berlin]');
2const newZonedDateTime = zonedDateTime.withCalendar('japanese');

calendar

• calendar: Temporal.CalendarLike: 新しいカレンダーを指定します。Temporal.CalendarLike は、Temporal.Calendar オブジェクト、またはカレンダー名を表す文字列、またはカレンダーのメソッドを実装したオブジェクトのいずれかです。

Temporal.ZonedDateTime

このメソッドは、呼び出し元の Temporal.ZonedDateTime オブジェクトのコピーを返します。このコピーは、指定されたカレンダーを使用して、元のオブジェクトと同じ時点を表します。