java.util
类 GregorianCalendar

java.lang.Object
  java.util.Calendar
      java.util.GregorianCalendar

所有已实现的接口：

Serializable, Cloneable, Comparable<Calendar>

public class GregorianCalendar
extends Calendar

GregorianCalendar 是 Calendar 的一个具体子类，提供了世界上大多数国家/地区使用的标准日历系统。

GregorianCalendar 是一种混合日历，在单一间断性的支持下同时支持儒略历和格里高利历系统，在默认情况下，它对应格里高利日历创立时的格里高利历日期（某些国家/地区是在 1582 年 10 月 15 日创立，在其他国家/地区要晚一些）。可由调用者通过调用 setGregorianChange() 来更改起始日期。

历史上，在那些首先采用格里高利历的国家/地区中，1582 年 10 月 4 日（儒略历）之后就是 1582 年 10 月 15 日（格里高利历）。此日历正确地模拟了这些变化。在开始格里高利历之前，GregorianCalendar 实现的是儒略历。格里高利历和儒略历之间的唯一区别就是闰年规则。儒略历指定每 4 年就为闰年，而格里高利历则忽略不能被 400 整除的世纪年。

GregorianCalendar 可实现预期的 格里高利历和儒略历。也就是说，可以通过在时间上无限地向后或向前外推当前规则来计算日期。因此，对于所有的年份，都可以使用 GregorianCalendar 来生成有意义并且一致的结果。但是，采用现代儒略历规则时，使用 GregorianCalendar 得到的日期只在历史上从公元 4 年 3 月 1 日之后是准确的。在此日期之前，闰年规则的应用没有规则性，在 45 BC 之前，甚至不存在儒略历。

在格里高利历创立以前，新年是 3 月 25 日。为了避免混淆，此日历始终使用 1 月 1 日为新年。如果想要格里高利历转换之前并且处于 1 月 1 日和 3 月 24 日之间的日期，则可以进行手动调整。

为 WEEK_OF_YEAR 字段所计算的值的范围从 1 到 53。一年的第一个星期始于 getFirstDayOfWeek() 的最早 7 天，至少包含该年的 getMinimalDaysInFirstWeek() 各天。这取决于 getMinimalDaysInFirstWeek()、getFirstDayOfWeek() 的值以及 1 月 1 日是星期几。一年的第一个星期和下一年的第一个星期之间的各个星期按顺序从 2 到 52 或 53（根据需要）进行编号。

例如，1998 年 1 月 1 日是星期四。如果 getFirstDayOfWeek() 为 MONDAY，并且 getMinimalDaysInFirstWeek() 为 4（这些值反映了 ISO 8601 和很多国家/地区标准），则 1998 年的第一个星期开始于 1997 年 12 月 29 日，结束于 1998 年 1 月 4 日。但是，如果 getFirstDayOfWeek() 为 SUNDAY，那么 1998 年的第一个星期开始于 1998 年 1 月 4 日，结束于 1998 年 1 月 10 日；1998 年头三天是 1997 年第 53 个星期的一部分。

为 WEEK_OF_MONTH 字段所计算的值的范围从 0 到 6。一个月的第一个星期（WEEK_OF_MONTH = 1 的日期）是该月至少连续 getMinimalDaysInFirstWeek() 天中的最早日期，结束于 getFirstDayOfWeek() 的前一天。与一年的第一个星期不同，一个月的第一个星期可能短于 7 天，也不必从 getFirstDayOfWeek() 这一天开始，并且不包括前一个月的日期。在第一个星期之前该月日期的 WEEK_OF_MONTH 为 0。

例如，如果 getFirstDayOfWeek() 为 SUNDAY，getMinimalDaysInFirstWeek() 为 4，那么 1998 年 1 月的第一个星期是从 1 月 4 日星期日到 1 月 10 日星期六。这些天的 WEEK_OF_MONTH 为 1。1 月 1 日星期四到 1 月 3 日星期六的 WEEK_OF_MONTH 为 0。如果 getMinimalDaysInFirstWeek() 变为 3，则 1 月 1 日到 1 月 3 日的 WEEK_OF_MONTH 为 1。

clear 方法将日历字段设置为未定义。GregorianCalendar 为每个日历字段使用以下默认值（如果该值未定义）。

