GregorianCalendar

Class Overview

GregorianCalendar is a concrete subclass of Calendar and provides the standard calendar used by most of the world.

The standard (Gregorian) calendar has 2 eras, BC and AD.

This implementation handles a single discontinuity, which corresponds by default to the date the Gregorian calendar was instituted (October 15, 1582 in some countries, later in others). The cutover date may be changed by the caller by calling setGregorianChange().

Historically, in those countries which adopted the Gregorian calendar first, October 4, 1582 was thus followed by October 15, 1582. This calendar models this correctly. Before the Gregorian cutover, GregorianCalendar implements the Julian calendar. The only difference between the Gregorian and the Julian calendar is the leap year rule. The Julian calendar specifies leap years every four years, whereas the Gregorian calendar omits century years which are not divisible by 400.

GregorianCalendar implements proleptic Gregorian and Julian calendars. That is, dates are computed by extrapolating the current rules indefinitely far backward and forward in time. As a result, GregorianCalendar may be used for all years to generate meaningful and consistent results. However, dates obtained using GregorianCalendar are historically accurate only from March 1, 4 AD onward, when modern Julian calendar rules were adopted. Before this date, leap year rules were applied irregularly, and before 45 BC the Julian calendar did not even exist.

Prior to the institution of the Gregorian calendar, New Year's Day was March 25. To avoid confusion, this calendar always uses January 1. A manual adjustment may be made if desired for dates that are prior to the Gregorian changeover and which fall between January 1 and March 24.

Values calculated for the WEEK_OF_YEAR field range from 1 to 53. Week 1 for a year is the earliest seven day period starting on getFirstDayOfWeek() that contains at least getMinimalDaysInFirstWeek() days from that year. It thus depends on the values of getMinimalDaysInFirstWeek(), getFirstDayOfWeek(), and the day of the week of January 1. Weeks between week 1 of one year and week 1 of the following year are numbered sequentially from 2 to 52 or 53 (as needed).

For example, January 1, 1998 was a Thursday. If getFirstDayOfWeek() is MONDAY and getMinimalDaysInFirstWeek() is 4 (these are the values reflecting ISO 8601 and many national standards), then week 1 of 1998 starts on December 29, 1997, and ends on January 4, 1998. If, however, getFirstDayOfWeek() is SUNDAY, then week 1 of 1998 starts on January 4, 1998, and ends on January 10, 1998; the first three days of 1998 then are part of week 53 of 1997.

Values calculated for the WEEK_OF_MONTH field range from 0 or 1 to 4 or 5. Week 1 of a month (the days with WEEK_OF_MONTH = 1) is the earliest set of at least getMinimalDaysInFirstWeek() contiguous days in that month, ending on the day before getFirstDayOfWeek(). Unlike week 1 of a year, week 1 of a month may be shorter than 7 days, need not start on getFirstDayOfWeek(), and will not include days of the previous month. Days of a month before week 1 have a WEEK_OF_MONTH of 0.

For example, if getFirstDayOfWeek() is SUNDAY and getMinimalDaysInFirstWeek() is 4, then the first week of January 1998 is Sunday, January 4 through Saturday, January 10. These days have a WEEK_OF_MONTH of 1. Thursday, January 1 through Saturday, January 3 have a WEEK_OF_MONTH of 0. If getMinimalDaysInFirstWeek() is changed to 3, then January 1 through January 3 have a WEEK_OF_MONTH of 1.

Example:

 // 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 savings 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
 

Summary

[Expand] Inherited Constants

