类 java.util.Calendar

java.lang.Object
   |
   +----java.util.Calendar

public abstract class Calendar

extends Object

implements Serializable, Cloneable

下列类的父类：

GregorianCalendar

Calendar 是一个抽象的基类，用于在一个 Date 对象和一个诸如 YEAR、MONTH、 DAY、HOUR 等整数字段集合之间转换。 (Date 对象代表一个时间精度为毫秒达到特定实例。 关于 Date 类的信息请参见 java.util.Date。)

Calendar 的子类根据一个特定的日历系统解释一个 Date。 JDK 提供了 Calendar 的一个具体的子类： GregorianCalendar。 将来的子类将代表世界上大部分地区使用的各种类型的阴历。

同其它国别敏感的类一样，Calendar 提供了一个类方法 getInstance，以获得该类型的一个通用的对象。 Calendar 的 getInstance 方法返回一个 GregorianCalendar 对象，该对象的时间域由当前的日期和时间初始化：

 Calendar rightNow = Calendar.getInstance();
 

Calendar 对象能够产生为特定语言和日历风格格式化所需实现的日期_时间的所有时间域值。( 例如，日语-格里高里日历，日语-传统日历 ) 。

当从时间域中计算 Date时，可能会出现两种情况：或者没有足够的信息计算 Date ( 例如只有年和月但没有日 ) 或者有矛盾的信息 ( 例如 "Tuesday, July 15, 1996" -- 实际上，1996 年 7 月 15 日是星期一 )。

没有足够的信息。 日历将使用缺省信息指定缺少的域。 这将根据不同日历有所不同；对于格里高里日历，域的缺省值等于开始时间： 例如，YEAR = 1970，MONTH = JANUARY，DATE = 1 等等。

矛盾的信息。 如果域值有冲突，日历将参考最近设置的域值。 例如，当确定日时，日历将参考下列域的组合之一。将使用由最近设置的单个域确定的最近的组合。

 MONTH + DAY_OF_MONTH
 MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
 MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
 DAY_OF_YEAR
 DAY_OF_WEEK + WEEK_OF_YEAR
 

 HOUR_OF_DAY
 AM_PM + HOUR
 

注意： 对于非格里高里日历，为了保证完全没有歧义，可能会需要不同的域。 例如，关于阿拉伯宇宙日历的完整的规格说明有时需要年、月、一月中的日期和一周中的日期。

注意：对于某些特别的时间的解释可能会有一定的歧义，这可以用下列方式解决：

1. 24:00:00 “属于”下一天。即，1969 年 11 月 31 日 23:59 < 1970 年 1 月 1 日 24:00 < 1970 年 1 月 1 日 24:01:00。
2. 尽管历史的来看不精确，午夜也属于“上午”，中午属于“下午”，所以在同一天，12:00 am ( 午夜 ) < 12:01 am，12:00 pm ( 中午 ) < 12:01 pm。

日期或时间格式字符串不是日历定义的一部分，因为在运行时，它们必须能够由用户修改或重写。使用 java.text.DateFormat 格式化日期。

Calendar 为域的“滚动”提供了一个 API，域可以被加一或减一，但是循环滚动。 例如，将日期 "September 12, 1996" 向上滚动一个月结果是 "October 12, 1996"。

Calendar 也为将指定 ( 带符号的 ) 数量的时间添加到特定的时间域中提供了一个日期计算功能。 例如，将日期 "September 12, 1996" 减 5 天得到 "September 7, 1996"。

参见：

Date, GregorianCalendar, TimeZone, DateFormat

变量索引

AM

12 小时时钟的可用常数。

AM_PM

日期和时间的可用常数。

APRIL

月的可用常数。

areFieldsSet

如果该域与 Calendar 的当前时间集合同步则为 true。

AUGUST

月的可用常数。

DATE

日期和时间的可用常数。

DAY_OF_MONTH

日期和时间的可用常数。

DAY_OF_WEEK

日期和时间的可用常数。

DAY_OF_WEEK_IN_MONTH

日期和时间的可用常数。

DAY_OF_YEAR

日期和时间的可用常数。

DECEMBER

月的可用常数。

DST_OFFSET

日期和时间的可用常数。

ERA

日期和时间的可用常数。

FEBRUARY

月的可用常数。

FIELD_COUNT

日期和时间的可用常数。

fields

包含计算毫秒值的时间域。

FRIDAY

星期的可用常数。

HOUR

日期和时间的可用常数。

HOUR_OF_DAY