示例：

 // get the supported ids for GMT-08:00 (Pacific Standard Time)
 String[] ids = TimeZone.getAvailableIDs(-8 * 60 * 60 * 1000);
 // if no ids were returned, something is wrong. get out.
 if (ids.length == 0)
     System.exit(0);

  // begin output
 System.out.println("Current Time");

 // create a Pacific Standard Time time zone
 SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, ids[0]);

 // set up rules for daylight savings time
 pdt.setStartRule(Calendar.APRIL, 1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
 pdt.setEndRule(Calendar.0ctober, -1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);

 // create a GregorianCalendar with the Pacific Daylight time zone
 // and the current date and time
 Calendar calendar = new GregorianCalendar(pdt);
 Date trialTime = new Date();
 calendar.setTime(trialTime);

 // print out a bunch of interesting things
 System.out.println("ERA: " + calendar.get(Calendar.ERA));
 System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
 System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
 System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
 System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
 System.out.println("DATE: " + calendar.get(Calendar.DATE));
 System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
 System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
 System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
 System.out.println("DAY_OF_WEEK_IN_MONTH: "
                    + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
 System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
 System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
 System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
 System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
 System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
 System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
 System.out.println("ZONE_OFFSET: "
                    + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000)));
 System.out.println("DST_OFFSET: "
                    + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000)));

 System.out.println("Current Time, with hour reset to 3");
 calendar.clear(Calendar.HOUR_OF_DAY); // so doesn't override
 calendar.set(Calendar.HOUR, 3);
 System.out.println("ERA: " + calendar.get(Calendar.ERA));
 System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
 System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
 System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
 System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
 System.out.println("DATE: " + calendar.get(Calendar.DATE));
 System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
 System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
 System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
 System.out.println("DAY_OF_WEEK_IN_MONTH: "
                    + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
 System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
 System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
 System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
 System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
 System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
 System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
 System.out.println("ZONE_OFFSET: "
        + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000))); // in hours
 System.out.println("DST_OFFSET: "
        + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000))); // in hours
 

从以下版本开始：

JDK1.1

另请参见：

TimeZone, 序列化表格

BC

public static final int BC

ERA 字段的值指示公元前（Christ 前）的时期（也称为 BCE）。从 BC 到 AD 各年转换依次是 2 BC、1 BC、1 AD、2 AD……。

另请参见：

Calendar.ERA, 常量字段值

AD

public static final int AD

ERA 字段的值指示公元后（耶稣纪元后）的时期（也称为 CE）。从 BC 到 AD 各年转换依次是 2 BC、1 BC、1 AD、2 AD……。

另请参见：

Calendar.ERA, 常量字段值

GregorianCalendar

public GregorianCalendar()

在具有默认语言环境的默认时区内使用当前时间构造一个默认的 GregorianCalendar。

GregorianCalendar

public GregorianCalendar(TimeZone zone)

在具有默认语言环境的给定时区内构造一个基于当前时间的 GregorianCalendar。

参数：

zone - 给定的时区。

GregorianCalendar

public GregorianCalendar(Locale aLocale)

在具有给定语言环境的默认时区内构造一个基于当前时间的 GregorianCalendar。

参数：

aLocale - 给定的语言环境。

GregorianCalendar

public GregorianCalendar(TimeZone zone,
                         Locale aLocale)

在具有给定语言环境的给定时区内构造一个基于当前时间的 GregorianCalendar。

参数：

zone - 给定的时区。

aLocale - 给定的语言环境。

GregorianCalendar

public GregorianCalendar(int year,
                         int month,
                         int dayOfMonth)

在具有默认语言环境的默认时区内构造一个带有给定日期设置的 GregorianCalendar。

参数：

year - 用来在日历中设置 YEAR 日历字段的值。

month - 用来在日历中设置 MONTH 日历字段的值。Month 值是基于 0 的，例如，0 表示 1 月。

dayOfMonth - 用来在日历中设置 DAY_OF_MONTH 日历字段的值。

GregorianCalendar

public GregorianCalendar(int year,
                         int month,
                         int dayOfMonth,
                         int hourOfDay,
                         int minute)

为具有默认语言环境的默认时区构造一个具有给定日期和时间设置的 GregorianCalendar。

参数：

year - 用来在日历中设置 YEAR 日历字段的值。

month - 用来在日历中设置 MONTH 日历字段的值。Month 值是基于 0 的，例如，0 表示 1 月。