From class java.util.Calendar int ALL_STYLES Requests both SHORT and LONG styles in the map returned by getDisplayNames(int, int, Locale). int AM Value of the AM_PM field indicating the period of the day from midnight to just before noon. int AM_PM Field number for get and set indicating whether the HOUR is before or after noon. int APRIL Value of the MONTH field indicating the fourth month of the year. int AUGUST Value of the MONTH field indicating the eighth month of the year. int DATE Field number for get and set indicating the day of the month. int DAY_OF_MONTH Field number for get and set indicating the day of the month. int DAY_OF_WEEK Field number for get and set indicating the day of the week. int DAY_OF_WEEK_IN_MONTH Field number for get and set indicating the ordinal number of the day of the week within the current month. int DAY_OF_YEAR Field number for get and set indicating the day number within the current year. int DECEMBER Value of the MONTH field indicating the twelfth month of the year. int DST_OFFSET Field number for get and set indicating the daylight savings offset in milliseconds. int ERA Field number for get and set indicating the era, e.g., AD or BC in the Julian calendar. int FEBRUARY Value of the MONTH field indicating the second month of the year. int FIELD_COUNT This is the total number of fields in this calendar. int FRIDAY Value of the DAY_OF_WEEK field indicating Friday. int HOUR Field number for get and set indicating the hour of the morning or afternoon. int HOUR_OF_DAY Field number for get and set indicating the hour of the day. int JANUARY Value of the MONTH field indicating the first month of the year. int JULY Value of the MONTH field indicating the seventh month of the year. int JUNE Value of the MONTH field indicating the sixth month of the year. int LONG Requests long names (such as "January") from getDisplayName(int, int, Locale) or getDisplayNames(int, int, Locale). int MARCH Value of the MONTH field indicating the third month of the year. int MAY Value of the MONTH field indicating the fifth month of the year. int MILLISECOND Field number for get and set indicating the millisecond within the second. int MINUTE Field number for get and set indicating the minute within the hour. int MONDAY Value of the DAY_OF_WEEK field indicating Monday. int MONTH Field number for get and set indicating the month. int NOVEMBER Value of the MONTH field indicating the eleventh month of the year. int OCTOBER Value of the MONTH field indicating the tenth month of the year. int PM Value of the AM_PM field indicating the period of the day from noon to just before midnight. int SATURDAY Value of the DAY_OF_WEEK field indicating Saturday. int SECOND Field number for get and set indicating the second within the minute. int SEPTEMBER Value of the MONTH field indicating the ninth month of the year. int SHORT Requests short names (such as "Jan") from getDisplayName(int, int, Locale) or getDisplayNames(int, int, Locale). int SUNDAY Value of the DAY_OF_WEEK field indicating Sunday. int THURSDAY Value of the DAY_OF_WEEK field indicating Thursday. int TUESDAY Value of the DAY_OF_WEEK field indicating Tuesday. int UNDECIMBER Value of the MONTH field indicating the thirteenth month of the year. int WEDNESDAY Value of the DAY_OF_WEEK field indicating Wednesday. int WEEK_OF_MONTH Field number for get and set indicating the week number within the current month. int WEEK_OF_YEAR Field number for get and set indicating the week number within the current year. int YEAR Field number for get and set indicating the year. int ZONE_OFFSET Field number for get and set indicating the raw offset from GMT in milliseconds.

[Expand] Inherited Fields

From class java.util.Calendar protected boolean areFieldsSet True iff the values in fields[] correspond to time. protected int[] fields Contains broken-down field values for the current value of time if areFieldsSet is true, or stale data corresponding to some previous value otherwise. protected boolean[] isSet Whether the corresponding element in field[] has been set. protected boolean isTimeSet Whether time corresponds to the values in fields[]. protected long time A time in milliseconds since January 1, 1970.