日期和时间的可用常数。

isSet

指明日历的一个指定的时间域是否被设置的标志。

isTimeSet

指示是否设置了日历中当前时间的标志。

JANUARY

月的可用常数。

JULY

月的可用常数。

JUNE

月的可用常数。

MARCH

月的可用常数。

MAY

月的可用常数。

MILLISECOND

日期和时间的可用常数。

MINUTE

日期和时间的可用常数。

MONDAY

星期的可用常数。

MONTH

日期和时间的可用常数。

NOVEMBER

月的可用常数。

OCTOBER

月的可用常数。

PM

12 小时时钟时间的可用常数。

SATURDAY

星期的可用常数。

SECOND

日期和时间的可用常数。

SEPTEMBER

月的可用常数。

SUNDAY

星期的可用常数。

THURSDAY

星期的可用常数。

time

为日历设置的当前时间。

TUESDAY

星期的可用常数。

UNDECIMBER

月的可用常数。

WEDNESDAY

星期的可用常数。

WEEK_OF_MONTH

日期和时间的可用常数。

WEEK_OF_YEAR

日期和时间的可用常数。

YEAR

日期和时间的可用常数。

ZONE_OFFSET

日期和时间的可用常数。

构造子索引

Calendar()

用 TimeZone.getDefault() 返回的缺省的时区和缺省的语言环境构造一个日历。

Calendar(TimeZone, Locale)

用该给定的时区和语言环境构造一个日历。

方法索引

add(int, int)

日期的计算功能。

after(Object)

比较时间域记录。

before(Object)

比较时间域记录。

clear()

将所有时间域值清零。

clear(int)

将给定的时间域值清零。

clone()

覆盖 Cloneable

complete()

填充时间域列表中所有未设置的域。

computeFields()

将 UTC 作为毫秒数转换为时间域值。

computeTime()

将日历的时间域值作为毫秒数转换为 UTC。

equals(Object)

比较该日历和指定的对象。

get(int)

获得给定时间域的值。

getAvailableLocales()

获得安装 Calendars 的语言环境集合。

getFirstDayOfWeek()

获得一周的第一天；例如在美国为 Sunday，在法国为 Monday。

getGreatestMinimum(int)

获得给定域变化时的最高的最小值。

getInstance()

获得使用缺省时区和语言环境的日历。

getInstance(Locale)

获得使用缺省时区和给定语言环境的日历。

getInstance(TimeZone)

获得使用给定时区和缺省语言环境的日历。

getInstance(TimeZone, Locale)

获得使用给定时区和给定语言环境的日历。

getLeastMaximum(int)

获得给定域变化时的最低的最大值。

getMaximum(int)

获取给定时间域最大值。

getMinimalDaysInFirstWeek()

获得该年中第一个星期所需要的最少的天数，例如，如果定义第一个星期包含一年第一个月的第一天，getMinimalDaysInFirstWeek 返回 1。

getMinimum(int)

获得给定时间域最小值。

getTime()

获得日历的当前时间。

getTimeInMillis()

获得日历的当前时间，作为一个长整数。

getTimeZone()

获得时区。

internalGet(int)

获得给定时间域的值。

isLenient()

指明对日期／时间的解释是否是宽松的。

isSet(int)

确定给定的时间域是否设置了数值。

roll(int, boolean)

时间域滚动功能。

set(int, int)

用给定的值设置时间域。

set(int, int, int)

设置年、月、日期域的数值。

set(int, int, int, int, int)

设置年、月、日期、时和分域的数值。

set(int, int, int, int, int, int)

设置年、月、日期、时、分和秒域的数值。

setFirstDayOfWeek(int)

设置一周的第一天；例如在美国为 Sunday，在法国为 Monday。

setLenient(boolean)

指明对日期／时间的解释是否是宽松的。

setMinimalDaysInFirstWeek(int)

设置该年中第一个星期所需要的最少的天数，例如，定义第一个星期包含一年第一个月的第一天，用值 1 调用该方法。

setTime(Date)

用给定的 Date 设置 Calendar 的当前时间。

setTimeInMillis(long)

用给定的长整数设置 Calendar 的当前时间。

setTimeZone(TimeZone)

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

toString()

返回日历的字符串表示。

变量

 public static final int ERA

日期和时间的可用常数。 用于时间域中。 ERA 是日历专用的。

 public static final int YEAR

日期和时间的可用常数。 用于时间域中。

 public static final int MONTH

日期和时间的可用常数。 用于时间域中。

 public static final int WEEK_OF_YEAR