dayOfMonth - 用来在日历中设置 DAY_OF_MONTH 日历字段的值。

hourOfDay - 用来在日历中设置 HOUR_OF_DAY 日历字段的值。

minute - 用来在日历中设置 MINUTE 日历字段的值。

GregorianCalendar

public GregorianCalendar(int year,
                         int month,
                         int dayOfMonth,
                         int hourOfDay,
                         int minute,
                         int second)

为具有默认语言环境的默认时区构造一个具有给定日期和时间设置的 GregorianCalendar。

参数：

year - 用来在日历中设置 YEAR 日历字段的值。

month - 用来在日历中设置 MONTH 日历字段的值。Month 值是基于 0 的，例如，0 表示 1 月。

dayOfMonth - 用来在日历中设置 DAY_OF_MONTH 日历字段的值。

hourOfDay - 用来在日历中设置 HOUR_OF_DAY 日历字段的值。

minute - 用来在日历中设置 MINUTE 日历字段的值。

second - 用来在日历中设置 SECOND 日历字段的值。

setGregorianChange

public void setGregorianChange(Date date)

设置 GregorianCalendar 的更改日期。这是发生从儒略历日期切换到格里高利历日期的点。默认时间是 1582 年 10 月 15 日（格里高利历）。在此之前，日期是按照儒略历计算的。

要得到纯粹的儒略历日历，可将更改日期设置为 Date(Long.MAX_VALUE)。要得到一个纯粹的格里高利历日历，可将更改日期设置为 Date(Long.MIN_VALUE)。

参数：

date - 给定的格里高利历起始日期。

getGregorianChange

public final Date getGregorianChange()

获得格里高利历的更改日期。这是发生从儒略历日期切换到格里高利历日期的点。默认时间是 1582 年 10 月 15 日（格里高利历）。在此之前，日期是按照儒略历计算的。

返回：

此 GregorianCalendar 对象的格里高利历起始日期。

isLeapYear

public boolean isLeapYear(int year)

确定给定的年份是否为闰年。如果给定的年份是闰年，则返回 true。要指定 BC 年份，必须给定 1 - 年份。例如，指定 -3 为 BC 4 年。

参数：

year - 给定的年份。

返回：

如果给定的年份为闰年，则返回 true；否则返回 false。

equals

public boolean equals(Object obj)

比较此 GregorianCalendar 与指定的 Object。当且仅当参数是一个 GregorianCalendar 对象，并且这个对象表示在相同的 Calendar 参数和格里高利历更改日期下与此对象具有相同的时间值（从 Epoch 至现在的毫秒偏移量）时，结果为 true。

覆盖：

类 Calendar 中的 equals

参数：

obj - 要与之比较的对象。

返回：

如果此对象等于 obj，则返回 true；否则返回 false。

另请参见：

Calendar.compareTo(Calendar)

hashCode

public int hashCode()

生成此 GregorianCalendar 对象的哈希码。

覆盖：

类 Calendar 中的 hashCode

返回：

此对象的哈希码值。

另请参见：

Object.equals(java.lang.Object), Hashtable

add

public void add(int field,
                int amount)

根据日历规则，将指定的（有符号的）时间量添加到给定的日历字段中。

添加规则 1。调用之后的 field 字段的值减去调用之前的 field 字段的值等于 amount，以 field 中发生的任何溢出为模。溢出发生在字段值超出其范围时，结果，下一个更大的字段会递增或递减，字段值被调整回其范围内。

添加规则 2。如果期望某一个更小的字段是无变化的，但让它等于以前的值是不可能的，因为在字段 field 发生更改之后，它的最大值和最小值也在发生更改，然后它的值被调整为尽量接近于所期望的值。更小的字段表示一个更小的时间单元。HOUR 是一个比 DAY_OF_MONTH 更小的字段。对于不期望是无变化字段的更小字段，无需进行任何调整。日历系统确定期望是无变化字段的那些字段。

指定者：

类 Calendar 中的 add

参数：

field - 日历字段。

amount - 为字段添加的日期或时间量。

抛出：

IllegalArgumentException - 如果 field 为 ZONE_OFFSET、DST_OFFSET，或未知，或者任何日历字段在 non-lenient 模式下具有超出范围的值。

另请参见：

Calendar.roll(int,int), Calendar.set(int,int)

roll

