モジュール java.base
パッケージ java.util

クラスCalendar

java.lang.Object
java.util.Calendar
すべての実装されたインタフェース:
Serializable, Cloneable, Comparable<Calendar>
直系の既知のサブクラス:
GregorianCalendar
public abstract class Calendar extends Object implements Serializable, Cloneable, Comparable<Calendar>
Calendarクラスは、特定の時点とYEAR、MONTH、DAY_OF_MONTH、HOURなどのカレンダ・フィールド・セット間の変換、および次週の日付の取得などのカレンダ・フィールド操作を行うための抽象クラスです。 特定のインスタントは、1970年1月1日00:00:00.000 GMT (グレゴリオ暦)を元期とするミリ秒単位のオフセットで表現できます。

このクラスは、パッケージ外部の具象暦体系を実装するための追加メソッドおよびフィールドも提供します。 これらのフィールドおよびメソッドは、protectedとして定義されます。

ロケールに依存するほかのクラスと同じように、Calendarでは、この種の一般に役立つオブジェクトを得るためのクラス・メソッドgetInstanceが提供されます。 CalendarのgetInstanceメソッドは、Calendarオブジェクトを返しますが、このカレンダ・フィールドは現在の日付と時間に初期化されています。 

     Calendar rightNow = Calendar.getInstance();

Calendarオブジェクトでは、特定の言語およびカレンダ・スタイル(日本のグレゴリオ暦、日本の旧暦など)に対して、日付と時間のフォーマットを行うときに必要なすべての時間フィールド値を生成できます。 Calendarでは、特定のフィールドとその意味の両方によって返される値の範囲が定義されます。 たとえば、暦体系の最初の月には、すべてのカレンダについて値MONTH == JANUARYがあります。 ほかの値は、ERAなどの具象サブクラスで定義されます。 詳細は、個別のフィールド・ドキュメントおよびサブクラス・ドキュメントを参照してください。

カレンダ・フィールド値の取得と設定

カレンダ・フィールド値は、setメソッドを呼び出して設定できます。 Calendar内で設定されたフィールド値はすべて、その時間値(「元期」からのミリ秒)またはカレンダ・フィールドの値を計算する必要が生じるまで解釈されません。 get、getTimeInMillis、getTime、add、およびrollの呼出しでは、この種の計算が行われます。 特に指定されていないかぎり、パラメータint fieldを含むCalendarメソッドは、指定されたフィールドが(field < 0 || field >= FIELD_COUNT)の範囲外である場合にArrayIndexOutOfBoundsExceptionをスローします。

非厳密性

Calendarは、カレンダ・フィールドを解釈する際、厳密および非厳密の2つのモードを使用します。 非厳密モードの場合、Calendarはそれ自身が生成する値よりも広範なカレンダ・フィールド値を受け入れます。 Calendarが、get()の値を返すためにカレンダ・フィールド値を再計算する際、すべてのカレンダ・フィールドが正規化されます。 たとえば、非厳密なGregorianCalendarは、MONTH == JANUARY、DAY_OF_MONTH == 32を2月1日として解釈します。

厳密モードの場合、カレンダ・フィールド内に不一致があると、Calendarは例外をスローします。 たとえば、GregorianCalendarは、DAY_OF_MONTH値として1とその月の長さの間の値を常に生成します。 厳密なGregorianCalendarは、時間およびカレンダ・フィールド値を計算する際、範囲外のフィールド値が設定されていると例外をスローします。

最初の週

Calendar週の最初の日および最初の週の最小日数(1から7)という2つのパラメータを使用して、ロケール固有の週7日が定義されます。 これらの番号は、Calendarが構築されたときのロケール・リソース・データまたはロケール自体から取得されます。 指定されたロケールに"fw"または"rg" 「Unicode拡張」(あるいはその両方)が含まれる場合、それらの拡張に従って週の初日が取得されます。 "fw"と"rg"の両方が指定されている場合、"fw"拡張子の値は、"rg"拡張子の暗黙のものよりも優先されます。 また、これらの値の設定用メソッドによって明示的に指定されることもあります。

WEEK_OF_MONTHフィールドやWEEK_OF_YEARフィールドを設定または取得すると、Calendarでは月または年の最初の週を参照点として決定する必要があります。 月または年の最初の週は、getFirstDayOfWeek()で始まり、その月または年の少なくともgetMinimalDaysInFirstWeek()の日数を含む、もっとも早い7日間として定義されます。 ...、-1、0という番号が付けられた週は最初の週より前にあります。2、3、...という番号が付けられた週はそれより後ろにあります。 get()によって返される正規化された番号付けとは、異なる場合があります。 たとえば、特定のCalendarサブクラスでは、1年の週1の前の週を、前年の週nとして指定することがあります。

カレンダ・フィールドの解決

カレンダ・フィールドから日付および時間を計算する際、計算に必要な情報が不足している(年と月だけで日がないなど)、または情報に一貫性がない場合(たとえば「Tuesday, July 15, 1996 (Gregorian)」と指定されているが、実際にはJuly 15, 1996はMondayであるなど)があります。 Calendarは、次の方法でカレンダ・フィールド値を解決し、日付および時間を判定します。

カレンダ・フィールドの値に競合がある場合は、Calendarにより、最近設定されたカレンダ・フィールドに優先度が付与されます。 次に、カレンダ・フィールドのデフォルト組合せを示します。 もっとも最近に設定されたフィールドによって判定される、最新の組み合わせが使用されます。

日付フィールドの場合: 

 YEAR + MONTH + DAY_OF_MONTH
 YEAR + MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
 YEAR + MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
 YEAR + DAY_OF_YEAR
 YEAR + DAY_OF_WEEK + WEEK_OF_YEAR