日期和时间的可用常数。 用于时间域中。

 public static final int WEEK_OF_MONTH

日期和时间的可用常数。 用于时间域中。

 public static final int DATE

日期和时间的可用常数。 用于时间域中。 它是 DAY_OF_MONTH 的同义词。

 public static final int DAY_OF_MONTH

日期和时间的可用常数。 用于时间域中。 它是 DATE 的同义词。

 public static final int DAY_OF_YEAR

日期和时间的可用常数。 用于时间域中。

 public static final int DAY_OF_WEEK

日期和时间的可用常数。 用于时间域中。

 public static final int DAY_OF_WEEK_IN_MONTH

日期和时间的可用常数。 用于时间域中。

 public static final int AM_PM

日期和时间的可用常数。 用于时间域中。

 public static final int HOUR

日期和时间的可用常数。 用于时间域中。 HOUR 用于 12 小时时钟。

 public static final int HOUR_OF_DAY

日期和时间的可用常数。 用于时间域中。 HOUR_OF_DAY 用于 24 小时时钟。

 public static final int MINUTE

日期和时间的可用常数。 用于时间域中。

 public static final int SECOND

日期和时间的可用常数。 用于时间域中。

 public static final int MILLISECOND

日期和时间的可用常数。 用于时间域中。

 public static final int ZONE_OFFSET

日期和时间的可用常数。 用于时间域中。

 public static final int DST_OFFSET

日期和时间的可用常数。 用于时间域中。

 public static final int FIELD_COUNT

日期和时间的可用常数。 FIELD_COUNT 用于时间域数组的创建。

 public static final int SUNDAY

星期的可用常数。 用于格里高里日历。

 public static final int MONDAY

星期的可用常数。 用于格里高里日历。

 public static final int TUESDAY

星期的可用常数。 用于格里高里日历。

 public static final int WEDNESDAY

星期的可用常数。 用于格里高里日历。

 public static final int THURSDAY

星期的可用常数。 用于格里高里日历。

 public static final int FRIDAY

星期的可用常数。 用于格里高里日历。

 public static final int SATURDAY

星期的可用常数。 用于格里高里日历。

 public static final int JANUARY

月的可用常数。 用于格里高里日历。 注意：现在日历的月以 0 开始。

 public static final int FEBRUARY

月的可用常数。 用于格里高里日历。

 public static final int MARCH

月的可用常数。 用于格里高里日历。

 public static final int APRIL

月的可用常数。 用于格里高里日历。

 public static final int MAY

月的可用常数。 用于格里高里日历。

 public static final int JUNE

月的可用常数。 用于格里高里日历。

 public static final int JULY

月的可用常数。 用于格里高里日历。

 public static final int AUGUST

月的可用常数。 用于格里高里日历。

 public static final int SEPTEMBER

月的可用常数。 用于格里高里日历。

 public static final int OCTOBER

月的可用常数。 用于格里高里日历。

 public static final int NOVEMBER

月的可用常数。 用于格里高里日历。

 public static final int DECEMBER

月的可用常数。 用于格里高里日历。

 public static final int UNDECIMBER

月的可用常数。 用于格里高里日历。 UNDECIMBER 是一个人为的名称。第 13 个月用于阴历。

 public static final int AM

12 小时时钟时间的可用常数。 用于格里高里日历。

 public static final int PM

12 小时时钟时间的可用常数。 用于格里高里日历。

 protected int fields[]

包含计算毫秒值的时间域。

 protected boolean isSet[]

指明日历的指定时间域是否设置的标志。 新建对象的域没有设置。当第一次调用生成该域的方法之后，它们都保持设置。

 protected long time

为日历设置的当前时间。

 protected boolean isTimeSet

指示是否设置了日历中当前时间的标志。 用户通过设置一个私有域使该时间无效。

 protected boolean areFieldsSet

如果该域与 Calendar 的当前时间集合同步则为 true。 如果为 false，下一次试图获得一个域的数值时将强迫根据时间域的当前值重新计算所有域的值。 实际上它应该被命名为 areFieldsInSync， 但是为了向下兼容性旧名仍然保留下来。

构造子

 protected Calendar()

用 TimeZone.getDefault() 返回的缺省的时区和缺省的语言环境构造一个日历。

参见：

getDefault

 protected Calendar(TimeZone zone,
                    Locale aLocale)

用该给定的时区和语言环境构造一个日历。

参数：

zone - 给定的时区。