public void roll(int field,
                 boolean up)

在给定的时间字段上添加或减去（上/下）单个时间单元，不更改更大的字段。

示例：考虑原来设置为 1999 年 12 月 31 日的 GregorianCalendar 。现在调用 roll(Calendar.MONTH, true) 将该日历设置为 1999 年 1 月 31 日。YEAR 字段未改变，因为它是一个比 MONTH 更大的字段。

指定者：

类 Calendar 中的 roll

参数：

up - 指出指定日历字段的值是上升还是下降。如果上升了，则使用 true；否则使用 false。

field - 时间字段。

抛出：

IllegalArgumentException - 如果 field 为 ZONE_OFFSET、DST_OFFSET，或未知，或者任何日历字段在 non-lenient 模式下具有超出范围的值。

另请参见：

add(int,int), Calendar.set(int,int)

roll

public void roll(int field,
                 int amount)

向指定日历字段添加有符号的时间量，不更改更大的字段。负的波动量表示从字段减去时间量，不更改更大的字段。如果指定的量为 0，则此方法不执行任何操作。

此方法在添加时间量前调用 Calendar.complete()，使得所有的日历字段都标准化。如果任何日历字段在 non-lenient 模式下具有超出范围的值，则抛出 IllegalArgumentException。

示例：考虑原来设置为 1999 年 8 月 31 日的 GregorianCalendar 。现在调用 roll(Calendar.MONTH, 8) 将该日历设置为 1999 年 4 月 30 日。如果使用 GregorianCalendar，则 4 月份的 DAY_OF_MONTH 字段不可能为 31。将 DAY_OF_MONTH 设置为最可能接近的值 30。YEAR 字段保持为值 1999，因为它是一个比 MONTH 更大的字段。

示例：考虑原来设置为 1999 年 6 月 6 日星期日的 GregorianCalendar 。现在调用 roll(Calendar.WEEK_OF_MONTH, -1) 将该日历设置为 1999 年 6 月 1 日星期二，而调用 add(Calendar.WEEK_OF_MONTH, -1) 则将日历设置为 1999 年 5 月 30 日星期日。这是因为上升和下降规则施加了其他的约束：WEEK_OF_MONTH 改变时 MONTH 必须不变。根据添加规则 1，所得日期必定在 6 月 1 日星期二和 6 月 5 日星期六之间。根据添加规则 2，DAY_OF_WEEK（在改变 WEEK_OF_MONTH 时它是一个不变量）被设置为 Tuesday，是最接近 Sunday 的可能值（其中星期日是一个星期的第一天）。

覆盖：

类 Calendar 中的 roll

参数：

field - 日历字段。

amount - 添加到 field 的有符号时间量。

抛出：

IllegalArgumentException - 如果 field 为 ZONE_OFFSET、DST_OFFSET 或未知，或者任何日历字段在 non-lenient 模式下具有超出范围的值。

从以下版本开始：

1.2

另请参见：

roll(int,boolean), add(int,int), Calendar.set(int,int)

getMinimum

public int getMinimum(int field)

返回此 GregorianCalendar 实例的给定日历字段的最小值。考虑到 getFirstDayOfWeek、getMinimalDaysInFirstWeek、getGregorianChange 和 getTimeZone 方法的当前值，最小值定义为由 get 方法为所有可能的时间值所返回的最小值。

指定者：

类 Calendar 中的 getMinimum

参数：

field - 日历字段。

返回：

给定日历字段的最小值。

另请参见：

getMaximum(int), getGreatestMinimum(int), getLeastMaximum(int), getActualMinimum(int), getActualMaximum(int)

getMaximum

public int getMaximum(int field)

返回此 GregorianCalendar 实例的给定日历字段的最大值。考虑到 getFirstDayOfWeek、getMinimalDaysInFirstWeek、getGregorianChange 和 getTimeZone 方法的当前值，最大值定义为 get 方法为所有可能的时间值所返回的最大值。

指定者：

类 Calendar 中的 getMaximum

参数：

field - 日历字段。

返回：

给定日历字段的最大值。

另请参见：

getMinimum(int), getGreatestMinimum(int), getLeastMaximum(int), getActualMinimum(int), getActualMaximum(int)

getGreatestMinimum

public int getGreatestMinimum(int field)

