2 *******************************************************************************
\r
3 * Copyright (C) 1996-2008, International Business Machines Corporation and *
\r
4 * others. All Rights Reserved. *
\r
5 *******************************************************************************
\r
9 package com.ibm.icu.util;
\r
11 import java.io.Serializable;
\r
12 import java.util.Date;
\r
13 import java.util.Locale;
\r
15 import com.ibm.icu.text.DateFormat;
\r
18 * <code>Calendar</code> is an abstract base class for converting between
\r
19 * a <code>Date</code> object and a set of integer fields such as
\r
20 * <code>YEAR</code>, <code>MONTH</code>, <code>DAY</code>, <code>HOUR</code>,
\r
21 * and so on. (A <code>Date</code> object represents a specific instant in
\r
22 * time with millisecond precision. See
\r
24 * for information about the <code>Date</code> class.)
\r
26 * <p><b>Note:</b> This class is similar, but not identical, to the class
\r
27 * <code>java.util.Calendar</code>. Changes are detailed below.
\r
30 * Subclasses of <code>Calendar</code> interpret a <code>Date</code>
\r
31 * according to the rules of a specific calendar system. ICU4J contains
\r
32 * several subclasses implementing different international calendar systems.
\r
35 * Like other locale-sensitive classes, <code>Calendar</code> provides a
\r
36 * class method, <code>getInstance</code>, for getting a generally useful
\r
37 * object of this type. <code>Calendar</code>'s <code>getInstance</code> method
\r
38 * returns a calendar of a type appropriate to the locale, whose
\r
39 * time fields have been initialized with the current date and time:
\r
41 * <pre>Calendar rightNow = Calendar.getInstance()</pre>
\r
44 * <p>When a <code>ULocale</code> is used by <code>getInstance</code>, its
\r
45 * '<code>calendar</code>' tag and value are retrieved if present. If a recognized
\r
46 * value is supplied, a calendar is provided and configured as appropriate.
\r
47 * Currently recognized tags are "buddhist", "chinese", "coptic", "ethiopic",
\r
48 * "gregorian", "hebrew", "islamic", "islamic-civil", and "japanese". For
\r
49 * example: <blockquote>
\r
50 * <pre>Calendar cal = Calendar.getInstance(new ULocale("en_US@calendar=japanese"));</pre>
\r
51 * </blockquote> will return an instance of JapaneseCalendar (using en_US conventions for
\r
52 * minimum days in first week, start day of week, et cetera).
\r
54 * <p>A <code>Calendar</code> object can produce all the time field values
\r
55 * needed to implement the date-time formatting for a particular language and
\r
56 * calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
\r
57 * <code>Calendar</code> defines the range of values returned by certain fields,
\r
58 * as well as their meaning. For example, the first month of the year has value
\r
59 * <code>MONTH</code> == <code>JANUARY</code> for all calendars. Other values
\r
60 * are defined by the concrete subclass, such as <code>ERA</code> and
\r
61 * <code>YEAR</code>. See individual field documentation and subclass
\r
62 * documentation for details.
\r
64 * <p>When a <code>Calendar</code> is <em>lenient</em>, it accepts a wider range
\r
65 * of field values than it produces. For example, a lenient
\r
66 * <code>GregorianCalendar</code> interprets <code>MONTH</code> ==
\r
67 * <code>JANUARY</code>, <code>DAY_OF_MONTH</code> == 32 as February 1. A
\r
68 * non-lenient <code>GregorianCalendar</code> throws an exception when given
\r
69 * out-of-range field settings. When calendars recompute field values for
\r
70 * return by <code>get()</code>, they normalize them. For example, a
\r
71 * <code>GregorianCalendar</code> always produces <code>DAY_OF_MONTH</code>
\r
72 * values between 1 and the length of the month.
\r
74 * <p><code>Calendar</code> defines a locale-specific seven day week using two
\r
75 * parameters: the first day of the week and the minimal days in first week
\r
76 * (from 1 to 7). These numbers are taken from the locale resource data when a
\r
77 * <code>Calendar</code> is constructed. They may also be specified explicitly
\r
80 * <p>When setting or getting the <code>WEEK_OF_MONTH</code> or
\r
81 * <code>WEEK_OF_YEAR</code> fields, <code>Calendar</code> must determine the
\r
82 * first week of the month or year as a reference point. The first week of a
\r
83 * month or year is defined as the earliest seven day period beginning on
\r
84 * <code>getFirstDayOfWeek()</code> and containing at least
\r
85 * <code>getMinimalDaysInFirstWeek()</code> days of that month or year. Weeks
\r
86 * numbered ..., -1, 0 precede the first week; weeks numbered 2, 3,... follow
\r
87 * it. Note that the normalized numbering returned by <code>get()</code> may be
\r
88 * different. For example, a specific <code>Calendar</code> subclass may
\r
89 * designate the week before week 1 of a year as week <em>n</em> of the previous
\r
92 * <p> When computing a <code>Date</code> from time fields, two special
\r
93 * circumstances may arise: there may be insufficient information to compute the
\r
94 * <code>Date</code> (such as only year and month but no day in the month), or
\r
95 * there may be inconsistent information (such as "Tuesday, July 15, 1996" --
\r
96 * July 15, 1996 is actually a Monday).
\r
99 * <strong>Insufficient information.</strong> The calendar will use default
\r
100 * information to specify the missing fields. This may vary by calendar; for
\r
101 * the Gregorian calendar, the default for a field is the same as that of the
\r
102 * start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc.
\r
105 * <strong>Inconsistent information.</strong> If fields conflict, the calendar
\r
106 * will give preference to fields set more recently. For example, when
\r
107 * determining the day, the calendar will look for one of the following
\r
108 * combinations of fields. The most recent combination, as determined by the
\r
109 * most recently set single field, will be used.
\r
113 * MONTH + DAY_OF_MONTH
\r
114 * MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
\r
115 * MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
\r
117 * DAY_OF_WEEK + WEEK_OF_YEAR</pre>
\r
120 * For the time of day:
\r
125 * AM_PM + HOUR</pre>
\r
129 * <strong>Note:</strong> for some non-Gregorian calendars, different
\r
130 * fields may be necessary for complete disambiguation. For example, a full
\r
131 * specification of the historial Arabic astronomical calendar requires year,
\r
132 * month, day-of-month <em>and</em> day-of-week in some cases.
\r
135 * <strong>Note:</strong> There are certain possible ambiguities in
\r
136 * interpretation of certain singular times, which are resolved in the
\r
139 * <li> 24:00:00 "belongs" to the following day. That is,
\r
140 * 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970
\r
142 * <li> Although historically not precise, midnight also belongs to "am",
\r
143 * and noon belongs to "pm", so on the same day,
\r
144 * 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm
\r
148 * The date or time format strings are not part of the definition of a
\r
149 * calendar, as those must be modifiable or overridable by the user at
\r
150 * runtime. Use {@link DateFormat}
\r
153 * <p><strong>Field manipulation methods</strong></p>
\r
155 * <p><code>Calendar</code> fields can be changed using three methods:
\r
156 * <code>set()</code>, <code>add()</code>, and <code>roll()</code>.</p>
\r
158 * <p><strong><code>set(f, value)</code></strong> changes field
\r
159 * <code>f</code> to <code>value</code>. In addition, it sets an
\r
160 * internal member variable to indicate that field <code>f</code> has
\r
161 * been changed. Although field <code>f</code> is changed immediately,
\r
162 * the calendar's milliseconds is not recomputed until the next call to
\r
163 * <code>get()</code>, <code>getTime()</code>, or
\r
164 * <code>getTimeInMillis()</code> is made. Thus, multiple calls to
\r
165 * <code>set()</code> do not trigger multiple, unnecessary
\r
166 * computations. As a result of changing a field using
\r
167 * <code>set()</code>, other fields may also change, depending on the
\r
168 * field, the field value, and the calendar system. In addition,
\r
169 * <code>get(f)</code> will not necessarily return <code>value</code>
\r
170 * after the fields have been recomputed. The specifics are determined by
\r
171 * the concrete calendar class.</p>
\r
173 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
\r
174 * originally set to August 31, 1999. Calling <code>set(Calendar.MONTH,
\r
175 * Calendar.SEPTEMBER)</code> sets the calendar to September 31,
\r
176 * 1999. This is a temporary internal representation that resolves to
\r
177 * October 1, 1999 if <code>getTime()</code>is then called. However, a
\r
178 * call to <code>set(Calendar.DAY_OF_MONTH, 30)</code> before the call to
\r
179 * <code>getTime()</code> sets the calendar to September 30, 1999, since
\r
180 * no recomputation occurs after <code>set()</code> itself.</p>
\r
182 * <p><strong><code>add(f, delta)</code></strong> adds <code>delta</code>
\r
183 * to field <code>f</code>. This is equivalent to calling <code>set(f,
\r
184 * get(f) + delta)</code> with two adjustments:</p>
\r
187 * <p><strong>Add rule 1</strong>. The value of field <code>f</code>
\r
188 * after the call minus the value of field <code>f</code> before the
\r
189 * call is <code>delta</code>, modulo any overflow that has occurred in
\r
190 * field <code>f</code>. Overflow occurs when a field value exceeds its
\r
191 * range and, as a result, the next larger field is incremented or
\r
192 * decremented and the field value is adjusted back into its range.</p>
\r
194 * <p><strong>Add rule 2</strong>. If a smaller field is expected to be
\r
195 * invariant, but it is impossible for it to be equal to its
\r
196 * prior value because of changes in its minimum or maximum after field
\r
197 * <code>f</code> is changed, then its value is adjusted to be as close
\r
198 * as possible to its expected value. A smaller field represents a
\r
199 * smaller unit of time. <code>HOUR</code> is a smaller field than
\r
200 * <code>DAY_OF_MONTH</code>. No adjustment is made to smaller fields
\r
201 * that are not expected to be invariant. The calendar system
\r
202 * determines what fields are expected to be invariant.</p>
\r
205 * <p>In addition, unlike <code>set()</code>, <code>add()</code> forces
\r
206 * an immediate recomputation of the calendar's milliseconds and all
\r
209 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
\r
210 * originally set to August 31, 1999. Calling <code>add(Calendar.MONTH,
\r
211 * 13)</code> sets the calendar to September 30, 2000. <strong>Add rule
\r
212 * 1</strong> sets the <code>MONTH</code> field to September, since
\r
213 * adding 13 months to August gives September of the next year. Since
\r
214 * <code>DAY_OF_MONTH</code> cannot be 31 in September in a
\r
215 * <code>GregorianCalendar</code>, <strong>add rule 2</strong> sets the
\r
216 * <code>DAY_OF_MONTH</code> to 30, the closest possible value. Although
\r
217 * it is a smaller field, <code>DAY_OF_WEEK</code> is not adjusted by
\r
218 * rule 2, since it is expected to change when the month changes in a
\r
219 * <code>GregorianCalendar</code>.</p>
\r
221 * <p><strong><code>roll(f, delta)</code></strong> adds
\r
222 * <code>delta</code> to field <code>f</code> without changing larger
\r
223 * fields. This is equivalent to calling <code>add(f, delta)</code> with
\r
224 * the following adjustment:</p>
\r
227 * <p><strong>Roll rule</strong>. Larger fields are unchanged after the
\r
228 * call. A larger field represents a larger unit of
\r
229 * time. <code>DAY_OF_MONTH</code> is a larger field than
\r
230 * <code>HOUR</code>.</p>
\r
233 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
\r
234 * originally set to August 31, 1999. Calling <code>roll(Calendar.MONTH,
\r
235 * 8)</code> sets the calendar to April 30, <strong>1999</strong>. Add
\r
236 * rule 1 sets the <code>MONTH</code> field to April. Using a
\r
237 * <code>GregorianCalendar</code>, the <code>DAY_OF_MONTH</code> cannot
\r
238 * be 31 in the month April. Add rule 2 sets it to the closest possible
\r
239 * value, 30. Finally, the <strong>roll rule</strong> maintains the
\r
240 * <code>YEAR</code> field value of 1999.</p>
\r
242 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
\r
243 * originally set to Sunday June 6, 1999. Calling
\r
244 * <code>roll(Calendar.WEEK_OF_MONTH, -1)</code> sets the calendar to
\r
245 * Tuesday June 1, 1999, whereas calling
\r
246 * <code>add(Calendar.WEEK_OF_MONTH, -1)</code> sets the calendar to
\r
247 * Sunday May 30, 1999. This is because the roll rule imposes an
\r
248 * additional constraint: The <code>MONTH</code> must not change when the
\r
249 * <code>WEEK_OF_MONTH</code> is rolled. Taken together with add rule 1,
\r
250 * the resultant date must be between Tuesday June 1 and Saturday June
\r
251 * 5. According to add rule 2, the <code>DAY_OF_WEEK</code>, an invariant
\r
252 * when changing the <code>WEEK_OF_MONTH</code>, is set to Tuesday, the
\r
253 * closest possible value to Sunday (where Sunday is the first day of the
\r
256 * <p><strong>Usage model</strong>. To motivate the behavior of
\r
257 * <code>add()</code> and <code>roll()</code>, consider a user interface
\r
258 * component with increment and decrement buttons for the month, day, and
\r
259 * year, and an underlying <code>GregorianCalendar</code>. If the
\r
260 * interface reads January 31, 1999 and the user presses the month
\r
261 * increment button, what should it read? If the underlying
\r
262 * implementation uses <code>set()</code>, it might read March 3, 1999. A
\r
263 * better result would be February 28, 1999. Furthermore, if the user
\r
264 * presses the month increment button again, it should read March 31,
\r
265 * 1999, not March 28, 1999. By saving the original date and using either
\r
266 * <code>add()</code> or <code>roll()</code>, depending on whether larger
\r
267 * fields should be affected, the user interface can behave as most users
\r
268 * will intuitively expect.</p>
\r
270 * <p><b>Note:</b> You should always use {@link #roll roll} and {@link #add add} rather
\r
271 * than attempting to perform arithmetic operations directly on the fields
\r
272 * of a <tt>Calendar</tt>. It is quite possible for <tt>Calendar</tt> subclasses
\r
273 * to have fields with non-linear behavior, for example missing months
\r
274 * or days during non-leap years. The subclasses' <tt>add</tt> and <tt>roll</tt>
\r
275 * methods will take this into account, while simple arithmetic manipulations
\r
276 * may give invalid results.
\r
278 * <p><big><big><b>Calendar Architecture in ICU4J</b></big></big></p>
\r
280 * <p>Recently the implementation of <code>Calendar</code> has changed
\r
281 * significantly in order to better support subclassing. The original
\r
282 * <code>Calendar</code> class was designed to support subclassing, but
\r
283 * it had only one implemented subclass, <code>GregorianCalendar</code>.
\r
284 * With the implementation of several new calendar subclasses, including
\r
285 * the <code>BuddhistCalendar</code>, <code>ChineseCalendar</code>,
\r
286 * <code>HebrewCalendar</code>, <code>IslamicCalendar</code>, and
\r
287 * <code>JapaneseCalendar</code>, the subclassing API has been reworked
\r
288 * thoroughly. This section details the new subclassing API and other
\r
289 * ways in which <code>com.ibm.icu.util.Calendar</code> differs from
\r
290 * <code>java.util.Calendar</code>.
\r
293 * <p><big><b>Changes</b></big></p>
\r
295 * <p>Overview of changes between the classic <code>Calendar</code>
\r
296 * architecture and the new architecture.
\r
300 * <li>The <code>fields[]</code> array is <code>private</code> now
\r
301 * instead of <code>protected</code>. Subclasses must access it
\r
302 * using the methods {@link #internalSet} and
\r
303 * {@link #internalGet}. <b>Motivation:</b> Subclasses should
\r
304 * not directly access data members.</li>
\r
306 * <li>The <code>time</code> long word is <code>private</code> now
\r
307 * instead of <code>protected</code>. Subclasses may access it using
\r
308 * the method {@link #internalGetTimeInMillis}, which does not
\r
309 * provoke an update. <b>Motivation:</b> Subclasses should not
\r
310 * directly access data members.</li>
\r
312 * <li>The scope of responsibility of subclasses has been drastically
\r
313 * reduced. As much functionality as possible is implemented in the
\r
314 * <code>Calendar</code> base class. As a result, it is much easier
\r
315 * to subclass <code>Calendar</code>. <b>Motivation:</b> Subclasses
\r
316 * should not have to reimplement common code. Certain behaviors are
\r
317 * common across calendar systems: The definition and behavior of
\r
318 * week-related fields and time fields, the arithmetic
\r
319 * ({@link #add(int, int) add} and {@link #roll(int, int) roll}) behavior of many
\r
320 * fields, and the field validation system.</li>
\r
322 * <li>The subclassing API has been completely redesigned.</li>
\r
324 * <li>The <code>Calendar</code> base class contains some Gregorian
\r
325 * calendar algorithmic support that subclasses can use (specifically
\r
326 * in {@link #handleComputeFields}). Subclasses can use the
\r
327 * methods <code>getGregorianXxx()</code> to obtain precomputed
\r
328 * values. <b>Motivation:</b> This is required by all
\r
329 * <code>Calendar</code> subclasses in order to implement consistent
\r
330 * time zone behavior, and Gregorian-derived systems can use the
\r
331 * already computed data.</li>
\r
333 * <li>The <code>FIELD_COUNT</code> constant has been removed. Use
\r
334 * {@link #getFieldCount}. In addition, framework API has been
\r
335 * added to allow subclasses to define additional fields.
\r
336 * <b>Motivation: </b>The number of fields is not constant across
\r
337 * calendar systems.</li>
\r
339 * <li>The range of handled dates has been narrowed from +/-
\r
340 * ~300,000,000 years to +/- ~5,000,000 years. In practical terms
\r
341 * this should not affect clients. However, it does mean that client
\r
342 * code cannot be guaranteed well-behaved results with dates such as
\r
343 * <code>Date(Long.MIN_VALUE)</code> or
\r
344 * <code>Date(Long.MAX_VALUE)</code>. Instead, the
\r
345 * <code>Calendar</code> constants {@link #MIN_DATE},
\r
346 * {@link #MAX_DATE}, {@link #MIN_MILLIS},
\r
347 * {@link #MAX_MILLIS}, {@link #MIN_JULIAN}, and
\r
348 * {@link #MAX_JULIAN} should be used. <b>Motivation:</b> With
\r
349 * the addition of the {@link #JULIAN_DAY} field, Julian day
\r
350 * numbers must be restricted to a 32-bit <code>int</code>. This
\r
351 * restricts the overall supported range. Furthermore, restricting
\r
352 * the supported range simplifies the computations by removing
\r
353 * special case code that was used to accomodate arithmetic overflow
\r
354 * at millis near <code>Long.MIN_VALUE</code> and
\r
355 * <code>Long.MAX_VALUE</code>.</li>
\r
357 * <li>New fields are implemented: {@link #JULIAN_DAY} defines
\r
358 * single-field specification of the
\r
359 * date. {@link #MILLISECONDS_IN_DAY} defines a single-field
\r
360 * specification of the wall time. {@link #DOW_LOCAL} and
\r
361 * {@link #YEAR_WOY} implement localized day-of-week and
\r
362 * week-of-year behavior.</li>
\r
364 * <li>Subclasses can access millisecond constants
\r
365 * {@link #ONE_SECOND}, {@link #ONE_MINUTE},
\r
366 * {@link #ONE_HOUR}, {@link #ONE_DAY}, and
\r
367 * {@link #ONE_WEEK} defined in <code>Calendar</code>.</li>
\r
369 * <li>New API has been added to suport calendar-specific subclasses
\r
370 * of <code>DateFormat</code>.</li>
\r
372 * <li>Several subclasses have been implemented, representing
\r
373 * various international calendar systems.</li>
\r
377 * <p><big><b>Subclass API</b></big></p>
\r
379 * <p>The original <code>Calendar</code> API was based on the experience
\r
380 * of implementing a only a single subclass,
\r
381 * <code>GregorianCalendar</code>. As a result, all of the subclassing
\r
382 * kinks had not been worked out. The new subclassing API has been
\r
383 * refined based on several implemented subclasses. This includes methods
\r
384 * that must be overridden and methods for subclasses to call. Subclasses
\r
385 * no longer have direct access to <code>fields</code> and
\r
386 * <code>stamp</code>. Instead, they have new API to access
\r
387 * these. Subclasses are able to allocate the <code>fields</code> array
\r
388 * through a protected framework method; this allows subclasses to
\r
389 * specify additional fields. </p>
\r
391 * <p>More functionality has been moved into the base class. The base
\r
392 * class now contains much of the computational machinery to support the
\r
393 * Gregorian calendar. This is based on two things: (1) Many calendars
\r
394 * are based on the Gregorian calendar (such as the Buddhist and Japanese
\r
395 * imperial calendars). (2) <em>All</em> calendars require basic
\r
396 * Gregorian support in order to handle timezone computations. </p>
\r
398 * <p>Common computations have been moved into
\r
399 * <code>Calendar</code>. Subclasses no longer compute the week related
\r
400 * fields and the time related fields. These are commonly handled for all
\r
401 * calendars by the base class. </p>
\r
403 * <p><b>Subclass computation of time <tt>=></tt> fields</b>
\r
405 * <p>The {@link #ERA}, {@link #YEAR},
\r
406 * {@link #EXTENDED_YEAR}, {@link #MONTH},
\r
407 * {@link #DAY_OF_MONTH}, and {@link #DAY_OF_YEAR} fields are
\r
408 * computed by the subclass, based on the Julian day. All other fields
\r
409 * are computed by <code>Calendar</code>.
\r
413 * <li>Subclasses should implement {@link #handleComputeFields}
\r
414 * to compute the {@link #ERA}, {@link #YEAR},
\r
415 * {@link #EXTENDED_YEAR}, {@link #MONTH},
\r
416 * {@link #DAY_OF_MONTH}, and {@link #DAY_OF_YEAR} fields,
\r
417 * based on the value of the {@link #JULIAN_DAY} field. If there
\r
418 * are calendar-specific fields not defined by <code>Calendar</code>,
\r
419 * they must also be computed. These are the only fields that the
\r
420 * subclass should compute. All other fields are computed by the base
\r
421 * class, so time and week fields behave in a consistent way across
\r
422 * all calendars. The default version of this method in
\r
423 * <code>Calendar</code> implements a proleptic Gregorian
\r
424 * calendar. Within this method, subclasses may call
\r
425 * <code>getGregorianXxx()</code> to obtain the Gregorian calendar
\r
426 * month, day of month, and extended year for the given date.</li>
\r
430 * <p><b>Subclass computation of fields <tt>=></tt> time</b>
\r
432 * <p>The interpretation of most field values is handled entirely by
\r
433 * <code>Calendar</code>. <code>Calendar</code> determines which fields
\r
434 * are set, which are not, which are set more recently, and so on. In
\r
435 * addition, <code>Calendar</code> handles the computation of the time
\r
436 * from the time fields and handles the week-related fields. The only
\r
437 * thing the subclass must do is determine the extended year, based on
\r
438 * the year fields, and then, given an extended year and a month, it must
\r
439 * return a Julian day number.
\r
443 * <li>Subclasses should implement {@link #handleGetExtendedYear}
\r
444 * to return the extended year for this calendar system, based on the
\r
445 * {@link #YEAR}, {@link #EXTENDED_YEAR}, and any fields that
\r
446 * the calendar system uses that are larger than a year, such as
\r
447 * {@link #ERA}.</li>
\r
449 * <li>Subclasses should implement {@link #handleComputeMonthStart}
\r
450 * to return the Julian day number
\r
451 * associated with a month and extended year. This is the Julian day
\r
452 * number of the day before the first day of the month. The month
\r
453 * number is zero-based. This computation should not depend on any
\r
454 * field values.</li>
\r
458 * <p><b>Other methods</b>
\r
462 * <li>Subclasses should implement {@link #handleGetMonthLength}
\r
463 * to return the number of days in a
\r
464 * given month of a given extended year. The month number, as always,
\r
465 * is zero-based.</li>
\r
467 * <li>Subclasses should implement {@link #handleGetYearLength}
\r
468 * to return the number of days in the given
\r
469 * extended year. This method is used by
\r
470 * <tt>computeWeekFields</tt> to compute the
\r
471 * {@link #WEEK_OF_YEAR} and {@link #YEAR_WOY} fields.</li>
\r
473 * <li>Subclasses should implement {@link #handleGetLimit}
\r
474 * to return the {@link #MINIMUM},
\r
475 * {@link #GREATEST_MINIMUM}, {@link #LEAST_MAXIMUM}, or
\r
476 * {@link #MAXIMUM} of a field, depending on the value of
\r
477 * <code>limitType</code>. This method only needs to handle the
\r
478 * fields {@link #ERA}, {@link #YEAR}, {@link #MONTH},
\r
479 * {@link #WEEK_OF_YEAR}, {@link #WEEK_OF_MONTH},
\r
480 * {@link #DAY_OF_MONTH}, {@link #DAY_OF_YEAR},
\r
481 * {@link #DAY_OF_WEEK_IN_MONTH}, {@link #YEAR_WOY}, and
\r
482 * {@link #EXTENDED_YEAR}. Other fields are invariant (with
\r
483 * respect to calendar system) and are handled by the base
\r
486 * <li>Optionally, subclasses may override {@link #validateField}
\r
487 * to check any subclass-specific fields. If the
\r
488 * field's value is out of range, the method should throw an
\r
489 * <code>IllegalArgumentException</code>. The method may call
\r
490 * <code>super.validateField(field)</code> to handle fields in a
\r
491 * generic way, that is, to compare them to the range
\r
492 * <code>getMinimum(field)</code>..<code>getMaximum(field)</code>.</li>
\r
494 * <li>Optionally, subclasses may override
\r
495 * {@link #handleCreateFields} to create an <code>int[]</code>
\r
496 * array large enough to hold the calendar's fields. This is only
\r
497 * necessary if the calendar defines additional fields beyond those
\r
498 * defined by <code>Calendar</code>. The length of the result must be
\r
499 * at least {@link #BASE_FIELD_COUNT} and no more than
\r
500 * {@link #MAX_FIELD_COUNT}.</li>
\r
502 * <li>Optionally, subclasses may override
\r
503 * {@link #handleGetDateFormat} to create a
\r
504 * <code>DateFormat</code> appropriate to this calendar. This is only
\r
505 * required if a calendar subclass redefines the use of a field (for
\r
506 * example, changes the {@link #ERA} field from a symbolic field
\r
507 * to a numeric one) or defines an additional field.</li>
\r
509 * <li>Optionally, subclasses may override {@link #roll roll} and
\r
510 * {@link #add add} to handle fields that are discontinuous. For
\r
511 * example, in the Hebrew calendar the month "Adar I" only
\r
512 * occurs in leap years; in other years the calendar jumps from
\r
513 * Shevat (month #4) to Adar (month #6). The {@link
\r
514 * HebrewCalendar#add HebrewCalendar.add} and {@link
\r
515 * HebrewCalendar#roll HebrewCalendar.roll} methods take this into
\r
516 * account, so that adding 1 month to Shevat gives the proper result
\r
517 * (Adar) in a non-leap year. The protected utility method {@link
\r
518 * #pinField pinField} is often useful when implementing these two
\r
523 * <p><big><b>Normalized behavior</b></big>
\r
525 * <p>The behavior of certain fields has been made consistent across all
\r
526 * calendar systems and implemented in <code>Calendar</code>.
\r
530 * <li>Time is normalized. Even though some calendar systems transition
\r
531 * between days at sunset or at other times, all ICU4J calendars
\r
532 * transition between days at <em>local zone midnight</em>. This
\r
533 * allows ICU4J to centralize the time computations in
\r
534 * <code>Calendar</code> and to maintain basic correpsondences
\r
535 * between calendar systems. Affected fields: {@link #AM_PM},
\r
536 * {@link #HOUR}, {@link #HOUR_OF_DAY}, {@link #MINUTE},
\r
537 * {@link #SECOND}, {@link #MILLISECOND},
\r
538 * {@link #ZONE_OFFSET}, and {@link #DST_OFFSET}.</li>
\r
540 * <li>DST behavior is normalized. Daylight savings time behavior is
\r
541 * computed the same for all calendar systems, and depends on the
\r
542 * value of several <code>GregorianCalendar</code> fields: the
\r
543 * {@link #YEAR}, {@link #MONTH}, and
\r
544 * {@link #DAY_OF_MONTH}. As a result, <code>Calendar</code>
\r
545 * always computes these fields, even for non-Gregorian calendar
\r
546 * systems. These fields are available to subclasses.</li>
\r
548 * <li>Weeks are normalized. Although locales define the week
\r
549 * differently, in terms of the day on which it starts, and the
\r
550 * designation of week number one of a month or year, they all use a
\r
551 * common mechanism. Furthermore, the day of the week has a simple
\r
552 * and consistent definition throughout history. For example,
\r
553 * although the Gregorian calendar introduced a discontinuity when
\r
554 * first instituted, the day of week was not disrupted. For this
\r
555 * reason, the fields {@link #DAY_OF_WEEK}, <code>WEEK_OF_YEAR,
\r
556 * WEEK_OF_MONTH</code>, {@link #DAY_OF_WEEK_IN_MONTH},
\r
557 * {@link #DOW_LOCAL}, {@link #YEAR_WOY} are all computed in
\r
558 * a consistent way in the base class, based on the
\r
559 * {@link #EXTENDED_YEAR}, {@link #DAY_OF_YEAR},
\r
560 * {@link #MONTH}, and {@link #DAY_OF_MONTH}, which are
\r
561 * computed by the subclass.</li>
\r
565 * <p><big><b>Supported range</b></big>
\r
567 * <p>The allowable range of <code>Calendar</code> has been
\r
568 * narrowed. <code>GregorianCalendar</code> used to attempt to support
\r
569 * the range of dates with millisecond values from
\r
570 * <code>Long.MIN_VALUE</code> to <code>Long.MAX_VALUE</code>. This
\r
571 * introduced awkward constructions (hacks) which slowed down
\r
572 * performance. It also introduced non-uniform behavior at the
\r
573 * boundaries. The new <code>Calendar</code> protocol specifies the
\r
574 * maximum range of supportable dates as those having Julian day numbers
\r
575 * of <code>-0x7F000000</code> to <code>+0x7F000000</code>. This
\r
576 * corresponds to years from ~5,000,000 BCE to ~5,000,000 CE. Programmers
\r
577 * should use the constants {@link #MIN_DATE} (or
\r
578 * {@link #MIN_MILLIS} or {@link #MIN_JULIAN}) and
\r
579 * {@link #MAX_DATE} (or {@link #MAX_MILLIS} or
\r
580 * {@link #MAX_JULIAN}) in <code>Calendar</code> to specify an
\r
581 * extremely early or extremely late date.</p>
\r
583 * <p><big><b>General notes</b></big>
\r
587 * <li>Calendars implementations are <em>proleptic</em>. For example,
\r
588 * even though the Gregorian calendar was not instituted until the
\r
589 * 16th century, the <code>GregorianCalendar</code> class supports
\r
590 * dates before the historical onset of the calendar by extending the
\r
591 * calendar system backward in time. Similarly, the
\r
592 * <code>HebrewCalendar</code> extends backward before the start of
\r
593 * its epoch into zero and negative years. Subclasses do not throw
\r
594 * exceptions because a date precedes the historical start of a
\r
595 * calendar system. Instead, they implement
\r
596 * {@link #handleGetLimit} to return appropriate limits on
\r
597 * {@link #YEAR}, {@link #ERA}, etc. fields. Then, if the
\r
598 * calendar is set to not be lenient, out-of-range field values will
\r
599 * trigger an exception.</li>
\r
601 * <li>Calendar system subclasses compute a <em>extended
\r
602 * year</em>. This differs from the {@link #YEAR} field in that
\r
603 * it ranges over all integer values, including zero and negative
\r
604 * values, and it encapsulates the information of the
\r
605 * {@link #YEAR} field and all larger fields. Thus, for the
\r
606 * Gregorian calendar, the {@link #EXTENDED_YEAR} is computed as
\r
607 * <code>ERA==AD ? YEAR : 1-YEAR</code>. Another example is the Mayan
\r
608 * long count, which has years (<code>KUN</code>) and nested cycles
\r
609 * of years (<code>KATUN</code> and <code>BAKTUN</code>). The Mayan
\r
610 * {@link #EXTENDED_YEAR} is computed as <code>TUN + 20 * (KATUN
\r
611 * + 20 * BAKTUN)</code>. The <code>Calendar</code> base class uses
\r
612 * the {@link #EXTENDED_YEAR} field to compute the week-related
\r
618 * @see GregorianCalendar
\r
621 * @author Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu, Laura Werner
\r
624 public class Calendar implements Serializable, Cloneable, Comparable {
\r
625 private static final long serialVersionUID = 1;
\r
630 public final java.util.Calendar calendar;
\r
634 * @param delegate the Calendar to which to delegate
\r
636 public Calendar(java.util.Calendar delegate) {
\r
637 this.calendar = delegate;
\r
642 * Field number for <code>get</code> and <code>set</code> indicating the
\r
643 * era, e.g., AD or BC in the Julian calendar. This is a calendar-specific
\r
644 * value; see subclass documentation.
\r
645 * @see GregorianCalendar#AD
\r
646 * @see GregorianCalendar#BC
\r
649 public final static int ERA = 0;
\r
652 * Field number for <code>get</code> and <code>set</code> indicating the
\r
653 * year. This is a calendar-specific value; see subclass documentation.
\r
656 public final static int YEAR = 1;
\r
659 * Field number for <code>get</code> and <code>set</code> indicating the
\r
660 * month. This is a calendar-specific value. The first month of the year is
\r
661 * <code>JANUARY</code>; the last depends on the number of months in a year.
\r
677 public final static int MONTH = 2;
\r
680 * Field number for <code>get</code> and <code>set</code> indicating the
\r
681 * week number within the current year. The first week of the year, as
\r
682 * defined by <code>getFirstDayOfWeek()</code> and
\r
683 * <code>getMinimalDaysInFirstWeek()</code>, has value 1. Subclasses define
\r
684 * the value of <code>WEEK_OF_YEAR</code> for days before the first week of
\r
686 * @see #getFirstDayOfWeek
\r
687 * @see #getMinimalDaysInFirstWeek
\r
690 public final static int WEEK_OF_YEAR = 3;
\r
693 * Field number for <code>get</code> and <code>set</code> indicating the
\r
694 * week number within the current month. The first week of the month, as
\r
695 * defined by <code>getFirstDayOfWeek()</code> and
\r
696 * <code>getMinimalDaysInFirstWeek()</code>, has value 1. Subclasses define
\r
697 * the value of <code>WEEK_OF_MONTH</code> for days before the first week of
\r
699 * @see #getFirstDayOfWeek
\r
700 * @see #getMinimalDaysInFirstWeek
\r
703 public final static int WEEK_OF_MONTH = 4;
\r
706 * Field number for <code>get</code> and <code>set</code> indicating the
\r
707 * day of the month. This is a synonym for <code>DAY_OF_MONTH</code>.
\r
708 * The first day of the month has value 1.
\r
709 * @see #DAY_OF_MONTH
\r
712 public final static int DATE = 5;
\r
715 * Field number for <code>get</code> and <code>set</code> indicating the
\r
716 * day of the month. This is a synonym for <code>DATE</code>.
\r
717 * The first day of the month has value 1.
\r
721 public final static int DAY_OF_MONTH = 5;
\r
724 * Field number for <code>get</code> and <code>set</code> indicating the day
\r
725 * number within the current year. The first day of the year has value 1.
\r
728 public final static int DAY_OF_YEAR = 6;
\r
731 * Field number for <code>get</code> and <code>set</code> indicating the day
\r
732 * of the week. This field takes values <code>SUNDAY</code>,
\r
733 * <code>MONDAY</code>, <code>TUESDAY</code>, <code>WEDNESDAY</code>,
\r
734 * <code>THURSDAY</code>, <code>FRIDAY</code>, and <code>SATURDAY</code>.
\r
744 public final static int DAY_OF_WEEK = 7;
\r
747 * Field number for <code>get</code> and <code>set</code> indicating the
\r
748 * ordinal number of the day of the week within the current month. Together
\r
749 * with the <code>DAY_OF_WEEK</code> field, this uniquely specifies a day
\r
750 * within a month. Unlike <code>WEEK_OF_MONTH</code> and
\r
751 * <code>WEEK_OF_YEAR</code>, this field's value does <em>not</em> depend on
\r
752 * <code>getFirstDayOfWeek()</code> or
\r
753 * <code>getMinimalDaysInFirstWeek()</code>. <code>DAY_OF_MONTH 1</code>
\r
754 * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH
\r
755 * 1</code>; <code>8</code> through <code>15</code> correspond to
\r
756 * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on.
\r
757 * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before
\r
758 * <code>DAY_OF_WEEK_IN_MONTH 1</code>. Negative values count back from the
\r
759 * end of the month, so the last Sunday of a month is specified as
\r
760 * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>. Because
\r
761 * negative values count backward they will usually be aligned differently
\r
762 * within the month than positive values. For example, if a month has 31
\r
763 * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap
\r
764 * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>.
\r
765 * @see #DAY_OF_WEEK
\r
766 * @see #WEEK_OF_MONTH
\r
769 public final static int DAY_OF_WEEK_IN_MONTH = 8;
\r
772 * Field number for <code>get</code> and <code>set</code> indicating
\r
773 * whether the <code>HOUR</code> is before or after noon.
\r
774 * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>.
\r
780 public final static int AM_PM = 9;
\r
783 * Field number for <code>get</code> and <code>set</code> indicating the
\r
784 * hour of the morning or afternoon. <code>HOUR</code> is used for the 12-hour
\r
786 * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10.
\r
788 * @see #HOUR_OF_DAY
\r
791 public final static int HOUR = 10;
\r
794 * Field number for <code>get</code> and <code>set</code> indicating the
\r
795 * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock.
\r
796 * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22.
\r
800 public final static int HOUR_OF_DAY = 11;
\r
803 * Field number for <code>get</code> and <code>set</code> indicating the
\r
804 * minute within the hour.
\r
805 * E.g., at 10:04:15.250 PM the <code>MINUTE</code> is 4.
\r
808 public final static int MINUTE = 12;
\r
811 * Field number for <code>get</code> and <code>set</code> indicating the
\r
812 * second within the minute.
\r
813 * E.g., at 10:04:15.250 PM the <code>SECOND</code> is 15.
\r
816 public final static int SECOND = 13;
\r
819 * Field number for <code>get</code> and <code>set</code> indicating the
\r
820 * millisecond within the second.
\r
821 * E.g., at 10:04:15.250 PM the <code>MILLISECOND</code> is 250.
\r
824 public final static int MILLISECOND = 14;
\r
827 * Field number for <code>get</code> and <code>set</code> indicating the
\r
828 * raw offset from GMT in milliseconds.
\r
831 public final static int ZONE_OFFSET = 15;
\r
834 * Field number for <code>get</code> and <code>set</code> indicating the
\r
835 * daylight savings offset in milliseconds.
\r
838 public final static int DST_OFFSET = 16;
\r
841 * Field number for <code>get()</code> and <code>set()</code>
\r
842 * indicating the extended year corresponding to the
\r
843 * <code>WEEK_OF_YEAR</code> field. This may be one greater or less
\r
844 * than the value of <code>EXTENDED_YEAR</code>.
\r
847 public static final int YEAR_WOY = 17;
\r
850 * Field number for <code>get()</code> and <code>set()</code>
\r
851 * indicating the localized day of week. This will be a value from 1
\r
852 * to 7 inclusive, with 1 being the localized first day of the week.
\r
855 public static final int DOW_LOCAL = 18;
\r
858 * Field number for <code>get()</code> and <code>set()</code>
\r
859 * indicating the extended year. This is a single number designating
\r
860 * the year of this calendar system, encompassing all supra-year
\r
861 * fields. For example, for the Julian calendar system, year numbers
\r
862 * are positive, with an era of BCE or CE. An extended year value for
\r
863 * the Julian calendar system assigns positive values to CE years and
\r
864 * negative values to BCE years, with 1 BCE being year 0.
\r
867 public static final int EXTENDED_YEAR = 19;
\r
870 * Field number for <code>get()</code> and <code>set()</code>
\r
871 * indicating the modified Julian day number. This is different from
\r
872 * the conventional Julian day number in two regards. First, it
\r
873 * demarcates days at local zone midnight, rather than noon GMT.
\r
874 * Second, it is a local number; that is, it depends on the local time
\r
875 * zone. It can be thought of as a single number that encompasses all
\r
876 * the date-related fields.
\r
879 public static final int JULIAN_DAY = 20;
\r
882 * Field number for <code>get()</code> and <code>set()</code>
\r
883 * indicating the milliseconds in the day. This ranges from 0 to
\r
884 * 23:59:59.999 (regardless of DST). This field behaves
\r
885 * <em>exactly</em> like a composite of all time-related fields, not
\r
886 * including the zone fields. As such, it also reflects
\r
887 * discontinuities of those fields on DST transition days. On a day of
\r
888 * DST onset, it will jump forward. On a day of DST cessation, it will
\r
889 * jump backward. This reflects the fact that is must be combined with
\r
890 * the DST_OFFSET field to obtain a unique local time value.
\r
893 public static final int MILLISECONDS_IN_DAY = 21;
\r
896 * The number of fields defined by this class. Subclasses may define
\r
897 * addition fields starting with this number.
\r
900 protected static final int BASE_FIELD_COUNT = 22;
\r
903 * The maximum number of fields possible. Subclasses must not define
\r
904 * more total fields than this number.
\r
907 protected static final int MAX_FIELD_COUNT = 32;
\r
910 * Value of the <code>DAY_OF_WEEK</code> field indicating
\r
914 public final static int SUNDAY = 1;
\r
917 * Value of the <code>DAY_OF_WEEK</code> field indicating
\r
921 public final static int MONDAY = 2;
\r
924 * Value of the <code>DAY_OF_WEEK</code> field indicating
\r
928 public final static int TUESDAY = 3;
\r
931 * Value of the <code>DAY_OF_WEEK</code> field indicating
\r
935 public final static int WEDNESDAY = 4;
\r
938 * Value of the <code>DAY_OF_WEEK</code> field indicating
\r
942 public final static int THURSDAY = 5;
\r
945 * Value of the <code>DAY_OF_WEEK</code> field indicating
\r
949 public final static int FRIDAY = 6;
\r
952 * Value of the <code>DAY_OF_WEEK</code> field indicating
\r
956 public final static int SATURDAY = 7;
\r
959 * Value of the <code>MONTH</code> field indicating the
\r
960 * first month of the year.
\r
963 public final static int JANUARY = 0;
\r
966 * Value of the <code>MONTH</code> field indicating the
\r
967 * second month of the year.
\r
970 public final static int FEBRUARY = 1;
\r
973 * Value of the <code>MONTH</code> field indicating the
\r
974 * third month of the year.
\r
977 public final static int MARCH = 2;
\r
980 * Value of the <code>MONTH</code> field indicating the
\r
981 * fourth month of the year.
\r
984 public final static int APRIL = 3;
\r
987 * Value of the <code>MONTH</code> field indicating the
\r
988 * fifth month of the year.
\r
991 public final static int MAY = 4;
\r
994 * Value of the <code>MONTH</code> field indicating the
\r
995 * sixth month of the year.
\r
998 public final static int JUNE = 5;
\r
1001 * Value of the <code>MONTH</code> field indicating the
\r
1002 * seventh month of the year.
\r
1005 public final static int JULY = 6;
\r
1008 * Value of the <code>MONTH</code> field indicating the
\r
1009 * eighth month of the year.
\r
1012 public final static int AUGUST = 7;
\r
1015 * Value of the <code>MONTH</code> field indicating the
\r
1016 * ninth month of the year.
\r
1019 public final static int SEPTEMBER = 8;
\r
1022 * Value of the <code>MONTH</code> field indicating the
\r
1023 * tenth month of the year.
\r
1026 public final static int OCTOBER = 9;
\r
1029 * Value of the <code>MONTH</code> field indicating the
\r
1030 * eleventh month of the year.
\r
1033 public final static int NOVEMBER = 10;
\r
1036 * Value of the <code>MONTH</code> field indicating the
\r
1037 * twelfth month of the year.
\r
1040 public final static int DECEMBER = 11;
\r
1043 * Value of the <code>MONTH</code> field indicating the
\r
1044 * thirteenth month of the year. Although <code>GregorianCalendar</code>
\r
1045 * does not use this value, lunar calendars do.
\r
1048 public final static int UNDECIMBER = 12;
\r
1051 * Value of the <code>AM_PM</code> field indicating the
\r
1052 * period of the day from midnight to just before noon.
\r
1055 public final static int AM = 0;
\r
1058 * Value of the <code>AM_PM</code> field indicating the
\r
1059 * period of the day from noon to just before midnight.
\r
1062 public final static int PM = 1;
\r
1065 * Value returned by getDayOfWeekType(int dayOfWeek) to indicate a
\r
1068 * @see #WEEKEND_ONSET
\r
1069 * @see #WEEKEND_CEASE
\r
1070 * @see #getDayOfWeekType
\r
1073 public static final int WEEKDAY = 0;
\r
1076 * Value returned by getDayOfWeekType(int dayOfWeek) to indicate a
\r
1079 * @see #WEEKEND_ONSET
\r
1080 * @see #WEEKEND_CEASE
\r
1081 * @see #getDayOfWeekType
\r
1084 public static final int WEEKEND = 1;
\r
1087 * Value returned by getDayOfWeekType(int dayOfWeek) to indicate a
\r
1088 * day that starts as a weekday and transitions to the weekend.
\r
1089 * Call getWeekendTransition() to get the point of transition.
\r
1092 * @see #WEEKEND_CEASE
\r
1093 * @see #getDayOfWeekType
\r
1096 public static final int WEEKEND_ONSET = 2;
\r
1099 * Value returned by getDayOfWeekType(int dayOfWeek) to indicate a
\r
1100 * day that starts as the weekend and transitions to a weekday.
\r
1101 * Call getWeekendTransition() to get the point of transition.
\r
1104 * @see #WEEKEND_ONSET
\r
1105 * @see #getDayOfWeekType
\r
1108 public static final int WEEKEND_CEASE = 3;
\r
1110 * Gets a calendar using the default time zone and locale.
\r
1111 * @return a Calendar.
\r
1114 public static synchronized Calendar getInstance() {
\r
1115 return new Calendar(java.util.Calendar.getInstance());
\r
1119 * Gets a calendar using the specified time zone and default locale.
\r
1120 * @param zone the time zone to use
\r
1121 * @return a Calendar.
\r
1124 public static synchronized Calendar getInstance(TimeZone zone) {
\r
1125 return new Calendar(java.util.Calendar.getInstance(zone.timeZone));
\r
1129 * Gets a calendar using the default time zone and specified locale.
\r
1130 * @param aLocale the locale for the week data
\r
1131 * @return a Calendar.
\r
1134 public static synchronized Calendar getInstance(Locale aLocale) {
\r
1135 return new Calendar(java.util.Calendar.getInstance(aLocale));
\r
1139 * Gets a calendar using the default time zone and specified locale.
\r
1140 * @param locale the ulocale for the week data
\r
1141 * @return a Calendar.
\r
1144 public static synchronized Calendar getInstance(ULocale locale) {
\r
1145 return new Calendar(java.util.Calendar.getInstance(locale.toLocale()));
\r
1149 * Gets a calendar with the specified time zone and locale.
\r
1150 * @param zone the time zone to use
\r
1151 * @param aLocale the locale for the week data
\r
1152 * @return a Calendar.
\r
1155 public static synchronized Calendar getInstance(TimeZone zone, Locale aLocale) {
\r
1156 return new Calendar(java.util.Calendar.getInstance(zone.timeZone, aLocale));
\r
1160 * Gets a calendar with the specified time zone and locale.
\r
1161 * @param zone the time zone to use
\r
1162 * @param locale the ulocale for the week data
\r
1163 * @return a Calendar.
\r
1166 public static synchronized Calendar getInstance(TimeZone zone, ULocale locale) {
\r
1167 return new Calendar(java.util.Calendar.getInstance(zone.timeZone, locale.toLocale()));
\r
1171 * Gets the list of locales for which Calendars are installed.
\r
1172 * @return the list of locales for which Calendars are installed.
\r
1175 public static Locale[] getAvailableLocales() {
\r
1176 return java.util.Calendar.getAvailableLocales();
\r
1180 * Gets the list of locales for which Calendars are installed.
\r
1181 * @return the list of locales for which Calendars are installed.
\r
1182 * @draft ICU 3.2 (retain)
\r
1184 public static ULocale[] getAvailableULocales() {
\r
1185 if (availableULocales == null) {
\r
1186 Locale[] locales = java.util.Calendar.getAvailableLocales();
\r
1187 ULocale[] ulocales = new ULocale[locales.length];
\r
1188 for (int i = 0; i < locales.length; ++i) {
\r
1189 ulocales[i] = ULocale.forLocale(locales[i]);
\r
1191 availableULocales = ulocales;
\r
1193 return (ULocale[])availableULocales.clone();
\r
1195 private static ULocale[] availableULocales;
\r
1198 * Gets this Calendar's current time.
\r
1199 * @return the current time.
\r
1202 public final Date getTime() {
\r
1203 return calendar.getTime();
\r
1207 * Sets this Calendar's current time with the given Date.
\r
1209 * Note: Calling <code>setTime()</code> with
\r
1210 * <code>Date(Long.MAX_VALUE)</code> or <code>Date(Long.MIN_VALUE)</code>
\r
1211 * may yield incorrect field values from <code>get()</code>.
\r
1212 * @param date the given Date.
\r
1215 public final void setTime(Date date) {
\r
1216 calendar.setTime(date);
\r
1220 * Gets this Calendar's current time as a long.
\r
1221 * @return the current time as UTC milliseconds from the epoch.
\r
1224 public long getTimeInMillis() {
\r
1225 return calendar.getTime().getTime();
\r
1229 * Sets this Calendar's current time from the given long value.
\r
1230 * @param millis the new time in UTC milliseconds from the epoch.
\r
1233 public void setTimeInMillis(long millis) {
\r
1234 calendar.setTime(new Date(millis));
\r
1238 * Gets the value for a given time field.
\r
1239 * @param field the given time field.
\r
1240 * @return the value for the given time field.
\r
1243 public final int get(int field) {
\r
1244 return calendar.get(field);
\r
1248 * Sets the time field with the given value.
\r
1249 * @param field the given time field.
\r
1250 * @param value the value to be set for the given time field.
\r
1253 public final void set(int field, int value) {
\r
1254 calendar.set(field, value);
\r
1258 * Sets the values for the fields year, month, and date.
\r
1259 * Previous values of other fields are retained. If this is not desired,
\r
1260 * call <code>clear</code> first.
\r
1261 * @param year the value used to set the YEAR time field.
\r
1262 * @param month the value used to set the MONTH time field.
\r
1263 * Month value is 0-based. e.g., 0 for January.
\r
1264 * @param date the value used to set the DATE time field.
\r
1267 public final void set(int year, int month, int date) {
\r
1268 calendar.set(year, month, date);
\r
1272 * Sets the values for the fields year, month, date, hour, and minute.
\r
1273 * Previous values of other fields are retained. If this is not desired,
\r
1274 * call <code>clear</code> first.
\r
1275 * @param year the value used to set the YEAR time field.
\r
1276 * @param month the value used to set the MONTH time field.
\r
1277 * Month value is 0-based. e.g., 0 for January.
\r
1278 * @param date the value used to set the DATE time field.
\r
1279 * @param hour the value used to set the HOUR_OF_DAY time field.
\r
1280 * @param minute the value used to set the MINUTE time field.
\r
1283 public final void set(int year, int month, int date, int hour, int minute) {
\r
1284 calendar.set(year, month, date, hour, minute);
\r
1288 * Sets the values for the fields year, month, date, hour, minute, and second.
\r
1289 * Previous values of other fields are retained. If this is not desired,
\r
1290 * call <code>clear</code> first.
\r
1291 * @param year the value used to set the YEAR time field.
\r
1292 * @param month the value used to set the MONTH time field.
\r
1293 * Month value is 0-based. e.g., 0 for January.
\r
1294 * @param date the value used to set the DATE time field.
\r
1295 * @param hour the value used to set the HOUR_OF_DAY time field.
\r
1296 * @param minute the value used to set the MINUTE time field.
\r
1297 * @param second the value used to set the SECOND time field.
\r
1300 public final void set(int year, int month, int date, int hour, int minute, int second) {
\r
1301 calendar.set(year, month, date, hour, minute, second);
\r
1305 * Clears the values of all the time fields.
\r
1308 public final void clear() {
\r
1313 * Clears the value in the given time field.
\r
1314 * @param field the time field to be cleared.
\r
1317 public final void clear(int field) {
\r
1318 calendar.clear(field);
\r
1322 * Determines if the given time field has a value set.
\r
1323 * @return true if the given time field has a value set; false otherwise.
\r
1326 public final boolean isSet(int field) {
\r
1327 return calendar.isSet(field);
\r
1331 * Compares this calendar to the specified object.
\r
1332 * The result is <code>true</code> if and only if the argument is
\r
1333 * not <code>null</code> and is a <code>Calendar</code> object that
\r
1334 * represents the same calendar as this object.
\r
1335 * @param obj the object to compare with.
\r
1336 * @return <code>true</code> if the objects are the same;
\r
1337 * <code>false</code> otherwise.
\r
1340 public boolean equals(Object obj) {
\r
1342 return calendar.equals(((Calendar)obj).calendar);
\r
1344 catch (Exception e) {
\r
1350 * Returns true if the given Calendar object is equivalent to this
\r
1351 * one. An equivalent Calendar will behave exactly as this one
\r
1352 * does, but it may be set to a different time. By contrast, for
\r
1353 * the equals() method to return true, the other Calendar must
\r
1354 * be set to the same time.
\r
1356 * @param other the Calendar to be compared with this Calendar
\r
1359 public boolean isEquivalentTo(Calendar other) {
\r
1360 return this.getClass() == other.getClass() &&
\r
1361 isLenient() == other.isLenient() &&
\r
1362 getFirstDayOfWeek() == other.getFirstDayOfWeek() &&
\r
1363 getMinimalDaysInFirstWeek() == other.getMinimalDaysInFirstWeek() &&
\r
1364 getTimeZone().equals(other.getTimeZone());
\r
1368 * Returns a hash code for this calendar.
\r
1369 * @return a hash code value for this object.
\r
1372 public int hashCode() {
\r
1373 return calendar.hashCode();
\r
1377 * Return the difference in milliseconds between the moment this
\r
1378 * calendar is set to and the moment the given calendar or Date object
\r
1381 private long compare(Object that) {
\r
1383 if (that instanceof Calendar) {
\r
1384 thatMs = ((Calendar)that).getTimeInMillis();
\r
1385 } else if (that instanceof Date) {
\r
1386 thatMs = ((Date)that).getTime();
\r
1388 throw new IllegalArgumentException(that + "is not a Calendar or Date");
\r
1390 return getTimeInMillis() - thatMs;
\r
1394 * Compares the time field records.
\r
1395 * Equivalent to comparing result of conversion to UTC.
\r
1396 * @param when the Calendar to be compared with this Calendar.
\r
1397 * @return true if the current time of this Calendar is before
\r
1398 * the time of Calendar when; false otherwise.
\r
1401 public boolean before(Object when) {
\r
1402 return compare(when) < 0;
\r
1406 * Compares the time field records.
\r
1407 * Equivalent to comparing result of conversion to UTC.
\r
1408 * @param when the Calendar to be compared with this Calendar.
\r
1409 * @return true if the current time of this Calendar is after
\r
1410 * the time of Calendar when; false otherwise.
\r
1413 public boolean after(Object when) {
\r
1414 return compare(when) > 0;
\r
1418 * Return the maximum value that this field could have, given the
\r
1419 * current date. For example, with the Gregorian date February 3, 1997
\r
1420 * and the {@link #DAY_OF_MONTH DAY_OF_MONTH} field, the actual maximum
\r
1421 * is 28; for February 3, 1996 it is 29.
\r
1423 * <p>The actual maximum computation ignores smaller fields and the
\r
1424 * current value of like-sized fields. For example, the actual maximum
\r
1425 * of the DAY_OF_YEAR or MONTH depends only on the year and supra-year
\r
1426 * fields. The actual maximum of the DAY_OF_MONTH depends, in
\r
1427 * addition, on the MONTH field and any other fields at that
\r
1428 * granularity (such as ChineseCalendar.IS_LEAP_MONTH). The
\r
1429 * DAY_OF_WEEK_IN_MONTH field does not depend on the current
\r
1430 * DAY_OF_WEEK; it returns the maximum for any day of week in the
\r
1431 * current month. Likewise for the WEEK_OF_MONTH and WEEK_OF_YEAR
\r
1434 * @param field the field whose maximum is desired
\r
1435 * @return the maximum of the given field for the current date of this calendar
\r
1436 * @see #getMaximum
\r
1437 * @see #getLeastMaximum
\r
1440 public int getActualMaximum(int field) {
\r
1441 return calendar.getActualMaximum(field);
\r
1445 * Return the minimum value that this field could have, given the current date.
\r
1446 * For most fields, this is the same as {@link #getMinimum getMinimum}
\r
1447 * and {@link #getGreatestMinimum getGreatestMinimum}. However, some fields,
\r
1448 * especially those related to week number, are more complicated.
\r
1450 * For example, assume {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek}
\r
1451 * returns 4 and {@link #getFirstDayOfWeek getFirstDayOfWeek} returns SUNDAY.
\r
1452 * If the first day of the month is Sunday, Monday, Tuesday, or Wednesday
\r
1453 * there will be four or more days in the first week, so it will be week number 1,
\r
1454 * and <code>getActualMinimum(WEEK_OF_MONTH)</code> will return 1. However,
\r
1455 * if the first of the month is a Thursday, Friday, or Saturday, there are
\r
1456 * <em>not</em> four days in that week, so it is week number 0, and
\r
1457 * <code>getActualMinimum(WEEK_OF_MONTH)</code> will return 0.
\r
1459 * @param field the field whose actual minimum value is desired.
\r
1460 * @return the minimum of the given field for the current date of this calendar
\r
1462 * @see #getMinimum
\r
1463 * @see #getGreatestMinimum
\r
1466 public int getActualMinimum(int field) {
\r
1467 return calendar.getActualMinimum(field);
\r
1472 * Rolls (up/down) a single unit of time on the given field. If the
\r
1473 * field is rolled past its maximum allowable value, it will "wrap" back
\r
1474 * to its minimum and continue rolling. For
\r
1475 * example, to roll the current date up by one day, you can call:
\r
1477 * <code>roll({@link #DATE}, true)</code>
\r
1479 * When rolling on the {@link #YEAR} field, it will roll the year
\r
1480 * value in the range between 1 and the value returned by calling
\r
1481 * {@link #getMaximum getMaximum}({@link #YEAR}).
\r
1483 * When rolling on certain fields, the values of other fields may conflict and
\r
1484 * need to be changed. For example, when rolling the <code>MONTH</code> field
\r
1485 * for the Gregorian date 1/31/96 upward, the <code>DAY_OF_MONTH</code> field
\r
1486 * must be adjusted so that the result is 2/29/96 rather than the invalid
\r
1489 * <b>Note:</b> Calling <tt>roll(field, true)</tt> N times is <em>not</em>
\r
1490 * necessarily equivalent to calling <tt>roll(field, N)</tt>. For example,
\r
1491 * imagine that you start with the date Gregorian date January 31, 1995. If you call
\r
1492 * <tt>roll(Calendar.MONTH, 2)</tt>, the result will be March 31, 1995.
\r
1493 * But if you call <tt>roll(Calendar.MONTH, true)</tt>, the result will be
\r
1494 * February 28, 1995. Calling it one more time will give March 28, 1995, which
\r
1495 * is usually not the desired result.
\r
1497 * <b>Note:</b> You should always use <tt>roll</tt> and <tt>add</tt> rather
\r
1498 * than attempting to perform arithmetic operations directly on the fields
\r
1499 * of a <tt>Calendar</tt>. It is quite possible for <tt>Calendar</tt> subclasses
\r
1500 * to have fields with non-linear behavior, for example missing months
\r
1501 * or days during non-leap years. The subclasses' <tt>add</tt> and <tt>roll</tt>
\r
1502 * methods will take this into account, while simple arithmetic manipulations
\r
1503 * may give invalid results.
\r
1505 * @param field the calendar field to roll.
\r
1507 * @param up indicates if the value of the specified time field is to be
\r
1508 * rolled up or rolled down. Use <code>true</code> if rolling up,
\r
1509 * <code>false</code> otherwise.
\r
1511 * @exception IllegalArgumentException if the field is invalid or refers
\r
1512 * to a field that cannot be handled by this method.
\r
1513 * @see #roll(int, int)
\r
1517 public final void roll(int field, boolean up) {
\r
1518 calendar.roll(field, up);
\r
1522 * Rolls (up/down) a specified amount time on the given field. For
\r
1523 * example, to roll the current date up by three days, you can call
\r
1524 * <code>roll(Calendar.DATE, 3)</code>. If the
\r
1525 * field is rolled past its maximum allowable value, it will "wrap" back
\r
1526 * to its minimum and continue rolling.
\r
1527 * For example, calling <code>roll(Calendar.DATE, 10)</code>
\r
1528 * on a Gregorian calendar set to 4/25/96 will result in the date 4/5/96.
\r
1530 * When rolling on certain fields, the values of other fields may conflict and
\r
1531 * need to be changed. For example, when rolling the {@link #MONTH MONTH} field
\r
1532 * for the Gregorian date 1/31/96 by +1, the {@link #DAY_OF_MONTH DAY_OF_MONTH} field
\r
1533 * must be adjusted so that the result is 2/29/96 rather than the invalid
\r
1536 * The <code>com.ibm.icu.util.Calendar</code> implementation of this method is able to roll
\r
1537 * all fields except for {@link #ERA ERA}, {@link #DST_OFFSET DST_OFFSET},
\r
1538 * and {@link #ZONE_OFFSET ZONE_OFFSET}. Subclasses may, of course, add support for
\r
1539 * additional fields in their overrides of <code>roll</code>.
\r
1541 * <b>Note:</b> You should always use <tt>roll</tt> and <tt>add</tt> rather
\r
1542 * than attempting to perform arithmetic operations directly on the fields
\r
1543 * of a <tt>Calendar</tt>. It is quite possible for <tt>Calendar</tt> subclasses
\r
1544 * to have fields with non-linear behavior, for example missing months
\r
1545 * or days during non-leap years. The subclasses' <tt>add</tt> and <tt>roll</tt>
\r
1546 * methods will take this into account, while simple arithmetic manipulations
\r
1547 * may give invalid results.
\r
1549 * <b>Subclassing:</b><br>
\r
1550 * This implementation of <code>roll</code> assumes that the behavior of the
\r
1551 * field is continuous between its minimum and maximum, which are found by
\r
1552 * calling {@link #getActualMinimum getActualMinimum} and {@link #getActualMaximum getActualMaximum}.
\r
1553 * For most such fields, simple addition, subtraction, and modulus operations
\r
1554 * are sufficient to perform the roll. For week-related fields,
\r
1555 * the results of {@link #getFirstDayOfWeek getFirstDayOfWeek} and
\r
1556 * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek} are also necessary.
\r
1557 * Subclasses can override these two methods if their values differ from the defaults.
\r
1559 * Subclasses that have fields for which the assumption of continuity breaks
\r
1560 * down must overide <code>roll</code> to handle those fields specially.
\r
1561 * For example, in the Hebrew calendar the month "Adar I"
\r
1562 * only occurs in leap years; in other years the calendar jumps from
\r
1563 * Shevat (month #4) to Adar (month #6). The
\r
1564 * {@link HebrewCalendar#roll HebrewCalendar.roll} method takes this into account,
\r
1565 * so that rolling the month of Shevat by one gives the proper result (Adar) in a
\r
1568 * @param field the calendar field to roll.
\r
1569 * @param amount the amount by which the field should be rolled.
\r
1571 * @exception IllegalArgumentException if the field is invalid or refers
\r
1572 * to a field that cannot be handled by this method.
\r
1573 * @see #roll(int, boolean)
\r
1577 public void roll(int field, int amount) {
\r
1578 calendar.roll(field, amount);
\r
1582 * Add a signed amount to a specified field, using this calendar's rules.
\r
1583 * For example, to add three days to the current date, you can call
\r
1584 * <code>add(Calendar.DATE, 3)</code>.
\r
1586 * When adding to certain fields, the values of other fields may conflict and
\r
1587 * need to be changed. For example, when adding one to the {@link #MONTH MONTH} field
\r
1588 * for the Gregorian date 1/31/96, the {@link #DAY_OF_MONTH DAY_OF_MONTH} field
\r
1589 * must be adjusted so that the result is 2/29/96 rather than the invalid
\r
1592 * The <code>com.ibm.icu.util.Calendar</code> implementation of this method is able to add to
\r
1593 * all fields except for {@link #ERA ERA}, {@link #DST_OFFSET DST_OFFSET},
\r
1594 * and {@link #ZONE_OFFSET ZONE_OFFSET}. Subclasses may, of course, add support for
\r
1595 * additional fields in their overrides of <code>add</code>.
\r
1597 * <b>Note:</b> You should always use <tt>roll</tt> and <tt>add</tt> rather
\r
1598 * than attempting to perform arithmetic operations directly on the fields
\r
1599 * of a <tt>Calendar</tt>. It is quite possible for <tt>Calendar</tt> subclasses
\r
1600 * to have fields with non-linear behavior, for example missing months
\r
1601 * or days during non-leap years. The subclasses' <tt>add</tt> and <tt>roll</tt>
\r
1602 * methods will take this into account, while simple arithmetic manipulations
\r
1603 * may give invalid results.
\r
1605 * <b>Subclassing:</b><br>
\r
1606 * This implementation of <code>add</code> assumes that the behavior of the
\r
1607 * field is continuous between its minimum and maximum, which are found by
\r
1608 * calling {@link #getActualMinimum getActualMinimum} and
\r
1609 * {@link #getActualMaximum getActualMaximum}.
\r
1610 * For such fields, simple arithmetic operations are sufficient to
\r
1611 * perform the add.
\r
1613 * Subclasses that have fields for which this assumption of continuity breaks
\r
1614 * down must overide <code>add</code> to handle those fields specially.
\r
1615 * For example, in the Hebrew calendar the month "Adar I"
\r
1616 * only occurs in leap years; in other years the calendar jumps from
\r
1617 * Shevat (month #4) to Adar (month #6). The
\r
1618 * {@link HebrewCalendar#add HebrewCalendar.add} method takes this into account,
\r
1619 * so that adding one month
\r
1620 * to a date in Shevat gives the proper result (Adar) in a non-leap year.
\r
1622 * @param field the time field.
\r
1623 * @param amount the amount to add to the field.
\r
1625 * @exception IllegalArgumentException if the field is invalid or refers
\r
1626 * to a field that cannot be handled by this method.
\r
1627 * @see #roll(int, int)
\r
1630 public void add(int field, int amount) {
\r
1631 calendar.add(field, amount);
\r
1635 * Return the name of this calendar in the language of the given locale.
\r
1638 public String getDisplayName(Locale loc) {
\r
1639 return "Calendar";
\r
1643 * Return the name of this calendar in the language of the given locale.
\r
1646 public String getDisplayName(ULocale loc) {
\r
1647 return "Calendar";
\r
1651 * Compares the times (in millis) represented by two
\r
1652 * <code>Calendar</code> objects.
\r
1654 * @param that the <code>Calendar</code> to compare to this.
\r
1655 * @return <code>0</code> if the time represented by
\r
1656 * this <code>Calendar</code> is equal to the time represented
\r
1657 * by that <code>Calendar</code>, a value less than
\r
1658 * <code>0</code> if the time represented by this is before
\r
1659 * the time represented by that, and a value greater than
\r
1660 * <code>0</code> if the time represented by this
\r
1661 * is after the time represented by that.
\r
1662 * @throws NullPointerException if that
\r
1663 * <code>Calendar</code> is null.
\r
1664 * @throws IllegalArgumentException if the time of that
\r
1665 * <code>Calendar</code> can't be obtained because of invalid
\r
1666 * calendar values.
\r
1669 public int compareTo(Calendar that) {
\r
1670 long v = getTimeInMillis() - that.getTimeInMillis();
\r
1671 return v < 0 ? -1 : (v > 0 ? 1 : 0);
\r
1675 * Implement comparable API as a convenience override of
\r
1676 * {@link #compareTo(Calendar)}.
\r
1679 public int compareTo(Object that) {
\r
1680 return compareTo((Calendar)that);
\r
1683 //-------------------------------------------------------------------------
\r
1684 // Interface for creating custon DateFormats for different types of Calendars
\r
1685 //-------------------------------------------------------------------------
\r
1688 * Return a <code>DateFormat</code> appropriate to this calendar.
\r
1691 public DateFormat getDateTimeFormat(int dateStyle, int timeStyle, Locale loc) {
\r
1692 return formatHelper(this, loc, dateStyle, timeStyle);
\r
1696 * Return a <code>DateFormat</code> appropriate to this calendar.
\r
1699 public DateFormat getDateTimeFormat(int dateStyle, int timeStyle, ULocale loc) {
\r
1700 return formatHelper(this, loc.toLocale(), dateStyle, timeStyle);
\r
1704 * Utility for formatting.
\r
1706 private static DateFormat formatHelper(Calendar cal, Locale loc, int dateStyle, int timeStyle) {
\r
1707 // Assume there is only one kind of calendar. In Java 6 there will also be Japanese
\r
1708 // calendars, but we'll worry about that when it happens.
\r
1709 DateFormat df = DateFormat.getDateTimeInstance(dateStyle, timeStyle, loc);
\r
1710 df.setCalendar(cal);
\r
1714 //-------------------------------------------------------------------------
\r
1716 //-------------------------------------------------------------------------
\r
1720 * Return the difference between the given time and the time this
\r
1721 * calendar object is set to. If this calendar is set
\r
1722 * <em>before</em> the given time, the returned value will be
\r
1723 * positive. If this calendar is set <em>after</em> the given
\r
1724 * time, the returned value will be negative. The
\r
1725 * <code>field</code> parameter specifies the units of the return
\r
1726 * value. For example, if <code>fieldDifference(when,
\r
1727 * Calendar.MONTH)</code> returns 3, then this calendar is set to
\r
1728 * 3 months before <code>when</code>, and possibly some additional
\r
1729 * time less than one month.
\r
1731 * <p>As a side effect of this call, this calendar is advanced
\r
1732 * toward <code>when</code> by the given amount. That is, calling
\r
1733 * this method has the side effect of calling <code>add(field,
\r
1734 * n)</code>, where <code>n</code> is the return value.
\r
1736 * <p>Usage: To use this method, call it first with the largest
\r
1737 * field of interest, then with progressively smaller fields. For
\r
1741 * int y = cal.fieldDifference(when, Calendar.YEAR);
\r
1742 * int m = cal.fieldDifference(when, Calendar.MONTH);
\r
1743 * int d = cal.fieldDifference(when, Calendar.DATE);</pre>
\r
1745 * computes the difference between <code>cal</code> and
\r
1746 * <code>when</code> in years, months, and days.
\r
1748 * <p>Note: <code>fieldDifference()</code> is
\r
1749 * <em>asymmetrical</em>. That is, in the following code:
\r
1752 * cal.setTime(date1);
\r
1753 * int m1 = cal.fieldDifference(date2, Calendar.MONTH);
\r
1754 * int d1 = cal.fieldDifference(date2, Calendar.DATE);
\r
1755 * cal.setTime(date2);
\r
1756 * int m2 = cal.fieldDifference(date1, Calendar.MONTH);
\r
1757 * int d2 = cal.fieldDifference(date1, Calendar.DATE);</pre>
\r
1759 * one might expect that <code>m1 == -m2 && d1 == -d2</code>.
\r
1760 * However, this is not generally the case, because of
\r
1761 * irregularities in the underlying calendar system (e.g., the
\r
1762 * Gregorian calendar has a varying number of days per month).
\r
1764 * @param when the date to compare this calendar's time to
\r
1765 * @param field the field in which to compute the result
\r
1766 * @return the difference, either positive or negative, between
\r
1767 * this calendar's time and <code>when</code>, in terms of
\r
1768 * <code>field</code>.
\r
1771 public int fieldDifference(Date when, int field) {
\r
1773 long startMs = getTimeInMillis();
\r
1774 long targetMs = when.getTime();
\r
1775 // Always add from the start millis. This accomodates
\r
1776 // operations like adding years from February 29, 2000 up to
\r
1777 // February 29, 2004. If 1, 1, 1, 1 is added to the year
\r
1778 // field, the DOM gets pinned to 28 and stays there, giving an
\r
1779 // incorrect DOM difference of 1. We have to add 1, reset, 2,
\r
1780 // reset, 3, reset, 4.
\r
1781 if (startMs < targetMs) {
\r
1783 // Find a value that is too large
\r
1785 setTimeInMillis(startMs);
\r
1787 long ms = getTimeInMillis();
\r
1788 if (ms == targetMs) {
\r
1790 } else if (ms > targetMs) {
\r
1795 // Field difference too large to fit into int
\r
1796 throw new RuntimeException();
\r
1800 // Do a binary search
\r
1801 while ((max - min) > 1) {
\r
1802 int t = (min + max) / 2;
\r
1803 setTimeInMillis(startMs);
\r
1805 long ms = getTimeInMillis();
\r
1806 if (ms == targetMs) {
\r
1808 } else if (ms > targetMs) {
\r
1814 } else if (startMs > targetMs) {
\r
1816 // This works, and makes the code smaller, but costs
\r
1817 // an extra object creation and an extra couple cycles
\r
1818 // of calendar computation.
\r
1819 setTimeInMillis(targetMs);
\r
1820 min = -fieldDifference(new Date(startMs), field);
\r
1823 // Find a value that is too small
\r
1825 setTimeInMillis(startMs);
\r
1827 long ms = getTimeInMillis();
\r
1828 if (ms == targetMs) {
\r
1830 } else if (ms < targetMs) {
\r
1835 // Field difference too large to fit into int
\r
1836 throw new RuntimeException();
\r
1840 // Do a binary search
\r
1841 while ((min - max) > 1) {
\r
1842 int t = (min + max) / 2;
\r
1843 setTimeInMillis(startMs);
\r
1845 long ms = getTimeInMillis();
\r
1846 if (ms == targetMs) {
\r
1848 } else if (ms < targetMs) {
\r
1855 // Set calendar to end point
\r
1856 setTimeInMillis(startMs);
\r
1862 * Sets the time zone with the given time zone value.
\r
1863 * @param value the given time zone.
\r
1866 public void setTimeZone(TimeZone value) {
\r
1867 calendar.setTimeZone(value.timeZone);
\r
1871 * Gets the time zone.
\r
1872 * @return the time zone object associated with this calendar.
\r
1875 public TimeZone getTimeZone() {
\r
1876 return new TimeZone(calendar.getTimeZone());
\r
1880 * Specify whether or not date/time interpretation is to be lenient. With
\r
1881 * lenient interpretation, a date such as "February 942, 1996" will be
\r
1882 * treated as being equivalent to the 941st day after February 1, 1996.
\r
1883 * With strict interpretation, such dates will cause an exception to be
\r
1886 * @see DateFormat#setLenient
\r
1889 public void setLenient(boolean lenient) {
\r
1890 calendar.setLenient(lenient);
\r
1894 * Tell whether date/time interpretation is to be lenient.
\r
1897 public boolean isLenient() {
\r
1898 return calendar.isLenient();
\r
1902 * Sets what the first day of the week is; e.g., Sunday in US,
\r
1903 * Monday in France.
\r
1904 * @param value the given first day of the week.
\r
1907 public void setFirstDayOfWeek(int value) {
\r
1908 calendar.setFirstDayOfWeek(value);
\r
1912 * Gets what the first day of the week is; e.g., Sunday in US,
\r
1913 * Monday in France.
\r
1914 * @return the first day of the week.
\r
1917 public int getFirstDayOfWeek() {
\r
1918 return calendar.getFirstDayOfWeek();
\r
1922 * Sets what the minimal days required in the first week of the year are.
\r
1923 * For example, if the first week is defined as one that contains the first
\r
1924 * day of the first month of a year, call the method with value 1. If it
\r
1925 * must be a full week, use value 7.
\r
1926 * @param value the given minimal days required in the first week
\r
1930 public void setMinimalDaysInFirstWeek(int value) {
\r
1931 calendar.setMinimalDaysInFirstWeek(value);
\r
1935 * Gets what the minimal days required in the first week of the year are;
\r
1936 * e.g., if the first week is defined as one that contains the first day
\r
1937 * of the first month of a year, getMinimalDaysInFirstWeek returns 1. If
\r
1938 * the minimal days required must be a full week, getMinimalDaysInFirstWeek
\r
1940 * @return the minimal days required in the first week of the year.
\r
1943 public int getMinimalDaysInFirstWeek() {
\r
1944 return calendar.getMinimalDaysInFirstWeek();
\r
1948 * Gets the minimum value for the given time field.
\r
1949 * e.g., for Gregorian DAY_OF_MONTH, 1.
\r
1950 * @param field the given time field.
\r
1951 * @return the minimum value for the given time field.
\r
1954 public final int getMinimum(int field) {
\r
1955 return calendar.getMinimum(field);
\r
1959 * Gets the maximum value for the given time field.
\r
1960 * e.g. for Gregorian DAY_OF_MONTH, 31.
\r
1961 * @param field the given time field.
\r
1962 * @return the maximum value for the given time field.
\r
1965 public final int getMaximum(int field) {
\r
1966 return calendar.getMaximum(field);
\r
1970 * Gets the highest minimum value for the given field if varies.
\r
1971 * Otherwise same as getMinimum(). For Gregorian, no difference.
\r
1972 * @param field the given time field.
\r
1973 * @return the highest minimum value for the given time field.
\r
1976 public final int getGreatestMinimum(int field) {
\r
1977 return calendar.getGreatestMinimum(field);
\r
1981 * Gets the lowest maximum value for the given field if varies.
\r
1982 * Otherwise same as getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28.
\r
1983 * @param field the given time field.
\r
1984 * @return the lowest maximum value for the given time field.
\r
1987 public final int getLeastMaximum(int field) {
\r
1988 return calendar.getLeastMaximum(field);
\r
1991 //-------------------------------------------------------------------------
\r
1992 // Weekend support -- determining which days of the week are the weekend
\r
1993 // in a given locale
\r
1994 //-------------------------------------------------------------------------
\r
1997 * Return whether the given day of the week is a weekday, a
\r
1998 * weekend day, or a day that transitions from one to the other,
\r
1999 * in this calendar system. If a transition occurs at midnight,
\r
2000 * then the days before and after the transition will have the
\r
2001 * type WEEKDAY or WEEKEND. If a transition occurs at a time
\r
2002 * other than midnight, then the day of the transition will have
\r
2003 * the type WEEKEND_ONSET or WEEKEND_CEASE. In this case, the
\r
2004 * method getWeekendTransition() will return the point of
\r
2006 * @param dayOfWeek either SUNDAY, MONDAY, TUESDAY, WEDNESDAY,
\r
2007 * THURSDAY, FRIDAY, or SATURDAY
\r
2008 * @return either WEEKDAY, WEEKEND, WEEKEND_ONSET, or
\r
2010 * @exception IllegalArgumentException if dayOfWeek is not
\r
2011 * between SUNDAY and SATURDAY, inclusive
\r
2014 * @see #WEEKEND_ONSET
\r
2015 * @see #WEEKEND_CEASE
\r
2016 * @see #getWeekendTransition
\r
2017 * @see #isWeekend(Date)
\r
2018 * @see #isWeekend()
\r
2021 public int getDayOfWeekType(int dayOfWeek) {
\r
2022 // weekend always full saturday and sunday
\r
2023 if (dayOfWeek < 1 || dayOfWeek > 7) {
\r
2024 throw new IllegalArgumentException("illegal day of week: " + dayOfWeek);
\r
2026 return dayOfWeek >= SATURDAY ? WEEKEND : WEEKDAY;
\r
2030 * Return the time during the day at which the weekend begins or end in
\r
2031 * this calendar system. If getDayOfWeekType(dayOfWeek) ==
\r
2032 * WEEKEND_ONSET return the time at which the weekend begins. If
\r
2033 * getDayOfWeekType(dayOfWeek) == WEEKEND_CEASE return the time at
\r
2034 * which the weekend ends. If getDayOfWeekType(dayOfWeek) has some
\r
2035 * other value, then throw an exception.
\r
2036 * @param dayOfWeek either SUNDAY, MONDAY, TUESDAY, WEDNESDAY,
\r
2037 * THURSDAY, FRIDAY, or SATURDAY
\r
2038 * @return the milliseconds after midnight at which the
\r
2039 * weekend begins or ends
\r
2040 * @exception IllegalArgumentException if dayOfWeek is not
\r
2041 * WEEKEND_ONSET or WEEKEND_CEASE
\r
2042 * @see #getDayOfWeekType
\r
2043 * @see #isWeekend(Date)
\r
2044 * @see #isWeekend()
\r
2047 public int getWeekendTransition(int dayOfWeek) {
\r
2048 throw new IllegalArgumentException("Not weekend transition day");
\r
2052 * Return true if the given date and time is in the weekend in
\r
2053 * this calendar system. Equivalent to calling setTime() followed
\r
2054 * by isWeekend(). Note: This method changes the time this
\r
2055 * calendar is set to.
\r
2056 * @param date the date and time
\r
2057 * @return true if the given date and time is part of the
\r
2059 * @see #getDayOfWeekType
\r
2060 * @see #getWeekendTransition
\r
2061 * @see #isWeekend()
\r
2064 public boolean isWeekend(Date date) {
\r
2065 calendar.setTime(date);
\r
2066 return isWeekend();
\r
2070 * Return true if this Calendar's current date and time is in the
\r
2071 * weekend in this calendar system.
\r
2072 * @return true if the given date and time is part of the
\r
2074 * @see #getDayOfWeekType
\r
2075 * @see #getWeekendTransition
\r
2076 * @see #isWeekend(Date)
\r
2079 public boolean isWeekend() {
\r
2080 return calendar.get(Calendar.DAY_OF_WEEK) >= SATURDAY;
\r
2083 //-------------------------------------------------------------------------
\r
2084 // End of weekend support
\r
2085 //-------------------------------------------------------------------------
\r
2088 * Overrides Cloneable
\r
2091 public Object clone() {
\r
2092 return new Calendar((java.util.Calendar)calendar.clone());
\r
2096 * Return a string representation of this calendar. This method
\r
2097 * is intended to be used only for debugging purposes, and the
\r
2098 * format of the returned string may vary between implementations.
\r
2099 * The returned string may be empty but may not be <code>null</code>.
\r
2101 * @return a string representation of this calendar.
\r
2104 public String toString() {
\r
2105 return calendar.toString();
\r
2109 * Return the current Calendar type.
\r
2110 * Note, in 3.0 this function will return 'gregorian' in Calendar to emulate legacy behavior
\r
2111 * @return type of calendar (gregorian, etc)
\r
2112 * @internal ICU 3.0
\r
2114 public String getType() {
\r
2115 return "gregorian";
\r
projects / Dictionary.git / blob