時間フィールドの場合: 
 HOUR_OF_DAY
 AM_PM + HOUR

選択したフィールドの組み合わせで値が設定されていないカレンダ・フィールドが存在する場合、Calendarはデフォルト値を使用します。 各フィールドのデフォルト値は、具象暦体系により異なります。 GregorianCalendarの場合、フィールドのデフォルト値は、その元期の初めの値です。つまり、YEAR = 1970、MONTH = JANUARY、DAY_OF_MONTH = 1などです。

ノート: 一部の特別な時間では、その解釈があいまいになることもあります。その場合は、次のように解決されます。

  1. 23:59は一日の最後の分で、00:00は翌日の最初の分になります。 したがって、1999年12月31日23:59 < 2000年1月1日00:00 < 2000年1月1日00:01となります。
  2. 歴史的には明確ではありませんが、深夜零時は「am」に、正午は「pm」に属します。したがって、同じ日の中では12:00 am (深夜零時)< 12:01 am、および12:00 pm (正午)< 12:01 pmとなります

日付や時間のフォーマット文字列は、カレンダの定義の一部ではありません。これらが実行時にユーザーによって修正可能で、オーバーライド可能である必要があるためです。 日付の書式設定には、DateFormatを使用してください。

フィールド操作

カレンダ・フィールドは、set()、add()、およびroll()。

set(f, value)では、カレンダ・フィールドfがvalueに変更されます。 さらに、カレンダ・フィールドfが変更されたことを示すように内部メンバー変数が設定されます。 カレンダ・フィールドfはただちに変更されますが、カレンダの時間値(ミリ秒)は、get()、getTime()、getTimeInMillis()、add()、またはroll()が次に呼び出されるまで再計算されません。 このように、set()を複数回呼び出しても、不要な計算が行われることはありません。 set()を使用してカレンダ・フィールドを変更すると、カレンダ・フィールド、カレンダ・フィールド値、および暦体系によってほかのフィールドも変更されることがあります。 さらに、get(f)では、カレンダ・フィールドの再計算後に、setメソッドを呼び出して設定されたvalueが必ず返されるとは限りません。 これらの詳細は、具象カレンダ・クラスによって決定されます。

例: 1999年8月31日に当初設定されたGregorianCalendarを考えます。 set(Calendar.MONTH, Calendar.SEPTEMBER)を呼び出すと、日付が1999年9月31日に設定されます。 これは一時的な内部表現であり、getTime() を呼び出すと1999年10月1日になります。 ただし、getTime()を呼び出す前にset(Calendar.DAY_OF_MONTH, 30)を呼び出すと、set()自体のあとに再計算が行われるために、日付が1999年9月30日に設定されます。

add(f, delta)では、フィールドfにdeltaが追加されます。 これは、2つの調整によってset(f, get(f)+delta)を呼び出すのと同じです。

Addルール1。 呼出しがフィールドfで発生したモジュロ・オーバーフローdeltaになる前に、呼出しでフィールドfの値を引いたあとのフィールドfの値です。 オーバーフローは、フィールドの値が範囲を超え、その結果、次の大きいフィールドが増分または減分されて、フィールドの値がその範囲に入るよう調整された場合に発生します。

Addルール2。 小さいフィールドが不変式であると予想される場合に、フィールドfが変更されてから最小値または最大値が変更された、またはタイムゾーン・オフセットの変更などのほかの制約のために、その前の値と等しくならないと、フィールドの値はその予想される値にできるだけ近くなるように調整されます。 小さいフィールドは、小さい時間の単位を表します。 HOURはDAY_OF_MONTHよりも小さいフィールドです。 不変式ではないと予想される小さいフィールドは、調整されません。 暦体系では、不変式であると予想されるフィールドが判断されます。

さらに、set()とは異なり、add()ではカレンダのミリ秒およびすべてのフィールドがただちに強制的に再計算されます。

例: 最初に1999年8月31日に設定されたGregorianCalendarを考えます。 add(Calendar.MONTH, 13)を呼び出すと、カレンダが2000年9月30日に設定されます。 8月に13か月を追加すると翌年の9月になるため、Addルール1によってMONTHフィールドが9月に設定されます。 DAY_OF_MONTHはGregorianCalendarでは9月の31日にはできないため、Addルール2によってDAY_OF_MONTHがもっとも近い可能な値の30に設定されます。 これは小さいフィールドですが、GregorianCalendarで月が変更されるときに変更が予定されているため、DAY_OF_WEEKはルール2によっては調整されません。

roll(f, delta)では、大きいフィールドを変更せずにフィールドfにdeltaが追加されます。 これは、以下の調整によってadd(f, delta)を呼び出すのと同じです。

Rollルール。 呼出しのあと、大きいフィールドは変更されません。 大きいフィールドは、大きい時間の単位を表します。 DAY_OF_MONTHはHOURよりも大きいフィールドです。

例: GregorianCalendar.roll(int, int)を参照してください。

使用法モデル。 add()およびroll()の動作を動機付けするために、月、日、年、および基本となるGregorianCalendarの増分ボタンと減分ボタンがあるユーザー・インタフェース・コンポーネントを考えます。 インタフェースで1999年1月31日が読み込まれ、ユーザーが月増分ボタンを押すと、何が読み込まれるでしょうか。 基本となる実装でset()が使用される場合は、1999年3月3日が読み込まれます。 1999年2月28日となる方がよい結果です。 さらに、ユーザーが月増分ボタンを再度押した場合は、1999年3月28日ではなく、1999年3月31日が読み込まれるはずです。 元の日付を保存し、大きいフィールドが影響を受けるかどうかによってadd()またはroll()を使用することで、ユーザー・インタフェースはほとんどのユーザーが直観的に期待するとおりに動作できます。

導入されたバージョン:
1.1
関連項目: