鸿蒙OS GregorianCalendar

GregorianCalendar

java.lang.Object

|—java.util.Calendar

|—|—java.util.GregorianCalendar

public class GregorianCalendar
extends Calendar

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

GregorianCalendar 是一种混合日历，它同时支持儒略历和公历系统，并支持单个不连续性，默认情况下对应于公历制定时的公历日期（在某些国家/地区为 1582 年 10 月 15 日，在其他国家/地区较晚）。 调用者可以通过调用 setGregorianChange() 来更改切换日期。

从历史上看，在那些首先采用公历的国家中，1582 年 10 月 4 日（儒略历）随后是 1582 年 10 月 15 日（公历）。 这个日历正确地模拟了这一点。 在公历转换之前，GregorianCalendar 实现了儒略历。 公历和儒略历之间的唯一区别是闰年规则。 儒略历每四年指定闰年，而公历省略不能被 400 整除的世纪年。

GregorianCalendar 实现了预测的公历和儒略历。 也就是说，日期是通过无限期地向后和向前推断当前规则来计算的。 因此，GregorianCalendar 可用于所有年份以生成有意义且一致的结果。 然而，使用 GregorianCalendar 获得的日期仅在公元 4 年 3 月 1 日之后才具有历史准确度，当时采用了现代儒略历规则。 在此日期之前，闰年规则的应用不规律，而在公元前 45 年之前，儒略历甚至都不存在。

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

一年中的一周和一周年

为 Calendar#WEEK_OF_YEAR 字段计算的值范围为 1 到 53。日历年的第一周是从 Calendar#getFirstDayOfWeek() 开始的最早的 7 天时间段，其中至少包含该年的 Calendar#getMinimalDaysInFirstWeek() 天。 因此，它取决于 getMinimalDaysInFirstWeek()、getFirstDayOfWeek() 和 1 月 1 日的星期几的值。一年的第 1 周和下一年的第 1 周（不包括）之间的周数从 2 到 52 或 53 年（儒略-格里高利过渡所涉及的年份除外）。

getFirstDayOfWeek() 和 getMinimalDaysInFirstWeek() 值在构造 GregorianCalendar 时使用与语言环境相关的资源进行初始化。当 getFirstDayOfWeek() 为 MONDAY 且 getMinimalDaysInFirstWeek() 为 4 时，星期确定与 ISO 8601 标准兼容，这些值用于首选标准的区域设置。这些值可以通过调用 Calendar#setFirstDayOfWeek(int) 和 Calendar#setMinimalDaysInFirstWeek(int) 显式设置。

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

例如，1998 年 1 月 1 日是星期四。如果 getFirstDayOfWeek() 为 MONDAY 且 getMinimalDaysInFirstWeek() 为 4（ISO 8601 标准兼容设置），则 1998 年的第 1 周开始于 1997 年 12 月 29 日，结束于 1998 年 1 月 4 日。最后三天的周年份为 1998 年1997 日历年。但是，如果 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() 连续天数的最早集合，在 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 为 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 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

嵌套类摘要

字段摘要

构造函数摘要

方法总结

字段详细信息

AD

public static final int AD

指示共同时代（Anno Domini）的 ERA 字段的值，也称为 CE。 从公元前到公元过渡的年份顺序是……，公元前2年，公元前1年，公元1年，公元2年，……

BC

public static final int BC

ERA 字段的值表示普通时代（基督之前）之前的时期，也称为 BCE。 从公元前到公元过渡的年份顺序是……，公元前2年，公元前1年，公元1年，公元2年，……

构造函数详细信息

GregorianCalendar

public GregorianCalendar()

使用默认时区中的当前时间和默认 Locale.Category#FORMAT 语言环境构造默认 GregorianCalendar。

GregorianCalendar

public GregorianCalendar(TimeZone zone)

使用默认 Locale.Category#FORMAT 区域设置基于给定时区中的当前时间构造 GregorianCalendar。

参数：

GregorianCalendar

public GregorianCalendar(Locale aLocale)

根据给定语言环境的默认时区中的当前时间构造一个 GregorianCalendar。

参数：

GregorianCalendar

public GregorianCalendar(TimeZone zone, Locale aLocale)

根据给定区域设置的给定时区中的当前时间构造一个 GregorianCalendar。

参数：

GregorianCalendar

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

构造一个 GregorianCalendar，其给定日期设置在默认时区和默认语言环境中。

参数：

GregorianCalendar

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

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

参数：

GregorianCalendar

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

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

参数：

方法详情

setGregorianChange

public void setGregorianChange(Date date)

设置 GregorianCalendar 更改日期。 这是从儒略日期转换为公历日期的时间点。 默认值为 1582 年 10 月 15 日（公历）。 在此之前，日期将采用儒略历。

要获取纯儒略历，请将更改日期设置为 Date(Long.MAX_VALUE)。 要获取纯公历，请将更改日期设置为 Date(Long.MIN_VALUE)。

参数：

getGregorianChange

public final Date getGregorianChange()

获取公历更改日期。 这是从儒略日期转换为公历日期的时间点。 默认值为 1582 年 10 月 15 日（公历）。 在此之前，日期将采用儒略历。

返回:

此 GregorianCalendar 对象的公历截止日期。

isLeapYear

public boolean isLeapYear(int year)

确定给定年份是否为闰年。 如果给定年份是闰年，则返回 true。 要指定 BC 年编号，必须给出 1 年编号。 例如，公元前 4 年指定为 -3。

参数：

返回:

如果给定年份是闰年，则为 true； 否则为 false。

getCalendarType

public String getCalendarType()

返回“gregory”作为日历类型。

覆盖：

类 Calendar 中的 getCalendarType

返回:

“gregory”

equals

public boolean equals(Object obj)

将此 GregorianCalendar 与指定的 Object 进行比较。 当且仅当参数是一个 GregorianCalendar 对象，该对象表示与该对象相同的日历参数和公历更改日期下的相同时间值（从 Epoch 的毫秒偏移量）时，结果才为true。

覆盖：

等于日历类

参数：

返回:

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

hashCode

public int hashCode()

生成此 GregorianCalendar 对象的哈希码。

覆盖：

类 Calendar 中的 hashCode

返回:

此对象的哈希码值。

add

public void add(int field, int amount)

根据日历的规则，将指定（签名）的时间量添加到给定的日历字段。

添加规则1。调用后的字段值减去调用前的字段值是金额，以字段中发生的任何溢出为模。 当字段值超出其范围时会发生溢出，因此，下一个较大的字段会递增或递减，并且字段值会调整回其范围内。

增加规则2，如果一个较小的字段期望是不变的，但是由于字段改变后它的最小值或最大值发生了变化，使得它不可能等于它的先前值，那么它的值被调整为尽可能接近 可能达到其预期值。 较小的字段表示较小的时间单位。 HOUR 是比 DAY_OF_MONTH 小的字段。 不对预期不会保持不变的较小字段进行任何调整。 日历系统确定哪些字段预计是不变的。

指定者：

添加日历类

参数：

Throws:

roll

public void roll(int field, boolean up)

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

示例：考虑最初设置为 1999 年 12 月 31 日的 GregorianCalendar。调用 roll(Calendar.MONTH, true) 将日历设置为 1999 年 1 月 31 日。YEAR 字段未更改，因为它比 MONTH 更大。

指定者：

滚动日历类

参数：

Throws:

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 字段在 4 月份不能为 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 时的不变量，设置为星期二，最接近星期日的可能值（其中星期日是一周的第一天）。

覆盖：

滚动日历类

参数：

Throws:

getMinimum

public int getMinimum(int field)

返回此 GregorianCalendar 实例的给定日历字段的最小值。 最小值定义为 Calendar#get(int) 方法针对任何可能的时间值返回的最小值，同时考虑到 Calendar#getFirstDayOfWeek()、Calendar#getMinimalDaysInFirstWeek()、getGregorianChange 和 Calendar#getTimeZone 的当前值 （） 方法。

指定者：

日历类中的getMinimum

参数：

返回:

给定日历字段的最小值。

getMaximum

public int getMaximum(int field)

返回此 GregorianCalendar 实例的给定日历字段的最大值。 最大值定义为 Calendar#get(int) 方法针对任何可能的时间值返回的最大值，同时考虑到 Calendar#getFirstDayOfWeek()、Calendar#getMinimalDaysInFirstWeek()、getGregorianChange 和 Calendar#getTimeZone 的当前值 （） 方法。

指定者：

日历类中的getMaximum

参数：

返回:

给定日历字段的最大值。

getGreatestMinimum

public int getGreatestMinimum(int field)

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

指定者：

日历类中的getGreatestMinimum

参数：

返回:

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

getLeastMaximum

public int getLeastMaximum(int field)

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

指定者：

日历类中的getLeastMaximum

参数：

返回:

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

getActualMinimum

public int getActualMinimum(int field)

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