[Expand] Inherited Methods
From class java.util.Calendar abstract void add(int field, int value) Adds the given amount to a Calendar field. boolean after(Object calendar) Returns whether the Date represented by this Calendar instance is after the Date represented by the parameter. boolean before(Object calendar) Returns whether the Date represented by this Calendar instance is before the Date represented by the parameter. final void clear(int field) Clears the value in the given time field, marking it unset and assigning it a value of zero. final void clear() Clears the values of all the time fields, marking them all unset and assigning them all a value of zero. Object clone() Returns a shallow copy of this Calendar with the same properties. int compareTo(Calendar anotherCalendar) Compares the time represented by this Calendar to that represented by the given Calendar. void complete() Computes the time from the fields if the time has not already been set. abstract void computeFields() Computes the Calendar fields from time. abstract void computeTime() Computes time from the Calendar fields. boolean equals(Object object) Compares the given object to this Calendar and returns whether they are equal. int get(int field) Returns the value of the given field after computing the field values by calling complete() first. int getActualMaximum(int field) Returns the maximum value of the given field for the current date. int getActualMinimum(int field) Returns the minimum value of the given field for the current date. synchronized static Locale[] getAvailableLocales() Returns an array of locales for which custom Calendar instances are available. String getDisplayName(int field, int style, Locale locale) Returns a human-readable string for the value of field using the given style and locale. Map<String, Integer> getDisplayNames(int field, int style, Locale locale) Returns a map of human-readable strings to corresponding values, for the given field, style, and locale. int getFirstDayOfWeek() Returns the first day of the week for this Calendar. abstract int getGreatestMinimum(int field) Returns the greatest minimum value of the given field. synchronized static Calendar getInstance(Locale locale) Constructs a new instance of the Calendar subclass appropriate for the given Locale and default TimeZone, set to the current date and time. synchronized static Calendar getInstance(TimeZone timezone, Locale locale) Constructs a new instance of the Calendar subclass appropriate for the given Locale and given TimeZone, set to the current date and time. synchronized static Calendar getInstance(TimeZone timezone) Constructs a new instance of the Calendar subclass appropriate for the default Locale and given TimeZone, set to the current date and time. synchronized static Calendar getInstance() Constructs a new instance of the Calendar subclass appropriate for the default Locale and default TimeZone, set to the current date and time. abstract int getLeastMaximum(int field) Returns the smallest maximum value of the given field. abstract int getMaximum(int field) Returns the greatest maximum value of the given field. int getMinimalDaysInFirstWeek() Returns the minimal days in the first week of the year. abstract int getMinimum(int field) Returns the smallest minimum value of the given field. final Date getTime() Returns the time of this Calendar as a Date object. long getTimeInMillis() Returns the time represented by this Calendar, recomputing the time from its fields if necessary. TimeZone getTimeZone() Returns the time zone used by this Calendar. int hashCode() Returns an integer hash code for this object. final int internalGet(int field) Returns the value of the given field without recomputing. boolean isLenient() Tests whether this Calendar accepts field values which are outside the valid range for the field. final boolean isSet(int field) Tests whether the given field is set. void roll(int field, int value) Adds the given amount to the given field and wraps the value of the field when it goes beyond the maximum or minimum value for the current date. abstract void roll(int field, boolean increment) Increment or decrement the given field and wrap the value of the field when it goes beyond the maximum or minimum value for the current date. void set(int field, int value) Sets the given field to the given value. final void set(int year, int month, int day, int hourOfDay, int minute, int second) Sets the year, month, day of the month, hour of day, minute, and second fields. final void set(int year, int month, int day) Sets the year, month, and day of the month fields. final void set(int year, int month, int day, int hourOfDay, int minute) Sets the year, month, day of the month, hour of day, and minute fields. void setFirstDayOfWeek(int value) Sets the first day of the week for this Calendar. void setLenient(boolean value) Sets whether this Calendar accepts field values which are outside the valid range for the field. void setMinimalDaysInFirstWeek(int value) Sets the minimal days in the first week of the year. final void setTime(Date date) Sets the time of this Calendar. void setTimeInMillis(long milliseconds) Sets the time of this Calendar to the given Unix time. void setTimeZone(TimeZone timezone) Sets the TimeZone used by this Calendar. String toString() Returns a string representation of this Calendar, showing which fields are set.
From class java.lang.Object Object clone() Creates and returns a copy of this Object. boolean equals(Object o) Compares this instance with the specified object and indicates if they are equal. void finalize() Invoked when the garbage collector has detected that this instance is no longer reachable. final Class<?> getClass() Returns the unique instance of Class that represents this object's class. int hashCode() Returns an integer hash code for this object. final void notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString() Returns a string containing a concise, human-readable description of this object. final void wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait(long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
From interface java.lang.Comparable abstract int compareTo(T another) Compares this object to the specified object to determine their relative order.