Module  java.base
软件包  java.util

Class GregorianCalendar

  • All Implemented Interfaces:
    Serializable ， Cloneable ， Comparable<Calendar> 

    public class GregorianCalendar
extends Calendar
    GregorianCalendar是的具体子Calendar ，并提供了世界上大多数国家使用的标准日历系统。

    GregorianCalendar是一个混合日历，支持朱利安和公历日历系统，支持一个不连续性，默认情况下对应于格里高利日历（公元1582年10月15日，在一些国家，稍后在其他国家）。 主叫方可以通过拨打setGregorianChange()更改切换日期。

    历史上，1582年10月4日（朱利安）首先采用公历的那些国家，之后是1582年10月15日（格里高利）。 这个日历模型正确。 在格里高利GregorianCalendar之前， GregorianCalendar执行朱利安历。 公历和儒略历的唯一区别是闰年规则。 朱利安历法每四年规定一次闰年，而公历则省略了不能被400整除的百年。

    GregorianCalendar实现proleptic格里高利历和罗马儒略历。 也就是说，日期是通过在时间上无限远地向后和向前推断当前规则来计算的。 因此，可以使用GregorianCalendar多年来产生有意义和一致的结果。 然而，使用GregorianCalendar获得的日期从GregorianCalendar 4月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.周一天一年涉及朱利安 - 格里高利转型）。

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

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

    例如，1998年1月1日是星期四。 如果getFirstDayOfWeek()是MONDAY和getMinimalDaysInFirstWeek()是4（ISO 8601标准兼容环境），那么1998年的第1周从1997年12月29日开始，到1998年1月4日结束。1997年是1998年1997年的最后三天但是，如果getFirstDayOfWeek()是SUNDAY ，则1998年第1周从1998年1月4日开始，1998年1月10日结束; 1998年的头三天是1997年第53周的一部分，他们的周末是1997年。

    几个月

    为WEEK_OF_MONTH字段计算的值范围为0至6.一个月的第一周（ WEEK_OF_MONTH = 1的天WEEK_OF_MONTH = 1 ）是该月份至少getMinimalDaysInFirstWeek()连续天数的最早集合，截止于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月3日星期六有一个WEEK_OF_MONTH为0.如果getMinimalDaysInFirstWeek()改为3，则1月1日至1月3日期间有一个WEEK_OF_MONTH 。

    默认字段值

    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字段的价值表示共同时代之前（在基督之前）的时期，也称为公元前9世纪。 从BC转为AD是...，2 BC，1 BC，1 AD，2 AD，...
        另请参见：
        Calendar.ERA ， Constant Field Values

      • AD

        public static final int AD
        ERA字段的值代表共同时代（Anno Domini），也称为CE。 从BC转为AD是...，公元前2年，公元前1年，公元1年，公元2年
        另请参见：
        Calendar.ERA ， Constant Field Values

    • 构造方法详细信息

      • GregorianCalendar

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

      • GregorianCalendar

        public GregorianCalendar​(TimeZone zone)
        根据指定时区的当前时间，使用默认的 FORMAT区域设置构建一个 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日历字段的值。 月值为0。 例如，1月份为0。
        dayOfMonth - 用于设置日历中的 DAY_OF_MONTH日历字段的值。

      • GregorianCalendar

        public GregorianCalendar​(int year,
                         int month,
                         int dayOfMonth,
                         int hourOfDay,
                         int minute)
        构造一个 GregorianCalendar ，其默认时区的默认语言环境设置了给定的日期和时间。
        参数
        year - 用于设置日历中的 YEAR日历字段的值。
        month - 用于设置日历中MONTH日历字段的值。 月值为0。 例如，1月份为0。
        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。 例如，1月份为0。
        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 - year number 。 例如，年份BC 4被指定为-3。
        参数
        year - 给定年份。
        结果
        true如果给定的一年是闰年; false否则。

      • equals

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

      • add

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

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

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

        Specified by:
        add在 Calendar
        参数
        field - 日历字段。
        amount - 要添加到字段的日期或时间的数量。
        异常
        IllegalArgumentException -如果 field是 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否则。
        field - 时间字段。
        异常
        IllegalArgumentException -如果 field是 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字段比MONTH更大，所以YEAR字段保持1999的值。

        示例 ：考虑一个原始设置为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日星期六至6月5日星期六之间。根据附加规则DAY_OF_WEEK （更改WEEK_OF_MONTH时不变量）设置为星期二，最接近可能的星期日值（其中周日是本周的第一天）。

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

      • clone

        public Object clone​()
        描述从类复制： Calendar
        创建并返回此对象的副本。
        重写：
        clone在 Calendar
        结果
        这个对象的副本。
        另请参见：
        Cloneable

      • getTimeZone

        public TimeZone getTimeZone​()
        描述从类复制： Calendar
        获取时区。
        重写：
        getTimeZone在 Calendar
        结果
        与该日历相关联的时区对象。

      • setTimeZone

        public void setTimeZone​(TimeZone zone)
        描述从类复制： Calendar
        以给定的时区值设置时区。
        重写：
        setTimeZone在 Calendar
        参数
        zone - 给定的时区。

      • 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标准不同， weekOfYear编号与getFirstDayOfWeek()为MONDAY和getMinimalDaysInFirstWeek()为4时的标准兼容。

        与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日历系统中的正确日期，对于修改的朱利安天数也将是相同的值。

        结果
        一个分区的日期时间代表这个格式日历在时间线上的同一点
        从以下版本开始：
        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