方法

 public static synchronized Calendar getInstance()

用缺省时区和语言环境获得一个日历。

返回值：

一个 Calendar。

 public static synchronized Calendar getInstance(TimeZone zone)

用给定时区和缺省语言环境获得一个日历。

参数：

zone - 给定的时区。

返回值：

一个 Calendar。

 public static synchronized Calendar getInstance(Locale aLocale)

用缺省时区和给定语言环境获得一个日历。

参数：

aLocale - 给定的语言环境。

返回值：

一个 Calendar。

 public static synchronized Calendar getInstance(TimeZone zone,
                                                 Locale aLocale)

用给定时区和给定语言环境获得一个日历。

参数：

zone - 给定的时区。

aLocale - 给定的语言环境。

返回值：

一个 Calendar。

 public static synchronized Locale[] getAvailableLocales()

获得安装 Calendars 的语言环境集合。

返回值：

安装 Calendars 的语言环境集合。

 protected abstract void computeTime()

将日历的时间域作为毫秒值转换为 UTC。

 protected abstract void computeFields()

将 UTC 作为毫秒值转换为时间域值。 允许使时间域值与日历设置的新时间同步。 开始不重新计算该时间；为了重新计算时间和域，调用 complete 方法。

参见：

complete

 public final Date getTime()

获得日历的当前时间。

返回值：

当前的时间。

 public final void setTime(Date date)

用给定的 Date 设置 Calendar 的当前时间。

参数：

date - 给定的 Date。

 protected long getTimeInMillis()

获得日历的作为长整型的当前时间。

返回值：

当前时间，作为从开始时间的 UTC 毫秒值。

 protected void setTimeInMillis(long millis)

用给定的长整数设置 Calendar 的当前时间。

参数：

date - 新时间，从开始时间的 UTC 毫秒时间。

 public final int get(int field)

获得给定时间域的值。

参数：

field - 给定的时间域。

返回值：

给定的时间域值。

 protected final int internalGet(int field)

获取给定时间域的值。 这是子类的一个内部快速时间域值 getter。

参数：

field - 给定的时间域。

返回值：

给定的时间域值。

 public final void set(int field,
                int value)

用给定的值设置时间域。

参数：

field - 给定的时间域。

value - 要设置的给定时间域的值。

 public final void set(int year,
                       int month,
                       int date)

设置年、月、日期域的数值。 保留其它域上次的值。 如果不需要保留，首先调用 clear。

参数：

year - 用于设置 YEAR 时间域的值。

month - 用于设置 MONTH 时间域的值。 Month 值以 0 开始。 例如，0 代表一月。

date - 用于设置 DATE 时间域的值。

 public final void set(int year,
                       int month,
                       int date,
                       int hour,
                       int minute)

设置年、月、日期、时和分域的数值。 保留其它域上次的值。 如果不需要保留，首先调用 clear。

参数：

year - 用于设置 YEAR 时间域的值。

month - 用于设置 MONTH 时间域的值。 Month 值以 0 开始。 例如，0 代表一月。

date - 用于设置 DATE 时间域的值。

hour - 用于设置 HOUR 时间域的值。

minute - 用于设置 MINUTE 时间域的值。

 public final void set(int year,
                       int month,
                       int date,
                       int hour,
                       int minute,
                       int second)

设置年、月、日期、时、分和秒域的数值。 保留其它域上次的值。 如果不需要保留，首先调用 clear。

参数：

year - 用于设置 YEAR 时间域的值。

month - 用于设置 MONTH 时间域的值。 Month 值以 0 开始。 例如，0 代表一月。

date - 用于设置 DATE 时间域的值。

hour - 用于设置 HOUR 时间域的值。

minute - 用于设置 MINUTE 时间域的值。

second - 用于设置 SECOND 时间域的值。

 public final void clear()

将所有时间域值清零。

 public final void clear(int field)

将给定的时间域值清零。

参数：

field - 要清零的时间域。

 public final boolean isSet(int field)

确定给定的时间域是否设置了数值。

返回值：

如果给定的时间域设置了数值则返回 true；否则返回 false。

 protected void complete()

填充时间域列表中所有未设置的域。

 public abstract boolean equals(Object obj)

比较该日历和指定的对象。 当且仅当参数不为 null 而是与该对象描述同一日历的 Calendar 对象，结果为 true。

参数：

obj - 比较的对象。

返回值：

如果对象相同则为 true，否则为 false。

覆盖：

类 Object 中的 equals

 public abstract boolean before(Object when)