返回此 GregorianCalendar 实例给定日历字段的最高的最小值。考虑到 getFirstDayOfWeek、getMinimalDaysInFirstWeek、getGregorianChange 和 getTimeZone 方法的当前值，最高的最小值定义为 getActualMinimum(int) 为所有可能的时间值所返回的最大值。

指定者：

类 Calendar 中的 getGreatestMinimum

参数：

field - 日历字段。

返回：

给定日历字段的最高的最小值。

另请参见：

getMinimum(int), getMaximum(int), getLeastMaximum(int), getActualMinimum(int), getActualMaximum(int)

getLeastMaximum

public int getLeastMaximum(int field)

返回此 GregorianCalendar 实例给定日历字段的最低的最大值。考虑到 getFirstDayOfWeek、getMinimalDaysInFirstWeek、getGregorianChange 和 getTimeZone 方法的当前值，最低的最大值定义为 getActualMaximum(int) 为所有可能的时间值所返回的最小值。

指定者：

类 Calendar 中的 getLeastMaximum

参数：

field - 日历字段。

返回：

给定日历字段的最低的最大值。

另请参见：

getMinimum(int), getMaximum(int), getGreatestMinimum(int), getActualMinimum(int), getActualMaximum(int)

getActualMinimum

public int getActualMinimum(int field)

考虑到给定的时间值和 getFirstDayOfWeek、getMinimalDaysInFirstWeek、getGregorianChange 和 getTimeZone 方法的当前值，返回此日历字段可能具有的最小值。

例如，如果格里高利历的更改日期是 1970 年 1 月 10 日，而此 GregorianCalendar 的日期是 1970 年 1 月 20 日，则 DAY_OF_MONTH 字段的实际最小值是 10，因为按照儒略历，1970 年 1 月 10 日的前一个日期是 1969 年 12 月 27 日。因此，从 1969 年 12 月 28 日到 1970 年 1 月 9 日的日期不存在。

覆盖：

类 Calendar 中的 getActualMinimum

参数：

field - 日历字段。

返回：

针对此 GregorianCalendar 时间值的给定字段最小值。

从以下版本开始：

1.2

另请参见：

getMinimum(int), getMaximum(int), getGreatestMinimum(int), getLeastMaximum(int), getActualMaximum(int)

getActualMaximum

public int getActualMaximum(int field)

考虑到给定的时间值和 getFirstDayOfWeek、getMinimalDaysInFirstWeek、getGregorianChange 和 getTimeZone 方法的当前值，返回此日历字段可能具有的最大值。例如，如果此实例的日期是 2004 年 2 月 1 日，则 DAY_OF_MONTH 字段的实际最大值是 29，因为 2004 年是闰年；如果此实例的日期是 2005 年 2 月 1 日，则最大值是 28。

覆盖：

类 Calendar 中的 getActualMaximum

参数：

field - 日历字段。

返回：

针对此 GregorianCalendar 时间值的给定字段最大值。

从以下版本开始：

1.2

另请参见：

getMinimum(int), getMaximum(int), getGreatestMinimum(int), getLeastMaximum(int), getActualMinimum(int)

clone

public Object clone()

从类 Calendar 复制的描述

创建并返回此对象的一个副本。

覆盖：

类 Calendar 中的 clone

返回：

此对象的一个副本。

另请参见：

Cloneable

getTimeZone

public TimeZone getTimeZone()

从类 Calendar 复制的描述

获得时区。

覆盖：

类 Calendar 中的 getTimeZone

返回：

与此日历有关的时区对象。

setTimeZone

public void setTimeZone(TimeZone zone)

从类 Calendar 复制的描述

使用给定的时区值来设置时区。

覆盖：

类 Calendar 中的 setTimeZone

参数：

zone - 给定的时区。

computeFields

protected void computeFields()

将时间值（从 Epoch 至现在的毫秒偏移量）转换为日历字段值。不会 一开始就重新计算时间；要重新计算时间，并重新计算字段，则需要先调用 complete 方法。

指定者：

类 Calendar 中的 computeFields

另请参见：

Calendar.complete()

computeTime

protected void computeTime()

将日历字段值转换为时间值（从 Epoch 至现在的毫秒偏移量）。

指定者：

类 Calendar 中的 computeTime

抛出：

IllegalArgumentException - 如果存在任何无效的日历字段。

另请参见：

Calendar.complete(), Calendar.computeFields()

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。