模块  java.base
软件包  java.util

Class GregorianCalendar

  • 实现的所有接口
    Serializable ， Cloneable ， Comparable<Calendar> 
    public class GregorianCalendar
extends Calendar
    GregorianCalendar是GregorianCalendar的具体子类， Calendar提供了世界上大多数人使用的标准日历系统。

    GregorianCalendar是一个混合日历，支持Julian和Gregorian日历系统，支持单个不连续性，默认情况下对应公历日历时的格里高利日期（1582年10月15日，某些国家，后来的其他国家）。 调用者可以通过致电setGregorianChange()更改切换日期。

    历史上，在那些首先采用公历的国家，1582年10月4日（朱利安）因此随后是1582年10月15日（格里高利安）。 此日历可以正确建模。 在格里高利转换之前， GregorianCalendar实现了儒略历。 格里高利历和儒略历之间的唯一区别是闰年规则。 朱利安历法规定了每四年一次的闰年，而格里高利历则省略了不能被400整除的世纪年。

    GregorianCalendar实现proleptic格里高利历和罗马儒略历。 也就是说，日期是通过在时间上向后和向前无限地推断当前规则来计算的。 因此， GregorianCalendar可用于所有年份以产生有意义且一致的结果。 但是，使用GregorianCalendar获得的日期在历史上仅从公元3月1日开始准确，当时采用现代儒略历法规。 在此日期之前，闰年规则被不定期地适用，并且在公元前45年之前，朱利安历法甚至不存在。

    在公历制度之前，元旦是3月25日。为避免混淆，此日历始终使用1月1日。如果需要，可以在格里高利转换之前的日期进行手动调整，并且在1月1日之间和3月24日。

    Week Of Year and Week Year

    为WEEK_OF_YEAR字段计算的值范围为1到53.日历年的第一周是从getFirstDayOfWeek()开始的最早的七天时段，其中包含该年至少getMinimalDaysInFirstWeek()天。 因而它取决于的值getMinimalDaysInFirstWeek() ， getFirstDayOfWeek() ，和一周的一月的一年1周和下一年的1周（不包括）顺序地被编号为2至52或53（除了间1.周一天参与Julian-Gregorian过渡的年份。

    所述getFirstDayOfWeek()个getMinimalDaysInFirstWeek()值构建在使用区域设置相关的资源初始化GregorianCalendar 。 The week determination is compatible当所述ISO 8601标准getFirstDayOfWeek()是MONDAY和getMinimalDaysInFirstWeek()是4，其值是在其中标准是优选的语言环境使用。 可以通过调用setFirstDayOfWeek()和setMinimalDaysInFirstWeek()明确设置这些值。

    week year与WEEK_OF_YEAR周期同步。 第一周和最后一周（包括）之间的所有周都具有相同的周年值。 因此，一周的第一天和最后一天可能具有不同的日历年值。

    例如，1998年1月1日是星期四。 如果getFirstDayOfWeek()是MONDAY并且getMinimalDaysInFirstWeek()是4（ISO 8601标准兼容设置），则1998年第1周从1997年12月29日开始，到1998年1月4日结束。1997年的最后三天是1998年的一周但是，如果getFirstDayOfWeek()是SUNDAY ，则1998年第1周从1998年1月4日开始，到1998年1月10日结束; 1998年的前三天是1997年第53周的一部分，其一周是1997年。

    一个月的一周

    为WEEK_OF_MONTH字段计算的值范围为0到6.一个月的第1周（ WEEK_OF_MONTH = 1 ）是该getMinimalDaysInFirstWeek()至少getMinimalDaysInFirstWeek()个连续日的最早集合，结束于getFirstDayOfWeek()之前的前getFirstDayOfWeek() 。 与一年中的第1周不同，一个月的第1周可能短于7天，不需要从getFirstDayOfWeek()开始，并且不包括上个月的天数。 第1周前一个月的天数为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如果getMinimalDaysInFirstWeek()更改为3，则1月1日到1月3日的WEEK_OF_MONTH为1。

    默认字段值

    clear方法设置日历字段未定义。 如果未定义其值，则GregorianCalendar对每个日历字段使用以下默认值。

    GregorianCalendar default field values Field Default Value ERA AD YEAR 1970 MONTH JANUARY DAY_OF_MONTH 1 DAY_OF_WEEK the first day of week WEEK_OF_MONTH 0 DAY_OF_WEEK_IN_MONTH 1 AM_PM AM HOUR, HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND 0

    默认值不适用于上面未列出的字段。

    例： 

     // 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 Saving Time
 pdt.setStartRule(Calendar.APRIL, 1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
 pdt.setEndRule(Calendar.OCTOBER, -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
    从以下版本开始：
    1.1
    另请参见：
    TimeZone ， Serialized Form

    • 字段详细信息

      • BC

        public static final int BC
        ERA字段的值，表示共同时代之前（基督之前）的时期，也称为BCE。 的年在过渡从序列BC到AD是...，BC 2，BC 1，AD 1，AD 2，...
        另请参见：
        Calendar.ERA ， 常数字段值

      • AD

        public static final int AD
        ERA字段的值表示共同时代（Anno Domini），也称为CE。 的年在过渡从序列BC到AD是...，BC 2，BC 1，AD 1，AD 2，...
        另请参见：
        Calendar.ERA ， 常数字段值

    • 构造方法详细信息

      • GregorianCalendar

        public GregorianCalendar()
        构造一个默认 GregorianCalendar使用默认时区的当前时间的默认 FORMAT语言环境。

      • GregorianCalendar

        public GregorianCalendar​(TimeZone zone)
        根据给定时区中的当前时间构造一个 GregorianCalendar ，默认为 FORMAT语言环境。
        参数
        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日历字段的值。 月值基于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日历字段的值。 月值基于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日历字段的值。 月值基于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日（格里高利）。 在此之前，日期将在儒略历中。

        要获得纯Julian日历，请将更改日期设置为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 - year number 。 例如，BC 4年被指定为-3。
        参数
        year - 给定年份。
        结果
        如果给定的年份是闰年， true ; 否则为false 。

      • equals

        public boolean equals​(Object obj)
        将此GregorianCalendar与指定的Object 。 当且仅当参数是GregorianCalendar对象时，结果为true ，该对象表示相同的Calendar参数和格里高利更改日期下的相同时间值（距离Epoch的毫秒偏移量）。
        重写：
        equals在类 Calendar
        参数
        obj - 要与之比较的对象。
        结果
        true如果此对象等于obj ; 否则为false 。
        另请参见：
        Calendar.compareTo(Calendar)

      • add

        public void add​(int field,
                int amount)
        根据日历的规则，将指定（签名）的时间量添加到给定的日历字段。

        添加规则1 。 值字段通话减去的值之后字段呼叫之前是amount ，模内所出现的任何溢出字段 。 当字段值超出其范围时发生溢出，结果，下一个较大的字段递增或递减，并将字段值调整回其范围。

        添加规则2 。 如果预期较小的字段是不变的，但由于更改了字段之后其最小值或最大值的变化，它不可能等于其先前值，则将其值调整为尽可能接近其预期值值。 较小的字段表示较小的时间单位。 HOUR是一个比DAY_OF_MONTH更小的字段。 不对不希望不变的较小字段进行调整。 日历系统确定预期哪些字段是不变的。

        Specified by:
        add在类 Calendar
        参数
        字段 - 日历字段。
        amount - 要添加到字段中的日期或时间量。
        异常
        IllegalArgumentException -如果 字段是 ZONE_OFFSET ， DST_OFFSET ，或未知的，或者如果任何日历字段具有在非宽松模式外的范围内的值。
        另请参见：
        Calendar.roll(int,int) ， Calendar.set(int,int)

      • roll

        public void roll​(int field,
                 boolean up)
        在给定时间字段上添加或减去（向上/向下）单个时间单位而不更改更大的字段。

        例如 ：考虑GregorianCalendar最初被设置为1999调用12月31日， roll(Calendar.MONTH, true)个集日历至1999年1月31日，该YEAR场是不变的，因为它比一个更大的领域MONTH 。

        Specified by:
        roll在类 Calendar
        参数
        up - 指示是否要汇总或下滚指定日历字段的值。 使用true如果卷起， false不然。
        字段 - 时间字段。
        异常
        IllegalArgumentException -如果 字段是 ZONE_OFFSET ， DST_OFFSET ，或未知的，或者如果任何日历字段具有在非宽松模式外的范围内的值。
        另请参见：
        add(int,int) ， Calendar.set(int,int)

      • roll

        public void roll​(int field,
                 int amount)
        将签名金额添加到指定的日历字段，而不更改更大的字段。 负滚动量意味着在不改变较大字段的情况下从字段中减去。 如果指定的数量为0，则此方法不执行任何操作。

        此方法在添加金额之前调用Calendar.complete() ，以便对所有日历字段进行规范化。 如果在非宽松模式下有任何日历字段具有超出范围的值，则抛出IllegalArgumentException 。

        例如 ：考虑GregorianCalendar最初被设置为1999调用8月31日， roll(Calendar.MONTH, 8)集日历1999年 4月30日。 使用GregorianCalendar ，该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日星期日。这是因为滚动规则强加了一个额外的约束： MONTH时， WEEK_OF_MONTH不得更改。 用添加规则1综合起来，得到的日期必须是周二6月1日和09年6月5，根据之间添加规则2， DAY_OF_WEEK ，不变时改变WEEK_OF_MONTH ，设置为星期二，最接近的可能值至周日（其中星期天是一周的第一天）。

        重写：
        roll类 Calendar
        参数
        字段 - 日历字段。
        amount - 要添加到 字段的签名金额。
        异常
        IllegalArgumentException -如果 字段是 ZONE_OFFSET ， DST_OFFSET ，或未知的，或者如果任何日历字段具有在非宽松模式外的范围内的值。
        从以下版本开始：
        1.2
        另请参见：
        roll(int,boolean) ， add(int,int) ， Calendar.set(int,int)

      • setWeekDate

        public void setWeekDate​(int weekYear,
                        int weekOfYear,
                        int dayOfWeek)
        设置此GregorianCalendar通过之日起符给出的日期- weekYear ， weekOfYear和dayOfWeek 。 weekOfYear在WEEK_OF_YEAR numbering之后 。 dayOfWeek值必须是DAY_OF_WEEK之一值： SUNDAY至SATURDAY 。

        请注意，数字星期几表示与ISO 8601标准不同，并且当getFirstDayOfWeek()为MONDAY且getMinimalDaysInFirstWeek()为4时， weekOfYear编号与标准兼容。

        与set方法不同，所有日历字段和时间瞬间值都是在返回时计算的。

        如果weekOfYear超出有效周的年范围内的weekYear ，该weekYear个weekOfYear值在宽松模式调整，或IllegalArgumentException在非宽松的模式抛出。

        重写：
        setWeekDate在类 Calendar
        参数
        weekYear - 本周的一周
        weekOfYear - 本周数基于 weekYear
        dayOfWeek - 星期值： DAY_OF_WEEK字段的常量之一： SUNDAY ，...， SATURDAY 。
        异常
        IllegalArgumentException - 如果任何给定的日期说明符无效，或者任何日历字段与非宽松模式下的给定日期说明符不一致
        从以下版本开始：
        1.7
        另请参见：
        isWeekDateSupported() ， Calendar.getFirstDayOfWeek() ， Calendar.getMinimalDaysInFirstWeek()

      • computeFields

        protected void computeFields()
        将时间值（从Epoch的毫秒偏移量）转换为日历字段值。 时间不会先重新计算; 要重新计算时间，然后是字段，调用complete方法。
        Specified by:
        computeFields在类 Calendar
        另请参见：
        Calendar.complete()

      • toZonedDateTime

        public ZonedDateTime toZonedDateTime()
        将此对象转换为ZonedDateTime ，它表示时间线上与此GregorianCalendar相同的点。

        由于此对象支持Julian-Gregorian转换日期而ZonedDateTime不支持，因此生成的年，月和日可能具有不同的值。 结果将表示ISO日历系统中的正确日期，该日期系统也将与修改的Julian Days相同。

        结果
        分区日期时间，表示时间线上与此格里历日历相同的点
        从以下版本开始：
        1.8

      • from

        public static GregorianCalendar from​(ZonedDateTime zdt)
        获取的实例GregorianCalendar从一个默认的语言环境ZonedDateTime对象。

        由于ZonedDateTime不支持朱利安- Gregorian转换日期和使用ISO日历系统，返回的GregorianCalendar是一个纯粹的阳历和使用ISO 8601标准定义的一周，其中有MONDAY为FirstDayOfWeek和4作为价值MinimalDaysInFirstWeek 。

        ZoneDateTime可以在未来的时间线上存储积分，并且比GregorianCalendar 。 在这种情况下，此方法将抛出IllegalArgumentException异常。

        参数
        zdt - 要转换的分区日期时间对象
        结果
        格里高利历表示时间线上与分区日期时间相同的点
        异常
        NullPointerException - 如果 zdt为空
        IllegalArgumentException - 如果分区日期时间太大而无法表示为 GregorianCalendar
        从以下版本开始：
        1.8