例如，如果公历更改日期为 1970 年 1 月 10 日，并且此 GregorianCalendar 的日期为 1970 年 1 月 20 日，则 DAY_OF_MONTH 字段的实际最小值为 10，因为 1970 年 1 月 10 日的上一个日期是 1996 年 12 月 27 日（ 在儒略历中）。 因此，1969 年 12 月 28 日至 1970 年 1 月 9 日不存在。

覆盖：

日历类中的 getActualMinimum

参数：

返回:

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

getActualMaximum

public int getActualMaximum(int field)

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

此方法根据 Calendar#YEAR（日历年）值而不是周年计算 Calendar#WEEK_OF_YEAR 的最大值。 调用 getWeeksInWeekYear() 以获取此 GregorianCalendar 的周年中 WEEK_OF_YEAR 的最大值。

覆盖：

日历类中的 getActualMaximum

参数：

返回:

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

clone

public Object clone()

从班级复制的描述：日历

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

覆盖：

在日历类中克隆

返回:

此对象的副本。

getTimeZone

public TimeZone getTimeZone()

从班级复制的描述：日历

获取时区。

覆盖：

类 Calendar 中的 getTimeZone

返回:

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

setTimeZone

public void setTimeZone(TimeZone zone)

从班级复制的描述：日历

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

覆盖：

日历类中的 setTimeZone

参数：

isWeekDateSupported

public final boolean isWeekDateSupported()

返回 true 表示此 GregorianCalendar 支持星期日期。

覆盖：

类 Calendar 中的 isWeekDateSupported

返回:

true（总是）

getWeekYear

public int getWeekYear()

返回此 GregorianCalendar 表示的周年。 在 1 和周年的最大周数之间的周中的日期具有相同的周年值，可能在 Calendar#YEAR（日历年）值之前或之后一年。

此方法在计算周年之前调用 Calendar#complete()。

覆盖：

课堂日历中的getWeekYear

返回:

此 GregorianCalendar 表示的周年。 如果 Calendar#ERA 值为 BC，则年份由 0 或负数表示：BC 1 为 0，BC 2 为 -1，BC 3 为 -2，依此类推。

Throws:

setWeekDate

public void setWeekDate(int weekYear, int weekOfYear, int dayOfWeek)

将此 GregorianCalendar 设置为日期说明符给出的日期 – weekYear、weekOfYear 和 dayOfWeek。 weekOfYear 遵循 WEEK_OF_YEAR 编号。 dayOfWeek 值必须是 Calendar#DAY_OF_WEEK 值之一：Calendar#SUNDAY 到 Calendar#SATURDAY。

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

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

如果 weekOfYear 超出了 weekYear 中的有效周范围，则在宽松模式下调整 weekYear 和 weekOfYear 值，或者在非宽松模式下抛出 IllegalArgumentException。

覆盖：

日历类中的 setWeekDate

参数：

Throws:

getWeeksInWeekYear

public int getWeeksInWeekYear()

返回此 GregorianCalendar 表示的一周年中的周数。

例如，如果此 GregorianCalendar 的日期为 2008 年 12 月 31 日，且设置为 ISO 8601 兼容，则此方法将在以下期间返回 53：2008 年 12 月 29 日至 2010 年 1 月 3 日，而 getActualMaximum(WEEK_OF_YEAR) 将在以下期间返回 52：12 月 2007 年 31 月 31 日至 2008 年 12 月 28 日。

覆盖：

类日历中的getWeeksInWeekYear

返回:

一周中的周数。

computeFields

protected void computeFields()

将时间值（从 Epoch 的毫秒偏移量）转换为日历字段值。 时间不先重新计算； 重新计算时间，然后是字段，调用完整方法。

指定者：

日历类中的 computeFields

computeTime

protected void computeTime()

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

指定者：

日历类中的 computeTime

Throws:

toZonedDateTime

public ZonedDateTime toZonedDateTime()

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

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

返回:

表示时间线上与此公历相同的点的分区日期时间

from

public static GregorianCalendar from(ZonedDateTime zdt)

从 ZonedDateTime 对象获取具有默认语言环境的 GregorianCalendar 实例。

由于 ZonedDateTime 不支持 Julian-Gregorian 转换日期并使用 ISO 日历系统，因此返回 GregorianCalendar 是纯公历并使用 ISO 8601 标准定义周，其中 MONDAY 作为 Calendar#getFirstDayOfWeek() 和 4 作为值 日历#getMinimalDaysInFirstWeek()。

ZoneDateTime 可以比 GregorianCalendar 在未来和过去更远地存储时间线上的点。 在这种情况下，此方法将引发 IllegalArgumentException 异常。

参数：

返回:

公历，表示时间线上与提供的分区日期时间相同的点

Throws: