模块  java.base
软件包  java.util

Class GregorianCalendar

  • 实现的所有接口
    SerializableCloneableComparable<Calendar>

    public class GregorianCalendar
    extends Calendar
    GregorianCalendarGregorianCalendar的具体子类, 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()MONDAYgetMinimalDaysInFirstWeek()是4,其值是在其中标准是优选的语言环境使用。 可以通过调用setFirstDayOfWeek()setMinimalDaysInFirstWeek()明确设置这些值。

    week yearWEEK_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()SUNDAYgetMinimalDaysInFirstWeek()是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
    另请参见:
    TimeZoneSerialized Form
    • 字段详细信息

      • BC

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

        public static final int AD
        ERA字段的值表示共同时代(Anno Domini),也称为CE。 的年在过渡从序列BCAD是...,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_OFFSETDST_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_OFFSETDST_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 ,设置为星期二,最接近的可能值至周日(其中星期天是一周的第一天)。

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

        public void setWeekDate​(int weekYear,
                                int weekOfYear,
                                int dayOfWeek)
        设置此GregorianCalendar通过之日起符给出的日期- weekYearweekOfYeardayOfWeek weekOfYearWEEK_OF_YEAR numbering之后 dayOfWeek值必须是DAY_OF_WEEK之一值: SUNDAYSATURDAY

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

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

        如果weekOfYear超出有效周的年范围内的weekYear ,该weekYearweekOfYear值在宽松模式调整,或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标准定义的一周,其中有MONDAYFirstDayOfWeek4作为价值MinimalDaysInFirstWeek

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

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