java/util/Calendar.java

64  * The <code>Calendar</code> class is an abstract class that provides methods
78  * Like other locale-sensitive classes, <code>Calendar</code> provides a
80  * object of this type. <code>Calendar</code>'s <code>getInstance</code> method
81  * returns a <code>Calendar</code> object whose
85  *     Calendar rightNow = Calendar.getInstance();
89  * <p>A <code>Calendar</code> object can produce all the calendar field values
92  * <code>Calendar</code> defines the range of values returned by
99  * <h3>Getting and Setting Calendar Field Values</h3>
102  * methods. Any field values set in a <code>Calendar</code> will not be
110  * <p><code>Calendar</code> has two modes for interpreting the calendar
112  * <code>Calendar</code> is in lenient mode, it accepts a wider range of
113  * calendar field values than it produces.  When a <code>Calendar</code>
119  * <p>When a <code>Calendar</code> is in non-lenient mode, it throws an
129  * <code>Calendar</code> defines a locale-specific seven day week using two
132  * <code>Calendar</code> is constructed.  They may also be specified explicitly
136  * <code>WEEK_OF_YEAR</code> fields, <code>Calendar</code> must determine the
143  * different.  For example, a specific <code>Calendar</code> subclass may
147  * <h4>Calendar Fields Resolution</h4>
153  * 1996 is actually a Monday). <code>Calendar</code> will resolve
158  * <code>Calendar</code> gives priorities to calendar fields that have been set
181  * field combination, <code>Calendar</code> uses their default values. The default
229  * originally set to August 31, 1999. Calling <code>set(Calendar.MONTH,
230  * Calendar.SEPTEMBER)</code> sets the date to September 31,
233  * call to <code>set(Calendar.DAY_OF_MONTH, 30)</code> before the call to
266  * originally set to August 31, 1999. Calling <code>add(Calendar.MONTH,
313 public abstract class Calendar implements Serializable, Cloneable, Comparable<Calendar> {
315     // Data flow in Calendar
318     // The current time is represented in two ways by Calendar: as UTC
322     // conversion is encapsulated by a TimeZone object owned by the Calendar.
329     // This is implemented by the Calendar subclass's computeTime() method.
336     //           | Using Calendar-specific algorithm
345     // the data flow is as follows.  This is implemented by the Calendar
354     //           | Using Calendar-specific algorithm
362     // the Calendar is lenient, the fields are also renormalized to standard
552      * zone of this <code>Calendar</code> if the
563      * the time zone of this <code>Calendar</code> if the
824     // Calendar contains two kinds of time representations: current "time" in
905      * The <code>TimeZone</code> used by this calendar. <code>Calendar</code>
1026      * {@code Calendar.Builder} is used for creating a {@code Calendar} from
1029      * <p>There are two ways to set a {@code Calendar} to a date-time value. One
1031      * href="Calendar.html#Epoch">Epoch</a>. The other is to set individual
1032      * field parameters, such as {@link Calendar#YEAR YEAR}, to their desired
1040      * {@code Calendar}. For example, if the {@link Calendar#YEAR YEAR} value
1043      * href="Calendar.html#resolution"> resolution rules</a> are applied.
1054      * {@code Calendar} constants are statically imported.
1056      * <p>The following code produces a {@code Calendar} with date 2012-12-31
1061      *   Calendar cal = new Calendar.Builder().setCalendarType("iso8601")
1063      * <p>The following code produces a Japanese {@code Calendar} with date
1064      * 1989-01-08 (Gregorian), assuming that the default {@link Calendar#ERA ERA}
1067      *   Calendar cal = new Calendar.Builder().setCalendarType("japanese")
1071      * @see Calendar#getInstance(TimeZone, Locale)
1072      * @see Calendar#fields
1079         // Calendar.stamp[] (lower half) and Calendar.fields[] (upper half) combined
1094          * Constructs a {@code Calendar.Builder}.
1101          * a millisecond offset from <a href="Calendar.html#Epoch">the
1105          * @return this {@code Calendar.Builder}
1108          * @see Calendar#setTime(Date)
1109          * @see Calendar#setTimeInMillis(long)
1110          * @see Calendar#time
1128          * @return this {@code Calendar.Builder}
1132          * @see Calendar#setTime(Date)
1133          * @see Calendar#setTimeInMillis(long)
1134          * @see Calendar#time
1142          * {@code field} is an index to the {@link Calendar#fields}, such as
1143          * {@link Calendar#DAY_OF_MONTH DAY_OF_MONTH}. Field value validation is
1146          * non-lenient mode when building a {@code Calendar}.
1148          * @param field an index to the {@code Calendar} fields
1150          * @return this {@code Calendar.Builder}
1155          * @see Calendar#set(int, int)
1175          *   setFields(Calendar.YEAR, 2013,
1176          *             Calendar.MONTH, Calendar.DECEMBER,
1177          *             Calendar.DAY_OF_MONTH, 23);</pre>
1181          *   set(Calendar.YEAR, 2013)
1182          *   .set(Calendar.MONTH, Calendar.DECEMBER)
1183          *   .set(Calendar.DAY_OF_MONTH, 23);</pre>
1186          * @return this {@code Calendar.Builder}
1222          *   setFields(Calendar.YEAR, year,
1223          *             Calendar.MONTH, month,
1224          *             Calendar.DAY_OF_MONTH, dayOfMonth);</pre>
1226          * @param year       the {@link Calendar#YEAR YEAR} value
1227          * @param month      the {@link Calendar#MONTH MONTH} value
1229          * @param dayOfMonth the {@link Calendar#DAY_OF_MONTH DAY_OF_MONTH} value
1230          * @return this {@code Calendar.Builder}
1243          * @param hourOfDay the {@link Calendar#HOUR_OF_DAY HOUR_OF_DAY} value
1245          * @param minute    the {@link Calendar#MINUTE MINUTE} value
1246          * @param second    the {@link Calendar#SECOND SECOND} value
1247          * @return this {@code Calendar.Builder}
1258          *   setFields(Calendar.HOUR_OF_DAY, hourOfDay,
1259          *             Calendar.MINUTE, minute,
1260          *             Calendar.SECOND, second,
1261          *             Calendar.MILLISECOND, millis);</pre>
1263          * @param hourOfDay the {@link Calendar#HOUR_OF_DAY HOUR_OF_DAY} value
1265          * @param minute    the {@link Calendar#MINUTE MINUTE} value
1266          * @param second    the {@link Calendar#SECOND SECOND} value
1267          * @param millis    the {@link Calendar#MILLISECOND MILLISECOND} value
1268          * @return this {@code Calendar.Builder}
1285          *     for the {@link Calendar#DAY_OF_WEEK DAY_OF_WEEK} field:
1286          *     {@link Calendar#SUNDAY SUNDAY}, ..., {@link Calendar#SATURDAY SATURDAY}.
1287          * @return this {@code Calendar.Builder}
1288          * @see Calendar#setWeekDate(int, int, int)
1289          * @see Calendar#isWeekDateSupported()
1301          * zone parameter is given to this {@code Calendar.Builder}, the
1307          * @return this {@code Calendar.Builder}
1309          * @see Calendar#setTimeZone(TimeZone)
1321          * If no lenient parameter is given to this {@code Calendar.Builder},
1326          * @return this {@code Calendar.Builder}
1327          * @see Calendar#setLenient(boolean)
1341          * {@link Calendar#getAvailableCalendarTypes() Calendar.getAvailableCalendarTypes}
1346          * @return this {@code Calendar.Builder}
1350          * @see Calendar#getCalendarType()
1351          * @see Calendar#getAvailableCalendarTypes()
1357             if (!Calendar.getAvailableCalendarTypes().contains(type)
1373          * is given to this {@code Calendar.Builder}, the {@linkplain
1380          * {@code Calendar} to be built.
1388          * @return this {@code Calendar.Builder}
1389          * @see Calendar#getInstance(Locale)
1402          * used to determine the <a href="Calendar.html#First_Week">first
1408          *                       {@link Calendar#SUNDAY} to {@link Calendar#SATURDAY}
1411          * @return this {@code Calendar.Builder}
1414          * @see Calendar#getFirstDayOfWeek()
1415          * @see Calendar#getMinimalDaysInFirstWeek()
1428          * Returns a {@code Calendar} built from the parameters set by the
1431          * used to determine what {@code Calendar} to be created. If no explicit
1451          * @return a {@code Calendar} built with parameters of this {@code
1452          *         Calendar.Builder}
1457          * @see Calendar#getInstance(TimeZone, Locale)
1461         public Calendar build() {
1468             Calendar cal;
1521                 // the fields resolution works in the Calendar.
1576      * Constructs a Calendar with the default time zone
1581     protected Calendar()
1593     protected Calendar(TimeZone zone, Locale aLocale)
1605      * <code>Calendar</code> returned is based on the current time
1609      * @return a Calendar.
1611     public static Calendar getInstance()
1618      * The <code>Calendar</code> returned is based on the current time
1623      * @return a Calendar.
1625     public static Calendar getInstance(TimeZone zone)
1632      * The <code>Calendar</code> returned is based on the current time
1636      * @return a Calendar.
1638     public static Calendar getInstance(Locale aLocale)
1645      * The <code>Calendar</code> returned is based on the current time
1650      * @return a Calendar.
1652     public static Calendar getInstance(TimeZone zone,
1658     private static Calendar createCalendar(TimeZone zone,
1672         Calendar cal = null;
1692             // perform the traditional way to create a Calendar:
1716      *         <code>Calendar</code> instances are available.
1747      * <code>Calendar</code>'s time value (millisecond offset from the <a
1759      * Sets this Calendar's time with the given <code>Date</code>.
1774      * Returns this Calendar's time value in milliseconds.
1788      * Sets this Calendar's current time from the given long value.
1846      * <code>Calendar</code> instance.
1970      * this <code>Calendar</code> undefined. This means that {@link
1974      * <code>Calendar</code> implementation class may use its specific
1994      * this <code>Calendar</code> undefined. This means that {@link
1997      * had never been set. A <code>Calendar</code> implementation
2005      * the hour of day value of this <code>Calendar</code>. Use {@link
2006      * #set(int,int) set(Calendar.HOUR_OF_DAY, 0)} to reset the hour
2041      * {@link Calendar#get(int) get(field)} to get the calendar
2045      * <p>For example, if this <code>Calendar</code> is a
2074      *        or if this {@code Calendar} is non-lenient and any
2126      * example, if this {@code Calendar} is a {@link
2137      * this {@code Calendar} is a lunisolar calendar system and
2165      *        or if this {@code Calendar} is non-lenient and any
2347      * <code>Calendar</code> becomes that all the calendar fields are in sync
2392      * Marks this Calendar as not sync'd.
2612      * supported by {@code Calendar} in the runtime environment. The available
2622      * @see Calendar.Builder#setCalendarType(String)
2643      * Returns the calendar type of this {@code Calendar}. Calendar types are
2648      * this {@code Calendar} instance. Any subclasses that implement
2653      *         {@code Calendar} instance
2664      * Compares this <code>Calendar</code> to the specified
2666      * the argument is a <code>Calendar</code> object of the same calendar
2669      * <code>Calendar</code> parameters as this object.
2671      * <p>The <code>Calendar</code> parameters are the values represented
2675      * between the two <code>Calendar</code>s, this method returns
2678      * <p>Use the {@link #compareTo(Calendar) compareTo} method to
2692             Calendar that = (Calendar)obj;
2724      * Returns whether this <code>Calendar</code> represents a time
2730      * if and only if <code>when</code> is a <code>Calendar</code>
2735      * <code>Calendar</code> is before the time represented by
2737      * @see     #compareTo(Calendar)
2740         return when instanceof Calendar
2741             && compareTo((Calendar)when) < 0;
2745      * Returns whether this <code>Calendar</code> represents a time
2751      * if and only if <code>when</code> is a <code>Calendar</code>
2755      * @return <code>true</code> if the time of this <code>Calendar</code> is
2758      * @see     #compareTo(Calendar)
2761         return when instanceof Calendar
2762             && compareTo((Calendar)when) > 0;
2768      * <code>Calendar</code> objects.
2770      * @param anotherCalendar the <code>Calendar</code> to be compared.
2772      * is equal to the time represented by this <code>Calendar</code>; a value
2773      * less than <code>0</code> if the time of this <code>Calendar</code> is
2775      * <code>0</code> if the time of this <code>Calendar</code> is after the
2777      * @exception NullPointerException if the specified <code>Calendar</code> is
2780      * specified <code>Calendar</code> object can't be obtained due to
2785     public int compareTo(Calendar anotherCalendar) {
2793      * <p><code>add(Calendar.DAY_OF_MONTH, -5)</code>.
2806      * <p>roll(Calendar.DATE, true).
2807      * When rolling on the year or Calendar.YEAR field, it will roll the year
2809      * <code>getMaximum(Calendar.YEAR)</code>.
2810      * When rolling on the month or Calendar.MONTH field, other fields like
2813      * When rolling on the hour-in-day or Calendar.HOUR_OF_DAY field, it will
2819      * @see Calendar#add(int,int)
2820      * @see Calendar#set(int,int)
2829      * <p>NOTE:  This default implementation on <code>Calendar</code> just repeatedly calls the
2883         // If the TimeZone object is shared by other Calendar instances, then
3000      * Returns whether this {@code Calendar} supports week dates.
3004      * @return {@code true} if this {@code Calendar} supports week dates;
3016      * Returns the week year represented by this {@code Calendar}. The
3024      * @return the week year of this {@code Calendar}
3027      *            in this {@code Calendar}.
3038      * Sets the date of this {@code Calendar} with the given date
3063      *            {@code Calendar}.
3075      * {@code Calendar}.
3083      *            {@code Calendar}.
3096      * <code>Calendar</code> instance. The minimum value is defined as
3113      * <code>Calendar</code> instance. The maximum value is defined as
3130      * of this <code>Calendar</code> instance. The highest minimum
3148      * of this <code>Calendar</code> instance. The lowest maximum
3152      * the instance. For example, a <code>Calendar</code> for the
3170      * could have, given the time value of this <code>Calendar</code>.
3180      * value of this <code>Calendar</code>
3199         Calendar work = (Calendar)this.clone();
3223      * <code>Calendar</code>. For example, the actual maximum value of
3234      * value of this <code>Calendar</code>
3253         Calendar work = (Calendar)this.clone();
3289             Calendar other = (Calendar) super.clone();
3372      * a given locale. These must be set when a Calendar is constructed.
3406     private static long getMillisOf(Calendar calendar) {
3410         Calendar cal = (Calendar) calendar.clone();
3463         Calendar cal = (Calendar) clone();
3486      * Ideally, <code>Calendar</code> would only write out its state data and
3508         // If this Calendar has a ZoneInfo, save it and set a
3625      * same point on the time-line as this {@code Calendar}.