比较时间域记录。 等价于比较转换到 UTC 的结果。

参数：

when - 与该 Calendar 比较的 Calendar。

返回值：

如果当前时间在 Calendar when 的时间之前则为 true；否则为 false。

 public abstract boolean after(Object when)

比较时间域记录。 等价于比较转换到 UTC 的结果。

参数：

when - 与该 Calendar 比较的 Calendar。

返回值：

如果该日历的当前时间在 Calendar when 的时间之后则为 true；否则为 false。

 public abstract void add(int field,
                          int amount)

日期的计算功能。 按照日历的规则，将指定 ( 带符号的 ) 数量的时间添加到给定的时间域。 例如，从日历的当前时间减 5 ，可调用：

add(Calendar.DATE, -5)。

参数：

field - 时间域。

amount - 添加到该域的日期和时间的数量。

 public abstract void roll(int field,
                           boolean up)

时间域滚动功能。 在给定的时间域上 ( 向上 / 向下 ) 滚动一个单个的时间单元。 例如，为了将当前日期向上滚动一天，可调用：

roll(Calendar.DATE, true)。 当在年或 Calendar.YEAR 域滚动时，年值将在 1 和调用 getMaximum(Calendar.YEAR) 的返回值之间滚动。 当在月或 Calendar.MONTH 域滚动时，其它的域，例如日期，可能会发生冲突需要改变。 例如，将日期 01/31/96 滚动一月结果是 03/02/96。 当在小时域或 Calendar.HOUR_OF_DAY 域滚动，小时值将在范围 0 到 23 之间滚动，它以 0 开始。

参数：

field - 时间域。

up - 指明指定时间域值向上还是向下滚动。 如果向上滚动用 true ，否则用 false。

 public void setTimeZone(TimeZone value)

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

参数：

value - 给定的时区。

 public TimeZone getTimeZone()

获得时区。

返回值：

与日历相应的时区对象。

 public void setLenient(boolean lenient)

指明对日期／时间的解释是否是宽松的。 在宽松的解释下，一个诸如 "February 942, 1996" 的日期将被看作与1996 年 2 月后的第 941 天等价。 在严格的解释下，这样的日期将引起抛出异常。

参见：

setLenient

 public boolean isLenient()

指明对日期／时间的解释是否是宽松的。

 public void setFirstDayOfWeek(int value)

设置一周的第一天；例如在美国为 Sunday，在法国为 Monday。

参数：

value - 一周给定的第一天。

 public int getFirstDayOfWeek()

获得一周的第一天；例如在美国为 Sunday，在法国为 Monday。

返回值：

一周的第一天。

 public void setMinimalDaysInFirstWeek(int value)

设置该年中第一个星期所需要的最少的天数，例如，如果定义第一个星期包含一年第一个月的第一天，用值 1 调用该方法。如果它必须是一个完整的星期，使用 7 调用该方法。

参数：

value - 给定的一年中第一个星期要求的最少天数。

 public int getMinimalDaysInFirstWeek()

获得该年中第一个星期所需要的最少的天数，例如，如果第一个星期定义为包含一年第一个月的第一天，getMinimalDaysInFirstWeek 返回 1。如果要求的最少天数必须是一个完整的星期，getMinimalDaysInFirstWeek 返回 7。

返回值：

一年中第一个星期要求的最少天数。

 public abstract int getMinimum(int field)

获得给定时间域最小值。 例如对于格里高里 DAY_OF_MONTH 为 1。

参数：

field - 给定的时间域。

返回值：

给定时间域最小值。

 public abstract int getMaximum(int field)

获得给定时间域最大值。 例如对于 Gregorian DAY_OF_MONTH 为 31。

参数：

field - 给定的时间域。

返回值：

给定时间域最大值。

 public abstract int getGreatestMinimum(int field)

获得给定域变化时的最高的最小值。 否则与 getMinimum() 相同。对格里高里日历没有区别。

参数：

field - 给定的时间域。

返回值：

给定时间域最高的最小值。

 public abstract int getLeastMaximum(int field)

获得给定域变化时的最低的最大值。 否则与 getMaximum() 相同。例如对于格里高里日历 DAY_OF_MONTH 为 28。

参数：

field - 给定的时间域。

返回值：

定时间域最低的最大值。

 public Object clone()

覆盖 Cloneable

覆盖：

类 Object 中的 clone

 public String toString()

返回日历的字符串表示。

返回值：

日历的字符串表示。

覆盖：

类 Object 中的 toString