1/* 2* Copyright (C) 1996-2012, International Business Machines 3* Corporation and others. All Rights Reserved. 4*/ 5 6package com.ibm.icu.util; 7 8import java.io.Serializable; 9import java.util.Date; 10import java.util.GregorianCalendar; 11import java.util.Locale; 12 13import com.ibm.icu.text.DateFormat; 14import com.ibm.icu.util.ULocale.Category; 15 16/** 17 * {@icuenhanced java.util.Calendar}.{@icu _usage_} 18 * 19 * <p><code>Calendar</code> is an abstract base class for converting between 20 * a <code>Date</code> object and a set of integer fields such as 21 * <code>YEAR</code>, <code>MONTH</code>, <code>DAY</code>, <code>HOUR</code>, 22 * and so on. (A <code>Date</code> object represents a specific instant in 23 * time with millisecond precision. See 24 * {@link Date} 25 * for information about the <code>Date</code> class.) 26 * 27 * <p>Subclasses of <code>Calendar</code> interpret a <code>Date</code> 28 * according to the rules of a specific calendar system. ICU4J contains 29 * several subclasses implementing different international calendar systems. 30 * 31 * <p> 32 * Like other locale-sensitive classes, <code>Calendar</code> provides a 33 * class method, <code>getInstance</code>, for getting a generally useful 34 * object of this type. <code>Calendar</code>'s <code>getInstance</code> method 35 * returns a calendar of a type appropriate to the locale, whose 36 * time fields have been initialized with the current date and time: 37 * <blockquote> 38 * <pre>Calendar rightNow = Calendar.getInstance()</pre> 39 * </blockquote> 40 * 41 * <p>When a <code>ULocale</code> is used by <code>getInstance</code>, its 42 * '<code>calendar</code>' tag and value are retrieved if present. If a recognized 43 * value is supplied, a calendar is provided and configured as appropriate. 44 * Currently recognized tags are "buddhist", "chinese", "coptic", "ethiopic", 45 * "gregorian", "hebrew", "islamic", "islamic-civil", "japanese", and "roc". For 46 * example: <blockquote> 47 * <pre>Calendar cal = Calendar.getInstance(new ULocale("en_US@calendar=japanese"));</pre> 48 * </blockquote> will return an instance of JapaneseCalendar (using en_US conventions for 49 * minimum days in first week, start day of week, et cetera). 50 * 51 * <p>A <code>Calendar</code> object can produce all the time field values 52 * needed to implement the date-time formatting for a particular language and 53 * calendar style (for example, Japanese-Gregorian, Japanese-Traditional). 54 * <code>Calendar</code> defines the range of values returned by certain fields, 55 * as well as their meaning. For example, the first month of the year has value 56 * <code>MONTH</code> == <code>JANUARY</code> for all calendars. Other values 57 * are defined by the concrete subclass, such as <code>ERA</code> and 58 * <code>YEAR</code>. See individual field documentation and subclass 59 * documentation for details. 60 * 61 * <p>When a <code>Calendar</code> is <em>lenient</em>, it accepts a wider range 62 * of field values than it produces. For example, a lenient 63 * <code>GregorianCalendar</code> interprets <code>MONTH</code> == 64 * <code>JANUARY</code>, <code>DAY_OF_MONTH</code> == 32 as February 1. A 65 * non-lenient <code>GregorianCalendar</code> throws an exception when given 66 * out-of-range field settings. When calendars recompute field values for 67 * return by <code>get()</code>, they normalize them. For example, a 68 * <code>GregorianCalendar</code> always produces <code>DAY_OF_MONTH</code> 69 * values between 1 and the length of the month. 70 * 71 * <p><code>Calendar</code> defines a locale-specific seven day week using two 72 * parameters: the first day of the week and the minimal days in first week 73 * (from 1 to 7). These numbers are taken from the locale resource data when a 74 * <code>Calendar</code> is constructed. They may also be specified explicitly 75 * through the API. 76 * 77 * <p>When setting or getting the <code>WEEK_OF_MONTH</code> or 78 * <code>WEEK_OF_YEAR</code> fields, <code>Calendar</code> must determine the 79 * first week of the month or year as a reference point. The first week of a 80 * month or year is defined as the earliest seven day period beginning on 81 * <code>getFirstDayOfWeek()</code> and containing at least 82 * <code>getMinimalDaysInFirstWeek()</code> days of that month or year. Weeks 83 * numbered ..., -1, 0 precede the first week; weeks numbered 2, 3,... follow 84 * it. Note that the normalized numbering returned by <code>get()</code> may be 85 * different. For example, a specific <code>Calendar</code> subclass may 86 * designate the week before week 1 of a year as week <em>n</em> of the previous 87 * year. 88 * 89 * <p> When computing a <code>Date</code> from time fields, two special 90 * circumstances may arise: there may be insufficient information to compute the 91 * <code>Date</code> (such as only year and month but no day in the month), or 92 * there may be inconsistent information (such as "Tuesday, July 15, 1996" -- 93 * July 15, 1996 is actually a Monday). 94 * 95 * <p><strong>Insufficient information.</strong> The calendar will use default 96 * information to specify the missing fields. This may vary by calendar; for 97 * the Gregorian calendar, the default for a field is the same as that of the 98 * start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. 99 * 100 * <p><strong>Inconsistent information.</strong> If fields conflict, the calendar 101 * will give preference to fields set more recently. For example, when 102 * determining the day, the calendar will look for one of the following 103 * combinations of fields. The most recent combination, as determined by the 104 * most recently set single field, will be used. 105 * 106 * <blockquote> 107 * <pre> 108 * MONTH + DAY_OF_MONTH 109 * MONTH + WEEK_OF_MONTH + DAY_OF_WEEK 110 * MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK 111 * DAY_OF_YEAR 112 * DAY_OF_WEEK + WEEK_OF_YEAR</pre> 113 * </blockquote> 114 * 115 * For the time of day: 116 * 117 * <blockquote> 118 * <pre> 119 * HOUR_OF_DAY 120 * AM_PM + HOUR</pre> 121 * </blockquote> 122 * 123 * <p><strong>Note:</strong> for some non-Gregorian calendars, different 124 * fields may be necessary for complete disambiguation. For example, a full 125 * specification of the historial Arabic astronomical calendar requires year, 126 * month, day-of-month <em>and</em> day-of-week in some cases. 127 * 128 * <p><strong>Note:</strong> There are certain possible ambiguities in 129 * interpretation of certain singular times, which are resolved in the 130 * following ways: 131 * <ol> 132 * <li> 24:00:00 "belongs" to the following day. That is, 133 * 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970 134 * 135 * <li> Although historically not precise, midnight also belongs to "am", 136 * and noon belongs to "pm", so on the same day, 137 * 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm 138 * </ol> 139 * 140 * <p>The date or time format strings are not part of the definition of a 141 * calendar, as those must be modifiable or overridable by the user at 142 * runtime. Use {@link DateFormat} 143 * to format dates. 144 * 145 * <p><strong>Field manipulation methods</strong></p> 146 * 147 * <p><code>Calendar</code> fields can be changed using three methods: 148 * <code>set()</code>, <code>add()</code>, and <code>roll()</code>.</p> 149 * 150 * <p><strong><code>set(f, value)</code></strong> changes field 151 * <code>f</code> to <code>value</code>. In addition, it sets an 152 * internal member variable to indicate that field <code>f</code> has 153 * been changed. Although field <code>f</code> is changed immediately, 154 * the calendar's milliseconds is not recomputed until the next call to 155 * <code>get()</code>, <code>getTime()</code>, or 156 * <code>getTimeInMillis()</code> is made. Thus, multiple calls to 157 * <code>set()</code> do not trigger multiple, unnecessary 158 * computations. As a result of changing a field using 159 * <code>set()</code>, other fields may also change, depending on the 160 * field, the field value, and the calendar system. In addition, 161 * <code>get(f)</code> will not necessarily return <code>value</code> 162 * after the fields have been recomputed. The specifics are determined by 163 * the concrete calendar class.</p> 164 * 165 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code> 166 * originally set to August 31, 1999. Calling <code>set(Calendar.MONTH, 167 * Calendar.SEPTEMBER)</code> sets the calendar to September 31, 168 * 1999. This is a temporary internal representation that resolves to 169 * October 1, 1999 if <code>getTime()</code>is then called. However, a 170 * call to <code>set(Calendar.DAY_OF_MONTH, 30)</code> before the call to 171 * <code>getTime()</code> sets the calendar to September 30, 1999, since 172 * no recomputation occurs after <code>set()</code> itself.</p> 173 * 174 * <p><strong><code>add(f, delta)</code></strong> adds <code>delta</code> 175 * to field <code>f</code>. This is equivalent to calling <code>set(f, 176 * get(f) + delta)</code> with two adjustments:</p> 177 * 178 * <blockquote> 179 * <p><strong>Add rule 1</strong>. The value of field <code>f</code> 180 * after the call minus the value of field <code>f</code> before the 181 * call is <code>delta</code>, modulo any overflow that has occurred in 182 * field <code>f</code>. Overflow occurs when a field value exceeds its 183 * range and, as a result, the next larger field is incremented or 184 * decremented and the field value is adjusted back into its range.</p> 185 * 186 * <p><strong>Add rule 2</strong>. If a smaller field is expected to be 187 * invariant, but it is impossible for it to be equal to its 188 * prior value because of changes in its minimum or maximum after field 189 * <code>f</code> is changed, then its value is adjusted to be as close 190 * as possible to its expected value. A smaller field represents a 191 * smaller unit of time. <code>HOUR</code> is a smaller field than 192 * <code>DAY_OF_MONTH</code>. No adjustment is made to smaller fields 193 * that are not expected to be invariant. The calendar system 194 * determines what fields are expected to be invariant.</p> 195 * </blockquote> 196 * 197 * <p>In addition, unlike <code>set()</code>, <code>add()</code> forces 198 * an immediate recomputation of the calendar's milliseconds and all 199 * fields.</p> 200 * 201 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code> 202 * originally set to August 31, 1999. Calling <code>add(Calendar.MONTH, 203 * 13)</code> sets the calendar to September 30, 2000. <strong>Add rule 204 * 1</strong> sets the <code>MONTH</code> field to September, since 205 * adding 13 months to August gives September of the next year. Since 206 * <code>DAY_OF_MONTH</code> cannot be 31 in September in a 207 * <code>GregorianCalendar</code>, <strong>add rule 2</strong> sets the 208 * <code>DAY_OF_MONTH</code> to 30, the closest possible value. Although 209 * it is a smaller field, <code>DAY_OF_WEEK</code> is not adjusted by 210 * rule 2, since it is expected to change when the month changes in a 211 * <code>GregorianCalendar</code>.</p> 212 * 213 * <p><strong><code>roll(f, delta)</code></strong> adds 214 * <code>delta</code> to field <code>f</code> without changing larger 215 * fields. This is equivalent to calling <code>add(f, delta)</code> with 216 * the following adjustment:</p> 217 * 218 * <blockquote> 219 * <p><strong>Roll rule</strong>. Larger fields are unchanged after the 220 * call. A larger field represents a larger unit of 221 * time. <code>DAY_OF_MONTH</code> is a larger field than 222 * <code>HOUR</code>.</p> 223 * </blockquote> 224 * 225 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code> 226 * originally set to August 31, 1999. Calling <code>roll(Calendar.MONTH, 227 * 8)</code> sets the calendar to April 30, <strong>1999</strong>. Add 228 * rule 1 sets the <code>MONTH</code> field to April. Using a 229 * <code>GregorianCalendar</code>, the <code>DAY_OF_MONTH</code> cannot 230 * be 31 in the month April. Add rule 2 sets it to the closest possible 231 * value, 30. Finally, the <strong>roll rule</strong> maintains the 232 * <code>YEAR</code> field value of 1999.</p> 233 * 234 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code> 235 * originally set to Sunday June 6, 1999. Calling 236 * <code>roll(Calendar.WEEK_OF_MONTH, -1)</code> sets the calendar to 237 * Tuesday June 1, 1999, whereas calling 238 * <code>add(Calendar.WEEK_OF_MONTH, -1)</code> sets the calendar to 239 * Sunday May 30, 1999. This is because the roll rule imposes an 240 * additional constraint: The <code>MONTH</code> must not change when the 241 * <code>WEEK_OF_MONTH</code> is rolled. Taken together with add rule 1, 242 * the resultant date must be between Tuesday June 1 and Saturday June 243 * 5. According to add rule 2, the <code>DAY_OF_WEEK</code>, an invariant 244 * when changing the <code>WEEK_OF_MONTH</code>, is set to Tuesday, the 245 * closest possible value to Sunday (where Sunday is the first day of the 246 * week).</p> 247 * 248 * <p><strong>Usage model</strong>. To motivate the behavior of 249 * <code>add()</code> and <code>roll()</code>, consider a user interface 250 * component with increment and decrement buttons for the month, day, and 251 * year, and an underlying <code>GregorianCalendar</code>. If the 252 * interface reads January 31, 1999 and the user presses the month 253 * increment button, what should it read? If the underlying 254 * implementation uses <code>set()</code>, it might read March 3, 1999. A 255 * better result would be February 28, 1999. Furthermore, if the user 256 * presses the month increment button again, it should read March 31, 257 * 1999, not March 28, 1999. By saving the original date and using either 258 * <code>add()</code> or <code>roll()</code>, depending on whether larger 259 * fields should be affected, the user interface can behave as most users 260 * will intuitively expect.</p> 261 * 262 * <p><b>Note:</b> You should always use {@link #roll roll} and {@link #add add} rather 263 * than attempting to perform arithmetic operations directly on the fields 264 * of a <tt>Calendar</tt>. It is quite possible for <tt>Calendar</tt> subclasses 265 * to have fields with non-linear behavior, for example missing months 266 * or days during non-leap years. The subclasses' <tt>add</tt> and <tt>roll</tt> 267 * methods will take this into account, while simple arithmetic manipulations 268 * may give invalid results. 269 * 270 * <p><big><big><b>Calendar Architecture in ICU4J</b></big></big></p> 271 * 272 * <p>Recently the implementation of <code>Calendar</code> has changed 273 * significantly in order to better support subclassing. The original 274 * <code>Calendar</code> class was designed to support subclassing, but 275 * it had only one implemented subclass, <code>GregorianCalendar</code>. 276 * With the implementation of several new calendar subclasses, including 277 * the <code>BuddhistCalendar</code>, <code>ChineseCalendar</code>, 278 * <code>HebrewCalendar</code>, <code>IslamicCalendar</code>, and 279 * <code>JapaneseCalendar</code>, the subclassing API has been reworked 280 * thoroughly. This section details the new subclassing API and other 281 * ways in which <code>com.ibm.icu.util.Calendar</code> differs from 282 * <code>java.util.Calendar</code>. 283 * </p> 284 * 285 * <p><big><b>Changes</b></big></p> 286 * 287 * <p>Overview of changes between the classic <code>Calendar</code> 288 * architecture and the new architecture. 289 * 290 * <ul> 291 * 292 * <li>The <code>fields[]</code> array is <code>private</code> now 293 * instead of <code>protected</code>. Subclasses must access it 294 * using the methods {@link #internalSet} and 295 * {@link #internalGet}. <b>Motivation:</b> Subclasses should 296 * not directly access data members.</li> 297 * 298 * <li>The <code>time</code> long word is <code>private</code> now 299 * instead of <code>protected</code>. Subclasses may access it using 300 * the method {@link #internalGetTimeInMillis}, which does not 301 * provoke an update. <b>Motivation:</b> Subclasses should not 302 * directly access data members.</li> 303 * 304 * <li>The scope of responsibility of subclasses has been drastically 305 * reduced. As much functionality as possible is implemented in the 306 * <code>Calendar</code> base class. As a result, it is much easier 307 * to subclass <code>Calendar</code>. <b>Motivation:</b> Subclasses 308 * should not have to reimplement common code. Certain behaviors are 309 * common across calendar systems: The definition and behavior of 310 * week-related fields and time fields, the arithmetic 311 * ({@link #add(int, int) add} and {@link #roll(int, int) roll}) behavior of many 312 * fields, and the field validation system.</li> 313 * 314 * <li>The subclassing API has been completely redesigned.</li> 315 * 316 * <li>The <code>Calendar</code> base class contains some Gregorian 317 * calendar algorithmic support that subclasses can use (specifically 318 * in {@link #handleComputeFields}). Subclasses can use the 319 * methods <code>getGregorianXxx()</code> to obtain precomputed 320 * values. <b>Motivation:</b> This is required by all 321 * <code>Calendar</code> subclasses in order to implement consistent 322 * time zone behavior, and Gregorian-derived systems can use the 323 * already computed data.</li> 324 * 325 * <li>The <code>FIELD_COUNT</code> constant has been removed. Use 326 * {@link #getFieldCount}. In addition, framework API has been 327 * added to allow subclasses to define additional fields. 328 * <b>Motivation: </b>The number of fields is not constant across 329 * calendar systems.</li> 330 * 331 * <li>The range of handled dates has been narrowed from +/- 332 * ~300,000,000 years to +/- ~5,000,000 years. In practical terms 333 * this should not affect clients. However, it does mean that client 334 * code cannot be guaranteed well-behaved results with dates such as 335 * <code>Date(Long.MIN_VALUE)</code> or 336 * <code>Date(Long.MAX_VALUE)</code>. Instead, the 337 * <code>Calendar</code> protected constants should be used. 338 * <b>Motivation:</b> With 339 * the addition of the {@link #JULIAN_DAY} field, Julian day 340 * numbers must be restricted to a 32-bit <code>int</code>. This 341 * restricts the overall supported range. Furthermore, restricting 342 * the supported range simplifies the computations by removing 343 * special case code that was used to accomodate arithmetic overflow 344 * at millis near <code>Long.MIN_VALUE</code> and 345 * <code>Long.MAX_VALUE</code>.</li> 346 * 347 * <li>New fields are implemented: {@link #JULIAN_DAY} defines 348 * single-field specification of the 349 * date. {@link #MILLISECONDS_IN_DAY} defines a single-field 350 * specification of the wall time. {@link #DOW_LOCAL} and 351 * {@link #YEAR_WOY} implement localized day-of-week and 352 * week-of-year behavior.</li> 353 * 354 * <li>Subclasses can access protected millisecond constants 355 * defined in <code>Calendar</code>.</li> 356 * 357 * <li>New API has been added to support calendar-specific subclasses 358 * of <code>DateFormat</code>.</li> 359 * 360 * <li>Several subclasses have been implemented, representing 361 * various international calendar systems.</li> 362 * 363 * </ul> 364 * 365 * <p><big><b>Subclass API</b></big></p> 366 * 367 * <p>The original <code>Calendar</code> API was based on the experience 368 * of implementing a only a single subclass, 369 * <code>GregorianCalendar</code>. As a result, all of the subclassing 370 * kinks had not been worked out. The new subclassing API has been 371 * refined based on several implemented subclasses. This includes methods 372 * that must be overridden and methods for subclasses to call. Subclasses 373 * no longer have direct access to <code>fields</code> and 374 * <code>stamp</code>. Instead, they have new API to access 375 * these. Subclasses are able to allocate the <code>fields</code> array 376 * through a protected framework method; this allows subclasses to 377 * specify additional fields. </p> 378 * 379 * <p>More functionality has been moved into the base class. The base 380 * class now contains much of the computational machinery to support the 381 * Gregorian calendar. This is based on two things: (1) Many calendars 382 * are based on the Gregorian calendar (such as the Buddhist and Japanese 383 * imperial calendars). (2) <em>All</em> calendars require basic 384 * Gregorian support in order to handle timezone computations. </p> 385 * 386 * <p>Common computations have been moved into 387 * <code>Calendar</code>. Subclasses no longer compute the week related 388 * fields and the time related fields. These are commonly handled for all 389 * calendars by the base class. </p> 390 * 391 * <p><b>Subclass computation of time <tt>=></tt> fields</b> 392 * 393 * <p>The {@link #ERA}, {@link #YEAR}, 394 * {@link #EXTENDED_YEAR}, {@link #MONTH}, 395 * {@link #DAY_OF_MONTH}, and {@link #DAY_OF_YEAR} fields are 396 * computed by the subclass, based on the Julian day. All other fields 397 * are computed by <code>Calendar</code>. 398 * 399 * <ul> 400 * 401 * <li>Subclasses should implement {@link #handleComputeFields} 402 * to compute the {@link #ERA}, {@link #YEAR}, 403 * {@link #EXTENDED_YEAR}, {@link #MONTH}, 404 * {@link #DAY_OF_MONTH}, and {@link #DAY_OF_YEAR} fields, 405 * based on the value of the {@link #JULIAN_DAY} field. If there 406 * are calendar-specific fields not defined by <code>Calendar</code>, 407 * they must also be computed. These are the only fields that the 408 * subclass should compute. All other fields are computed by the base 409 * class, so time and week fields behave in a consistent way across 410 * all calendars. The default version of this method in 411 * <code>Calendar</code> implements a proleptic Gregorian 412 * calendar. Within this method, subclasses may call 413 * <code>getGregorianXxx()</code> to obtain the Gregorian calendar 414 * month, day of month, and extended year for the given date.</li> 415 * 416 * </ul> 417 * 418 * <p><b>Subclass computation of fields <tt>=></tt> time</b> 419 * 420 * <p>The interpretation of most field values is handled entirely by 421 * <code>Calendar</code>. <code>Calendar</code> determines which fields 422 * are set, which are not, which are set more recently, and so on. In 423 * addition, <code>Calendar</code> handles the computation of the time 424 * from the time fields and handles the week-related fields. The only 425 * thing the subclass must do is determine the extended year, based on 426 * the year fields, and then, given an extended year and a month, it must 427 * return a Julian day number. 428 * 429 * <ul> 430 * 431 * <li>Subclasses should implement {@link #handleGetExtendedYear} 432 * to return the extended year for this calendar system, based on the 433 * {@link #YEAR}, {@link #EXTENDED_YEAR}, and any fields that 434 * the calendar system uses that are larger than a year, such as 435 * {@link #ERA}.</li> 436 * 437 * <li>Subclasses should implement {@link #handleComputeMonthStart} 438 * to return the Julian day number 439 * associated with a month and extended year. This is the Julian day 440 * number of the day before the first day of the month. The month 441 * number is zero-based. This computation should not depend on any 442 * field values.</li> 443 * 444 * </ul> 445 * 446 * <p><b>Other methods</b> 447 * 448 * <ul> 449 * 450 * <li>Subclasses should implement {@link #handleGetMonthLength} 451 * to return the number of days in a 452 * given month of a given extended year. The month number, as always, 453 * is zero-based.</li> 454 * 455 * <li>Subclasses should implement {@link #handleGetYearLength} 456 * to return the number of days in the given 457 * extended year. This method is used by 458 * <tt>computeWeekFields</tt> to compute the 459 * {@link #WEEK_OF_YEAR} and {@link #YEAR_WOY} fields.</li> 460 * 461 * <li>Subclasses should implement {@link #handleGetLimit} 462 * to return the protected values of a field, depending on the value of 463 * <code>limitType</code>. This method only needs to handle the 464 * fields {@link #ERA}, {@link #YEAR}, {@link #MONTH}, 465 * {@link #WEEK_OF_YEAR}, {@link #WEEK_OF_MONTH}, 466 * {@link #DAY_OF_MONTH}, {@link #DAY_OF_YEAR}, 467 * {@link #DAY_OF_WEEK_IN_MONTH}, {@link #YEAR_WOY}, and 468 * {@link #EXTENDED_YEAR}. Other fields are invariant (with 469 * respect to calendar system) and are handled by the base 470 * class.</li> 471 * 472 * <li>Optionally, subclasses may override {@link #validateField} 473 * to check any subclass-specific fields. If the 474 * field's value is out of range, the method should throw an 475 * <code>IllegalArgumentException</code>. The method may call 476 * <code>super.validateField(field)</code> to handle fields in a 477 * generic way, that is, to compare them to the range 478 * <code>getMinimum(field)</code>..<code>getMaximum(field)</code>.</li> 479 * 480 * <li>Optionally, subclasses may override 481 * {@link #handleCreateFields} to create an <code>int[]</code> 482 * array large enough to hold the calendar's fields. This is only 483 * necessary if the calendar defines additional fields beyond those 484 * defined by <code>Calendar</code>. The length of the result must be 485 * be between the base and maximum field counts.</li> 486 * 487 * <li>Optionally, subclasses may override 488 * {@link #handleGetDateFormat} to create a 489 * <code>DateFormat</code> appropriate to this calendar. This is only 490 * required if a calendar subclass redefines the use of a field (for 491 * example, changes the {@link #ERA} field from a symbolic field 492 * to a numeric one) or defines an additional field.</li> 493 * 494 * <li>Optionally, subclasses may override {@link #roll roll} and 495 * {@link #add add} to handle fields that are discontinuous. For 496 * example, in the Hebrew calendar the month "Adar I" only 497 * occurs in leap years; in other years the calendar jumps from 498 * Shevat (month #4) to Adar (month #6). The {@link 499 * HebrewCalendar#add HebrewCalendar.add} and {@link 500 * HebrewCalendar#roll HebrewCalendar.roll} methods take this into 501 * account, so that adding 1 month to Shevat gives the proper result 502 * (Adar) in a non-leap year. The protected utility method {@link 503 * #pinField pinField} is often useful when implementing these two 504 * methods. </li> 505 * 506 * </ul> 507 * 508 * <p><big><b>Normalized behavior</b></big> 509 * 510 * <p>The behavior of certain fields has been made consistent across all 511 * calendar systems and implemented in <code>Calendar</code>. 512 * 513 * <ul> 514 * 515 * <li>Time is normalized. Even though some calendar systems transition 516 * between days at sunset or at other times, all ICU4J calendars 517 * transition between days at <em>local zone midnight</em>. This 518 * allows ICU4J to centralize the time computations in 519 * <code>Calendar</code> and to maintain basic correpsondences 520 * between calendar systems. Affected fields: {@link #AM_PM}, 521 * {@link #HOUR}, {@link #HOUR_OF_DAY}, {@link #MINUTE}, 522 * {@link #SECOND}, {@link #MILLISECOND}, 523 * {@link #ZONE_OFFSET}, and {@link #DST_OFFSET}.</li> 524 * 525 * <li>DST behavior is normalized. Daylight savings time behavior is 526 * computed the same for all calendar systems, and depends on the 527 * value of several <code>GregorianCalendar</code> fields: the 528 * {@link #YEAR}, {@link #MONTH}, and 529 * {@link #DAY_OF_MONTH}. As a result, <code>Calendar</code> 530 * always computes these fields, even for non-Gregorian calendar 531 * systems. These fields are available to subclasses.</li> 532 * 533 * <li>Weeks are normalized. Although locales define the week 534 * differently, in terms of the day on which it starts, and the 535 * designation of week number one of a month or year, they all use a 536 * common mechanism. Furthermore, the day of the week has a simple 537 * and consistent definition throughout history. For example, 538 * although the Gregorian calendar introduced a discontinuity when 539 * first instituted, the day of week was not disrupted. For this 540 * reason, the fields {@link #DAY_OF_WEEK}, <code>WEEK_OF_YEAR, 541 * WEEK_OF_MONTH</code>, {@link #DAY_OF_WEEK_IN_MONTH}, 542 * {@link #DOW_LOCAL}, {@link #YEAR_WOY} are all computed in 543 * a consistent way in the base class, based on the 544 * {@link #EXTENDED_YEAR}, {@link #DAY_OF_YEAR}, 545 * {@link #MONTH}, and {@link #DAY_OF_MONTH}, which are 546 * computed by the subclass.</li> 547 * 548 * </ul> 549 * 550 * <p><big><b>Supported range</b></big> 551 * 552 * <p>The allowable range of <code>Calendar</code> has been 553 * narrowed. <code>GregorianCalendar</code> used to attempt to support 554 * the range of dates with millisecond values from 555 * <code>Long.MIN_VALUE</code> to <code>Long.MAX_VALUE</code>. This 556 * introduced awkward constructions (hacks) which slowed down 557 * performance. It also introduced non-uniform behavior at the 558 * boundaries. The new <code>Calendar</code> protocol specifies the 559 * maximum range of supportable dates as those having Julian day numbers 560 * of <code>-0x7F000000</code> to <code>+0x7F000000</code>. This 561 * corresponds to years from ~5,000,000 BCE to ~5,000,000 CE. Programmers 562 * should use the protected constants in <code>Calendar</code> to 563 * specify an extremely early or extremely late date.</p> 564 * 565 * <p><big><b>General notes</b></big> 566 * 567 * <ul> 568 * 569 * <li>Calendars implementations are <em>proleptic</em>. For example, 570 * even though the Gregorian calendar was not instituted until the 571 * 16th century, the <code>GregorianCalendar</code> class supports 572 * dates before the historical onset of the calendar by extending the 573 * calendar system backward in time. Similarly, the 574 * <code>HebrewCalendar</code> extends backward before the start of 575 * its epoch into zero and negative years. Subclasses do not throw 576 * exceptions because a date precedes the historical start of a 577 * calendar system. Instead, they implement 578 * {@link #handleGetLimit} to return appropriate limits on 579 * {@link #YEAR}, {@link #ERA}, etc. fields. Then, if the 580 * calendar is set to not be lenient, out-of-range field values will 581 * trigger an exception.</li> 582 * 583 * <li>Calendar system subclasses compute a <em>extended 584 * year</em>. This differs from the {@link #YEAR} field in that 585 * it ranges over all integer values, including zero and negative 586 * values, and it encapsulates the information of the 587 * {@link #YEAR} field and all larger fields. Thus, for the 588 * Gregorian calendar, the {@link #EXTENDED_YEAR} is computed as 589 * <code>ERA==AD ? YEAR : 1-YEAR</code>. Another example is the Mayan 590 * long count, which has years (<code>KUN</code>) and nested cycles 591 * of years (<code>KATUN</code> and <code>BAKTUN</code>). The Mayan 592 * {@link #EXTENDED_YEAR} is computed as <code>TUN + 20 * (KATUN 593 * + 20 * BAKTUN)</code>. The <code>Calendar</code> base class uses 594 * the {@link #EXTENDED_YEAR} field to compute the week-related 595 * fields.</li> 596 * 597 * </ul> 598 * 599 * @see Date 600 * @see GregorianCalendar 601 * @see TimeZone 602 * @see DateFormat 603 * @author Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu, Laura Werner 604 * @stable ICU 2.0 605 */ 606public class Calendar implements Serializable, Cloneable, Comparable<Calendar> { 607 private static final long serialVersionUID = 1L; 608 609 /** 610 * @internal 611 */ 612 public final java.util.Calendar calendar; 613 614 /** 615 * @internal 616 * @param delegate the Calendar to which to delegate 617 */ 618 public Calendar(java.util.Calendar delegate) { 619 this.calendar = delegate; 620 } 621 622 // Data flow in Calendar 623 // --------------------- 624 625 // The current time is represented in two ways by Calendar: as UTC 626 // milliseconds from the epoch start (1 January 1970 0:00 UTC), and as local 627 // fields such as MONTH, HOUR, AM_PM, etc. It is possible to compute the 628 // millis from the fields, and vice versa. The data needed to do this 629 // conversion is encapsulated by a TimeZone object owned by the Calendar. 630 // The data provided by the TimeZone object may also be overridden if the 631 // user sets the ZONE_OFFSET and/or DST_OFFSET fields directly. The class 632 // keeps track of what information was most recently set by the caller, and 633 // uses that to compute any other information as needed. 634 635 // If the user sets the fields using set(), the data flow is as follows. 636 // This is implemented by the Calendar subclass's computeTime() method. 637 // During this process, certain fields may be ignored. The disambiguation 638 // algorithm for resolving which fields to pay attention to is described 639 // above. 640 641 // local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.) 642 // | 643 // | Using Calendar-specific algorithm 644 // V 645 // local standard millis 646 // | 647 // | Using TimeZone or user-set ZONE_OFFSET / DST_OFFSET 648 // V 649 // UTC millis (in time data member) 650 651 // If the user sets the UTC millis using setTime(), the data flow is as 652 // follows. This is implemented by the Calendar subclass's computeFields() 653 // method. 654 655 // UTC millis (in time data member) 656 // | 657 // | Using TimeZone getOffset() 658 // V 659 // local standard millis 660 // | 661 // | Using Calendar-specific algorithm 662 // V 663 // local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.) 664 665 // In general, a round trip from fields, through local and UTC millis, and 666 // back out to fields is made when necessary. This is implemented by the 667 // complete() method. Resolving a partial set of fields into a UTC millis 668 // value allows all remaining fields to be generated from that value. If 669 // the Calendar is lenient, the fields are also renormalized to standard 670 // ranges when they are regenerated. 671 672 /** 673 * Field number for <code>get</code> and <code>set</code> indicating the 674 * era, e.g., AD or BC in the Julian calendar. This is a calendar-specific 675 * value; see subclass documentation. 676 * @see GregorianCalendar#AD 677 * @see GregorianCalendar#BC 678 * @stable ICU 2.0 679 */ 680 public final static int ERA = 0; 681 682 /** 683 * Field number for <code>get</code> and <code>set</code> indicating the 684 * year. This is a calendar-specific value; see subclass documentation. 685 * @stable ICU 2.0 686 */ 687 public final static int YEAR = 1; 688 689 /** 690 * Field number for <code>get</code> and <code>set</code> indicating the 691 * month. This is a calendar-specific value. The first month of the year is 692 * <code>JANUARY</code>; the last depends on the number of months in a year. 693 * @see #JANUARY 694 * @see #FEBRUARY 695 * @see #MARCH 696 * @see #APRIL 697 * @see #MAY 698 * @see #JUNE 699 * @see #JULY 700 * @see #AUGUST 701 * @see #SEPTEMBER 702 * @see #OCTOBER 703 * @see #NOVEMBER 704 * @see #DECEMBER 705 * @see #UNDECIMBER 706 * @stable ICU 2.0 707 */ 708 public final static int MONTH = 2; 709 710 /** 711 * Field number for <code>get</code> and <code>set</code> indicating the 712 * week number within the current year. The first week of the year, as 713 * defined by {@link #getFirstDayOfWeek()} and 714 * {@link #getMinimalDaysInFirstWeek()}, has value 1. Subclasses define 715 * the value of {@link #WEEK_OF_YEAR} for days before the first week of 716 * the year. 717 * @see #getFirstDayOfWeek 718 * @see #getMinimalDaysInFirstWeek 719 * @stable ICU 2.0 720 */ 721 public final static int WEEK_OF_YEAR = 3; 722 723 /** 724 * Field number for <code>get</code> and <code>set</code> indicating the 725 * week number within the current month. The first week of the month, as 726 * defined by {@link #getFirstDayOfWeek()} and 727 * {@link #getMinimalDaysInFirstWeek()}, has value 1. Subclasses define 728 * the value of {@link #WEEK_OF_MONTH} for days before the first week of 729 * the month. 730 * @see #getFirstDayOfWeek 731 * @see #getMinimalDaysInFirstWeek 732 * @stable ICU 2.0 733 */ 734 public final static int WEEK_OF_MONTH = 4; 735 736 /** 737 * Field number for <code>get</code> and <code>set</code> indicating the 738 * day of the month. This is a synonym for {@link #DAY_OF_MONTH}. 739 * The first day of the month has value 1. 740 * @see #DAY_OF_MONTH 741 * @stable ICU 2.0 742 */ 743 public final static int DATE = 5; 744 745 /** 746 * Field number for <code>get</code> and <code>set</code> indicating the 747 * day of the month. This is a synonym for {@link #DATE}. 748 * The first day of the month has value 1. 749 * @see #DATE 750 * @stable ICU 2.0 751 */ 752 public final static int DAY_OF_MONTH = 5; 753 754 /** 755 * Field number for <code>get</code> and <code>set</code> indicating the day 756 * number within the current year. The first day of the year has value 1. 757 * @stable ICU 2.0 758 */ 759 public final static int DAY_OF_YEAR = 6; 760 761 /** 762 * Field number for <code>get</code> and <code>set</code> indicating the day 763 * of the week. This field takes values {@link #SUNDAY}, 764 * {@link #MONDAY}, {@link #TUESDAY}, {@link #WEDNESDAY}, 765 * {@link #THURSDAY}, {@link #FRIDAY}, and {@link #SATURDAY}. 766 * @see #SUNDAY 767 * @see #MONDAY 768 * @see #TUESDAY 769 * @see #WEDNESDAY 770 * @see #THURSDAY 771 * @see #FRIDAY 772 * @see #SATURDAY 773 * @stable ICU 2.0 774 */ 775 public final static int DAY_OF_WEEK = 7; 776 777 /** 778 * Field number for <code>get</code> and <code>set</code> indicating the 779 * ordinal number of the day of the week within the current month. Together 780 * with the {@link #DAY_OF_WEEK} field, this uniquely specifies a day 781 * within a month. Unlike {@link #WEEK_OF_MONTH} and 782 * {@link #WEEK_OF_YEAR}, this field's value does <em>not</em> depend on 783 * {@link #getFirstDayOfWeek()} or 784 * {@link #getMinimalDaysInFirstWeek()}. <code>DAY_OF_MONTH 1</code> 785 * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH 786 * 1</code>; <code>8</code> through <code>15</code> correspond to 787 * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on. 788 * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before 789 * <code>DAY_OF_WEEK_IN_MONTH 1</code>. Negative values count back from the 790 * end of the month, so the last Sunday of a month is specified as 791 * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>. Because 792 * negative values count backward they will usually be aligned differently 793 * within the month than positive values. For example, if a month has 31 794 * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap 795 * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>. 796 * @see #DAY_OF_WEEK 797 * @see #WEEK_OF_MONTH 798 * @stable ICU 2.0 799 */ 800 public final static int DAY_OF_WEEK_IN_MONTH = 8; 801 802 /** 803 * Field number for <code>get</code> and <code>set</code> indicating 804 * whether the <code>HOUR</code> is before or after noon. 805 * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>. 806 * @see #AM 807 * @see #PM 808 * @see #HOUR 809 * @stable ICU 2.0 810 */ 811 public final static int AM_PM = 9; 812 813 /** 814 * Field number for <code>get</code> and <code>set</code> indicating the 815 * hour of the morning or afternoon. <code>HOUR</code> is used for the 12-hour 816 * clock. 817 * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10. 818 * @see #AM_PM 819 * @see #HOUR_OF_DAY 820 * @stable ICU 2.0 821 */ 822 public final static int HOUR = 10; 823 824 /** 825 * Field number for <code>get</code> and <code>set</code> indicating the 826 * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock. 827 * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22. 828 * @see #HOUR 829 * @stable ICU 2.0 830 */ 831 public final static int HOUR_OF_DAY = 11; 832 833 /** 834 * Field number for <code>get</code> and <code>set</code> indicating the 835 * minute within the hour. 836 * E.g., at 10:04:15.250 PM the <code>MINUTE</code> is 4. 837 * @stable ICU 2.0 838 */ 839 public final static int MINUTE = 12; 840 841 /** 842 * Field number for <code>get</code> and <code>set</code> indicating the 843 * second within the minute. 844 * E.g., at 10:04:15.250 PM the <code>SECOND</code> is 15. 845 * @stable ICU 2.0 846 */ 847 public final static int SECOND = 13; 848 849 /** 850 * Field number for <code>get</code> and <code>set</code> indicating the 851 * millisecond within the second. 852 * E.g., at 10:04:15.250 PM the <code>MILLISECOND</code> is 250. 853 * @stable ICU 2.0 854 */ 855 public final static int MILLISECOND = 14; 856 857 /** 858 * Field number for <code>get</code> and <code>set</code> indicating the 859 * raw offset from GMT in milliseconds. 860 * @stable ICU 2.0 861 */ 862 public final static int ZONE_OFFSET = 15; 863 864 /** 865 * Field number for <code>get</code> and <code>set</code> indicating the 866 * daylight savings offset in milliseconds. 867 * @stable ICU 2.0 868 */ 869 public final static int DST_OFFSET = 16; 870 871// /** 872// * {@icu} Field number for <code>get()</code> and <code>set()</code> 873// * indicating the extended year corresponding to the 874// * {@link #WEEK_OF_YEAR} field. This may be one greater or less 875// * than the value of {@link #EXTENDED_YEAR}. 876// * @stable ICU 2.0 877// */ 878// public static final int YEAR_WOY = 17; 879// 880// /** 881// * {@icu} Field number for <code>get()</code> and <code>set()</code> 882// * indicating the localized day of week. This will be a value from 1 883// * to 7 inclusive, with 1 being the localized first day of the week. 884// * @stable ICU 2.0 885// */ 886// public static final int DOW_LOCAL = 18; 887// 888// /** 889// * {@icu} Field number for <code>get()</code> and <code>set()</code> 890// * indicating the extended year. This is a single number designating 891// * the year of this calendar system, encompassing all supra-year 892// * fields. For example, for the Julian calendar system, year numbers 893// * are positive, with an era of BCE or CE. An extended year value for 894// * the Julian calendar system assigns positive values to CE years and 895// * negative values to BCE years, with 1 BCE being year 0. 896// * @stable ICU 2.0 897// */ 898// public static final int EXTENDED_YEAR = 19; 899// 900// /** 901// * {@icu} Field number for <code>get()</code> and <code>set()</code> 902// * indicating the modified Julian day number. This is different from 903// * the conventional Julian day number in two regards. First, it 904// * demarcates days at local zone midnight, rather than noon GMT. 905// * Second, it is a local number; that is, it depends on the local time 906// * zone. It can be thought of as a single number that encompasses all 907// * the date-related fields. 908// * @stable ICU 2.0 909// */ 910// public static final int JULIAN_DAY = 20; 911// 912// /** 913// * {@icu} Field number for <code>get()</code> and <code>set()</code> 914// * indicating the milliseconds in the day. This ranges from 0 to 915// * 23:59:59.999 (regardless of DST). This field behaves 916// * <em>exactly</em> like a composite of all time-related fields, not 917// * including the zone fields. As such, it also reflects 918// * discontinuities of those fields on DST transition days. On a day of 919// * DST onset, it will jump forward. On a day of DST cessation, it will 920// * jump backward. This reflects the fact that is must be combined with 921// * the DST_OFFSET field to obtain a unique local time value. 922// * @stable ICU 2.0 923// */ 924// public static final int MILLISECONDS_IN_DAY = 21; 925// 926// /** 927// * {@icu} Field indicating whether or not the current month is a leap month. 928// * Should have a value of 0 for non-leap months, and 1 for leap months. 929// * @draft ICU 4.4 930// * @provisional This API might change or be removed in a future release. 931// */ 932// public static final int IS_LEAP_MONTH = 22; 933 934 /** 935 * Value of the <code>DAY_OF_WEEK</code> field indicating 936 * Sunday. 937 * @stable ICU 2.0 938 */ 939 public final static int SUNDAY = 1; 940 941 /** 942 * Value of the <code>DAY_OF_WEEK</code> field indicating 943 * Monday. 944 * @stable ICU 2.0 945 */ 946 public final static int MONDAY = 2; 947 948 /** 949 * Value of the <code>DAY_OF_WEEK</code> field indicating 950 * Tuesday. 951 * @stable ICU 2.0 952 */ 953 public final static int TUESDAY = 3; 954 955 /** 956 * Value of the <code>DAY_OF_WEEK</code> field indicating 957 * Wednesday. 958 * @stable ICU 2.0 959 */ 960 public final static int WEDNESDAY = 4; 961 962 /** 963 * Value of the <code>DAY_OF_WEEK</code> field indicating 964 * Thursday. 965 * @stable ICU 2.0 966 */ 967 public final static int THURSDAY = 5; 968 969 /** 970 * Value of the <code>DAY_OF_WEEK</code> field indicating 971 * Friday. 972 * @stable ICU 2.0 973 */ 974 public final static int FRIDAY = 6; 975 976 /** 977 * Value of the <code>DAY_OF_WEEK</code> field indicating 978 * Saturday. 979 * @stable ICU 2.0 980 */ 981 public final static int SATURDAY = 7; 982 983 /** 984 * Value of the <code>MONTH</code> field indicating the 985 * first month of the year. 986 * @stable ICU 2.0 987 */ 988 public final static int JANUARY = 0; 989 990 /** 991 * Value of the <code>MONTH</code> field indicating the 992 * second month of the year. 993 * @stable ICU 2.0 994 */ 995 public final static int FEBRUARY = 1; 996 997 /** 998 * Value of the <code>MONTH</code> field indicating the 999 * third month of the year. 1000 * @stable ICU 2.0 1001 */ 1002 public final static int MARCH = 2; 1003 1004 /** 1005 * Value of the <code>MONTH</code> field indicating the 1006 * fourth month of the year. 1007 * @stable ICU 2.0 1008 */ 1009 public final static int APRIL = 3; 1010 1011 /** 1012 * Value of the <code>MONTH</code> field indicating the 1013 * fifth month of the year. 1014 * @stable ICU 2.0 1015 */ 1016 public final static int MAY = 4; 1017 1018 /** 1019 * Value of the <code>MONTH</code> field indicating the 1020 * sixth month of the year. 1021 * @stable ICU 2.0 1022 */ 1023 public final static int JUNE = 5; 1024 1025 /** 1026 * Value of the <code>MONTH</code> field indicating the 1027 * seventh month of the year. 1028 * @stable ICU 2.0 1029 */ 1030 public final static int JULY = 6; 1031 1032 /** 1033 * Value of the <code>MONTH</code> field indicating the 1034 * eighth month of the year. 1035 * @stable ICU 2.0 1036 */ 1037 public final static int AUGUST = 7; 1038 1039 /** 1040 * Value of the <code>MONTH</code> field indicating the 1041 * ninth month of the year. 1042 * @stable ICU 2.0 1043 */ 1044 public final static int SEPTEMBER = 8; 1045 1046 /** 1047 * Value of the <code>MONTH</code> field indicating the 1048 * tenth month of the year. 1049 * @stable ICU 2.0 1050 */ 1051 public final static int OCTOBER = 9; 1052 1053 /** 1054 * Value of the <code>MONTH</code> field indicating the 1055 * eleventh month of the year. 1056 * @stable ICU 2.0 1057 */ 1058 public final static int NOVEMBER = 10; 1059 1060 /** 1061 * Value of the <code>MONTH</code> field indicating the 1062 * twelfth month of the year. 1063 * @stable ICU 2.0 1064 */ 1065 public final static int DECEMBER = 11; 1066 1067 /** 1068 * Value of the <code>MONTH</code> field indicating the 1069 * thirteenth month of the year. Although {@link GregorianCalendar} 1070 * does not use this value, lunar calendars do. 1071 * @stable ICU 2.0 1072 */ 1073 public final static int UNDECIMBER = 12; 1074 1075 /** 1076 * Value of the <code>AM_PM</code> field indicating the 1077 * period of the day from midnight to just before noon. 1078 * @stable ICU 2.0 1079 */ 1080 public final static int AM = 0; 1081 1082 /** 1083 * Value of the <code>AM_PM</code> field indicating the 1084 * period of the day from noon to just before midnight. 1085 * @stable ICU 2.0 1086 */ 1087 public final static int PM = 1; 1088 1089 /** 1090 * {@icu} Value returned by getDayOfWeekType(int dayOfWeek) to indicate a 1091 * weekday. 1092 * @see #WEEKEND 1093 * @see #WEEKEND_ONSET 1094 * @see #WEEKEND_CEASE 1095 * @see #getDayOfWeekType 1096 * @stable ICU 2.0 1097 */ 1098 public static final int WEEKDAY = 0; 1099 1100 /** 1101 * {@icu} Value returned by getDayOfWeekType(int dayOfWeek) to indicate a 1102 * weekend day. 1103 * @see #WEEKDAY 1104 * @see #WEEKEND_ONSET 1105 * @see #WEEKEND_CEASE 1106 * @see #getDayOfWeekType 1107 * @stable ICU 2.0 1108 */ 1109 public static final int WEEKEND = 1; 1110 1111 /** 1112 * {@icu} Value returned by getDayOfWeekType(int dayOfWeek) to indicate a 1113 * day that starts as a weekday and transitions to the weekend. 1114 * Call getWeekendTransition() to get the point of transition. 1115 * @see #WEEKDAY 1116 * @see #WEEKEND 1117 * @see #WEEKEND_CEASE 1118 * @see #getDayOfWeekType 1119 * @stable ICU 2.0 1120 */ 1121 public static final int WEEKEND_ONSET = 2; 1122 1123 /** 1124 * {@icu} Value returned by getDayOfWeekType(int dayOfWeek) to indicate a 1125 * day that starts as the weekend and transitions to a weekday. 1126 * Call getWeekendTransition() to get the point of transition. 1127 * @see #WEEKDAY 1128 * @see #WEEKEND 1129 * @see #WEEKEND_ONSET 1130 * @see #getDayOfWeekType 1131 * @stable ICU 2.0 1132 */ 1133 public static final int WEEKEND_CEASE = 3; 1134 1135 /** 1136 * {@icu}Option used by {@link #setRepeatedWallTimeOption(int)} and 1137 * {@link #setSkippedWallTimeOption(int)} specifying an ambiguous wall time 1138 * to be interpreted as the latest. 1139 * @see #setRepeatedWallTimeOption(int) 1140 * @see #getRepeatedWallTimeOption() 1141 * @see #setSkippedWallTimeOption(int) 1142 * @see #getSkippedWallTimeOption() 1143 * @draft ICU 49 1144 * @provisional This API might change or be removed in a future release. 1145 */ 1146 public static final int WALLTIME_LAST = 0; 1147 1148 /** 1149 * {@icu}Option used by {@link #setRepeatedWallTimeOption(int)} and 1150 * {@link #setSkippedWallTimeOption(int)} specifying an ambiguous wall time 1151 * to be interpreted as the earliest. 1152 * @see #setRepeatedWallTimeOption(int) 1153 * @see #getRepeatedWallTimeOption() 1154 * @see #setSkippedWallTimeOption(int) 1155 * @see #getSkippedWallTimeOption() 1156 * @draft ICU 49 1157 * @provisional This API might change or be removed in a future release. 1158 */ 1159 public static final int WALLTIME_FIRST = 1; 1160 1161 /** 1162 * {@icu}Option used by {@link #setSkippedWallTimeOption(int)} specifying an 1163 * ambiguous wall time to be interpreted as the next valid wall time. 1164 * @see #setSkippedWallTimeOption(int) 1165 * @see #getSkippedWallTimeOption() 1166 * @draft ICU 49 1167 * @provisional This API might change or be removed in a future release. 1168 */ 1169 public static final int WALLTIME_NEXT_VALID = 2; 1170 1171 /** 1172 * Constructs a Calendar with the default time zone 1173 * and locale. 1174 * @see TimeZone#getDefault 1175 * @stable ICU 2.0 1176 */ 1177 protected Calendar() 1178 { 1179 this(TimeZone.getDefault(), ULocale.getDefault(Category.FORMAT)); 1180 } 1181 1182 /** 1183 * Constructs a calendar with the specified time zone and locale. 1184 * @param zone the time zone to use 1185 * @param aLocale the locale for the week data 1186 * @stable ICU 2.0 1187 */ 1188 protected Calendar(TimeZone zone, Locale aLocale) 1189 { 1190 this(zone, ULocale.forLocale(aLocale)); 1191 } 1192 1193 /** 1194 * Constructs a calendar with the specified time zone and locale. 1195 * @param zone the time zone to use 1196 * @param locale the ulocale for the week data 1197 * @stable ICU 3.2 1198 */ 1199 protected Calendar(TimeZone zone, ULocale locale) 1200 { 1201 calendar = java.util.Calendar.getInstance(zone.timeZone, locale.toLocale()); 1202 } 1203 1204 /** 1205 * Returns a calendar using the default time zone and locale. 1206 * @return a Calendar. 1207 * @stable ICU 2.0 1208 */ 1209 public static synchronized Calendar getInstance() 1210 { 1211 return new Calendar(java.util.Calendar.getInstance(ULocale.getDefault(Category.FORMAT).toLocale())); 1212 } 1213 1214 /** 1215 * Returns a calendar using the specified time zone and default locale. 1216 * @param zone the time zone to use 1217 * @return a Calendar. 1218 * @stable ICU 2.0 1219 */ 1220 public static synchronized Calendar getInstance(TimeZone zone) 1221 { 1222 return new Calendar(java.util.Calendar.getInstance(zone.timeZone, ULocale.getDefault(Category.FORMAT).toLocale())); 1223 } 1224 1225 /** 1226 * Returns a calendar using the default time zone and specified locale. 1227 * @param aLocale the locale for the week data 1228 * @return a Calendar. 1229 * @stable ICU 2.0 1230 */ 1231 public static synchronized Calendar getInstance(Locale aLocale) 1232 { 1233 return new Calendar(java.util.Calendar.getInstance(aLocale)); 1234 } 1235 1236 /** 1237 * Returns a calendar using the default time zone and specified locale. 1238 * @param locale the ulocale for the week data 1239 * @return a Calendar. 1240 * @stable ICU 3.2 1241 */ 1242 public static synchronized Calendar getInstance(ULocale locale) 1243 { 1244 return new Calendar(java.util.Calendar.getInstance(locale.toLocale())); 1245 } 1246 1247 /** 1248 * Returns a calendar with the specified time zone and locale. 1249 * @param zone the time zone to use 1250 * @param aLocale the locale for the week data 1251 * @return a Calendar. 1252 * @stable ICU 2.0 1253 */ 1254 public static synchronized Calendar getInstance(TimeZone zone, 1255 Locale aLocale) { 1256 return new Calendar(java.util.Calendar.getInstance(zone.timeZone, aLocale)); 1257 } 1258 1259 /** 1260 * Returns a calendar with the specified time zone and locale. 1261 * @param zone the time zone to use 1262 * @param locale the ulocale for the week data 1263 * @return a Calendar. 1264 * @stable ICU 3.2 1265 */ 1266 public static synchronized Calendar getInstance(TimeZone zone, 1267 ULocale locale) { 1268 return new Calendar(java.util.Calendar.getInstance(zone.timeZone, locale.toLocale())); 1269 } 1270 1271 /** 1272 * Returns the list of locales for which Calendars are installed. 1273 * @return the list of locales for which Calendars are installed. 1274 * @stable ICU 2.0 1275 */ 1276 public static Locale[] getAvailableLocales() 1277 { 1278 return java.util.Calendar.getAvailableLocales(); 1279 } 1280 1281 /** 1282 * {@icu} Returns the list of locales for which Calendars are installed. 1283 * @return the list of locales for which Calendars are installed. 1284 * @draft ICU 3.2 (retain) 1285 * @provisional This API might change or be removed in a future release. 1286 */ 1287 public static ULocale[] getAvailableULocales() 1288 { 1289 if (availableLocales == null) { 1290 synchronized (Calendar.class) { 1291 if (availableLocales == null) { 1292 Locale[] locales = Locale.getAvailableLocales(); 1293 availableLocales = new ULocale[locales.length]; 1294 for (int i = 0; i < locales.length; i++) { 1295 availableLocales[i] = ULocale.forLocale(locales[i]); 1296 } 1297 } 1298 } 1299 } 1300 return availableLocales.clone(); 1301 } 1302 private static volatile ULocale[] availableLocales; 1303 1304// /** 1305// * {@icu} Given a key and a locale, returns an array of string values in a preferred 1306// * order that would make a difference. These are all and only those values where 1307// * the open (creation) of the service with the locale formed from the input locale 1308// * plus input keyword and that value has different behavior than creation with the 1309// * input locale alone. 1310// * @param key one of the keys supported by this service. For now, only 1311// * "calendar" is supported. 1312// * @param locale the locale 1313// * @param commonlyUsed if set to true it will return only commonly used values 1314// * with the given locale in preferred order. Otherwise, 1315// * it will return all the available values for the locale. 1316// * @return an array of string values for the given key and the locale. 1317// * @stable ICU 4.2 1318// */ 1319// public static final String[] getKeywordValuesForLocale(String key, ULocale locale, 1320// boolean commonlyUsed) { 1321// throw new UnsupportedOperationException("Method not supported by com.ibm.icu.base"); 1322// } 1323 1324 /** 1325 * Returns this Calendar's current time. 1326 * @return the current time. 1327 * @stable ICU 2.0 1328 */ 1329 public final Date getTime() { 1330 return calendar.getTime(); 1331 } 1332 1333 /** 1334 * Sets this Calendar's current time with the given Date. 1335 * 1336 * <p>Note: Calling <code>setTime</code> with 1337 * <code>Date(Long.MAX_VALUE)</code> or <code>Date(Long.MIN_VALUE)</code> 1338 * may yield incorrect field values from {@link #get(int)}. 1339 * @param date the given Date. 1340 * @stable ICU 2.0 1341 */ 1342 public final void setTime(Date date) { 1343 calendar.setTime(date); 1344 } 1345 1346 /** 1347 * Returns this Calendar's current time as a long. 1348 * @return the current time as UTC milliseconds from the epoch. 1349 * @stable ICU 2.0 1350 */ 1351 public long getTimeInMillis() { 1352 return calendar.getTimeInMillis(); 1353 } 1354 1355 /** 1356 * Sets this Calendar's current time from the given long value. 1357 * @param millis the new time in UTC milliseconds from the epoch. 1358 * @stable ICU 2.0 1359 */ 1360 public void setTimeInMillis( long millis ) { 1361 calendar.setTimeInMillis(millis); 1362 } 1363 1364 /** 1365 * Returns the value for a given time field. 1366 * @param field the given time field. 1367 * @return the value for the given time field. 1368 * @stable ICU 2.0 1369 */ 1370 public final int get(int field) 1371 { 1372 return calendar.get(getJDKField(field)); 1373 } 1374 1375 /** 1376 * Sets the time field with the given value. 1377 * @param field the given time field. 1378 * @param value the value to be set for the given time field. 1379 * @stable ICU 2.0 1380 */ 1381 public final void set(int field, int value) 1382 { 1383 calendar.set(getJDKField(field), value); 1384 } 1385 1386 /** 1387 * Sets the values for the fields year, month, and date. 1388 * Previous values of other fields are retained. If this is not desired, 1389 * call {@link #clear()} first. 1390 * @param year the value used to set the YEAR time field. 1391 * @param month the value used to set the MONTH time field. 1392 * Month value is 0-based. e.g., 0 for January. 1393 * @param date the value used to set the DATE time field. 1394 * @stable ICU 2.0 1395 */ 1396 public final void set(int year, int month, int date) 1397 { 1398 calendar.set(getJDKField(YEAR), year); 1399 calendar.set(getJDKField(MONTH), month); 1400 calendar.set(getJDKField(DATE), date); 1401 } 1402 1403 /** 1404 * Sets the values for the fields year, month, date, hour, and minute. 1405 * Previous values of other fields are retained. If this is not desired, 1406 * call {@link #clear()} first. 1407 * @param year the value used to set the YEAR time field. 1408 * @param month the value used to set the MONTH time field. 1409 * Month value is 0-based. e.g., 0 for January. 1410 * @param date the value used to set the DATE time field. 1411 * @param hour the value used to set the HOUR_OF_DAY time field. 1412 * @param minute the value used to set the MINUTE time field. 1413 * @stable ICU 2.0 1414 */ 1415 public final void set(int year, int month, int date, int hour, int minute) 1416 { 1417 calendar.set(getJDKField(YEAR), year); 1418 calendar.set(getJDKField(MONTH), month); 1419 calendar.set(getJDKField(DATE), date); 1420 calendar.set(getJDKField(HOUR_OF_DAY), hour); 1421 calendar.set(getJDKField(MINUTE), minute); 1422 } 1423 1424 /** 1425 * Sets the values for the fields year, month, date, hour, minute, and second. 1426 * Previous values of other fields are retained. If this is not desired, 1427 * call {@link #clear} first. 1428 * @param year the value used to set the YEAR time field. 1429 * @param month the value used to set the MONTH time field. 1430 * Month value is 0-based. e.g., 0 for January. 1431 * @param date the value used to set the DATE time field. 1432 * @param hour the value used to set the HOUR_OF_DAY time field. 1433 * @param minute the value used to set the MINUTE time field. 1434 * @param second the value used to set the SECOND time field. 1435 * @stable ICU 2.0 1436 */ 1437 public final void set(int year, int month, int date, int hour, int minute, 1438 int second) 1439 { 1440 calendar.set(getJDKField(YEAR), year); 1441 calendar.set(getJDKField(MONTH), month); 1442 calendar.set(getJDKField(DATE), date); 1443 calendar.set(getJDKField(HOUR_OF_DAY), hour); 1444 calendar.set(getJDKField(MINUTE), minute); 1445 calendar.set(getJDKField(SECOND), second); 1446 } 1447 1448 /** 1449 * Clears the values of all the time fields. 1450 * @stable ICU 2.0 1451 */ 1452 public final void clear() 1453 { 1454 calendar.clear(); 1455 } 1456 1457 /** 1458 * Clears the value in the given time field. 1459 * @param field the time field to be cleared. 1460 * @stable ICU 2.0 1461 */ 1462 public final void clear(int field) 1463 { 1464 calendar.clear(getJDKField(field)); 1465 } 1466 1467 /** 1468 * Determines if the given time field has a value set. 1469 * @return true if the given time field has a value set; false otherwise. 1470 * @stable ICU 2.0 1471 */ 1472 public final boolean isSet(int field) 1473 { 1474 return calendar.isSet(getJDKField(field)); 1475 } 1476 1477 /** 1478 * Compares this calendar to the specified object. 1479 * The result is <code>true</code> if and only if the argument is 1480 * not <code>null</code> and is a <code>Calendar</code> object that 1481 * represents the same calendar as this object. 1482 * @param obj the object to compare with. 1483 * @return <code>true</code> if the objects are the same; 1484 * <code>false</code> otherwise. 1485 * @stable ICU 2.0 1486 */ 1487 public boolean equals(Object obj) { 1488 try { 1489 return calendar.equals(((Calendar)obj).calendar); 1490 } catch (Exception e) { 1491 return false; 1492 } 1493 } 1494 1495 /** 1496 * {@icu} Returns true if the given Calendar object is equivalent to this 1497 * one. An equivalent Calendar will behave exactly as this one 1498 * does, but it may be set to a different time. By contrast, for 1499 * the equals() method to return true, the other Calendar must 1500 * be set to the same time. 1501 * 1502 * @param other the Calendar to be compared with this Calendar 1503 * @stable ICU 2.4 1504 */ 1505 public boolean isEquivalentTo(Calendar other) { 1506 return calendar.getClass() == other.calendar.getClass() && 1507 calendar.isLenient() == other.calendar.isLenient() && 1508 calendar.getFirstDayOfWeek() == other.calendar.getFirstDayOfWeek() && 1509 calendar.getMinimalDaysInFirstWeek() == other.calendar.getMinimalDaysInFirstWeek() && 1510 calendar.getTimeZone().equals(other.calendar.getTimeZone()); 1511 } 1512 1513 /** 1514 * Returns a hash code for this calendar. 1515 * @return a hash code value for this object. 1516 * @stable ICU 2.0 1517 */ 1518 public int hashCode() { 1519 return calendar.hashCode(); 1520 } 1521 1522 /** 1523 * Returns the difference in milliseconds between the moment this 1524 * calendar is set to and the moment the given calendar or Date object 1525 * is set to. 1526 */ 1527 private long compare(Object that) { 1528 long thatMs; 1529 if (that instanceof Calendar) { 1530 thatMs = ((Calendar)that).getTimeInMillis(); 1531 } else if (that instanceof Date) { 1532 thatMs = ((Date)that).getTime(); 1533 } else { 1534 throw new IllegalArgumentException(that + "is not a Calendar or Date"); 1535 } 1536 return getTimeInMillis() - thatMs; 1537 } 1538 1539 /** 1540 * Compares the time field records. 1541 * Equivalent to comparing result of conversion to UTC. 1542 * @param when the Calendar to be compared with this Calendar. 1543 * @return true if the current time of this Calendar is before 1544 * the time of Calendar when; false otherwise. 1545 * @stable ICU 2.0 1546 */ 1547 public boolean before(Object when) { 1548 return compare(when) < 0; 1549 } 1550 1551 /** 1552 * Compares the time field records. 1553 * Equivalent to comparing result of conversion to UTC. 1554 * @param when the Calendar to be compared with this Calendar. 1555 * @return true if the current time of this Calendar is after 1556 * the time of Calendar when; false otherwise. 1557 * @stable ICU 2.0 1558 */ 1559 public boolean after(Object when) { 1560 return compare(when) > 0; 1561 } 1562 1563 /** 1564 * Returns the maximum value that this field could have, given the 1565 * current date. For example, with the Gregorian date February 3, 1997 1566 * and the {@link #DAY_OF_MONTH DAY_OF_MONTH} field, the actual maximum 1567 * is 28; for February 3, 1996 it is 29. 1568 * 1569 * <p>The actual maximum computation ignores smaller fields and the 1570 * current value of like-sized fields. For example, the actual maximum 1571 * of the DAY_OF_YEAR or MONTH depends only on the year and supra-year 1572 * fields. The actual maximum of the DAY_OF_MONTH depends, in 1573 * addition, on the MONTH field and any other fields at that 1574 * granularity (such as IS_LEAP_MONTH). The 1575 * DAY_OF_WEEK_IN_MONTH field does not depend on the current 1576 * DAY_OF_WEEK; it returns the maximum for any day of week in the 1577 * current month. Likewise for the WEEK_OF_MONTH and WEEK_OF_YEAR 1578 * fields. 1579 * 1580 * @param field the field whose maximum is desired 1581 * @return the maximum of the given field for the current date of this calendar 1582 * @see #getMaximum 1583 * @see #getLeastMaximum 1584 * @stable ICU 2.0 1585 */ 1586 public int getActualMaximum(int field) { 1587 return calendar.getActualMaximum(getJDKField(field)); 1588 } 1589 1590 /** 1591 * Returns the minimum value that this field could have, given the current date. 1592 * For most fields, this is the same as {@link #getMinimum getMinimum} 1593 * and {@link #getGreatestMinimum getGreatestMinimum}. However, some fields, 1594 * especially those related to week number, are more complicated. 1595 * <p> 1596 * For example, assume {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek} 1597 * returns 4 and {@link #getFirstDayOfWeek getFirstDayOfWeek} returns SUNDAY. 1598 * If the first day of the month is Sunday, Monday, Tuesday, or Wednesday 1599 * there will be four or more days in the first week, so it will be week number 1, 1600 * and <code>getActualMinimum(WEEK_OF_MONTH)</code> will return 1. However, 1601 * if the first of the month is a Thursday, Friday, or Saturday, there are 1602 * <em>not</em> four days in that week, so it is week number 0, and 1603 * <code>getActualMinimum(WEEK_OF_MONTH)</code> will return 0. 1604 * <p> 1605 * @param field the field whose actual minimum value is desired. 1606 * @return the minimum of the given field for the current date of this calendar 1607 * 1608 * @see #getMinimum 1609 * @see #getGreatestMinimum 1610 * @stable ICU 2.0 1611 */ 1612 public int getActualMinimum(int field) { 1613 return calendar.getActualMinimum(getJDKField(field)); 1614 } 1615 1616 /** 1617 * Rolls (up/down) a single unit of time on the given field. If the 1618 * field is rolled past its maximum allowable value, it will "wrap" back 1619 * to its minimum and continue rolling. For 1620 * example, to roll the current date up by one day, you can call: 1621 * <p> 1622 * <code>roll({@link #DATE}, true)</code> 1623 * <p> 1624 * When rolling on the {@link #YEAR} field, it will roll the year 1625 * value in the range between 1 and the value returned by calling 1626 * {@link #getMaximum getMaximum}({@link #YEAR}). 1627 * <p> 1628 * When rolling on certain fields, the values of other fields may conflict and 1629 * need to be changed. For example, when rolling the <code>MONTH</code> field 1630 * for the Gregorian date 1/31/96 upward, the <code>DAY_OF_MONTH</code> field 1631 * must be adjusted so that the result is 2/29/96 rather than the invalid 1632 * 2/31/96. 1633 * <p> 1634 * <b>Note:</b> Calling <tt>roll(field, true)</tt> N times is <em>not</em> 1635 * necessarily equivalent to calling <tt>roll(field, N)</tt>. For example, 1636 * imagine that you start with the date Gregorian date January 31, 1995. If you call 1637 * <tt>roll(Calendar.MONTH, 2)</tt>, the result will be March 31, 1995. 1638 * But if you call <tt>roll(Calendar.MONTH, true)</tt>, the result will be 1639 * February 28, 1995. Calling it one more time will give March 28, 1995, which 1640 * is usually not the desired result. 1641 * <p> 1642 * <b>Note:</b> You should always use <tt>roll</tt> and <tt>add</tt> rather 1643 * than attempting to perform arithmetic operations directly on the fields 1644 * of a <tt>Calendar</tt>. It is quite possible for <tt>Calendar</tt> subclasses 1645 * to have fields with non-linear behavior, for example missing months 1646 * or days during non-leap years. The subclasses' <tt>add</tt> and <tt>roll</tt> 1647 * methods will take this into account, while simple arithmetic manipulations 1648 * may give invalid results. 1649 * <p> 1650 * @param field the calendar field to roll. 1651 * 1652 * @param up indicates if the value of the specified time field is to be 1653 * rolled up or rolled down. Use <code>true</code> if rolling up, 1654 * <code>false</code> otherwise. 1655 * 1656 * @exception IllegalArgumentException if the field is invalid or refers 1657 * to a field that cannot be handled by this method. 1658 * @see #roll(int, int) 1659 * @see #add 1660 * @stable ICU 2.0 1661 */ 1662 public final void roll(int field, boolean up) 1663 { 1664 calendar.roll(getJDKField(field), up); 1665 } 1666 1667 /** 1668 * Rolls (up/down) a specified amount time on the given field. For 1669 * example, to roll the current date up by three days, you can call 1670 * <code>roll(Calendar.DATE, 3)</code>. If the 1671 * field is rolled past its maximum allowable value, it will "wrap" back 1672 * to its minimum and continue rolling. 1673 * For example, calling <code>roll(Calendar.DATE, 10)</code> 1674 * on a Gregorian calendar set to 4/25/96 will result in the date 4/5/96. 1675 * <p> 1676 * When rolling on certain fields, the values of other fields may conflict and 1677 * need to be changed. For example, when rolling the {@link #MONTH MONTH} field 1678 * for the Gregorian date 1/31/96 by +1, the {@link #DAY_OF_MONTH DAY_OF_MONTH} field 1679 * must be adjusted so that the result is 2/29/96 rather than the invalid 1680 * 2/31/96. 1681 * <p> 1682 * {@icunote} the ICU implementation of this method is able to roll 1683 * all fields except for {@link #ERA ERA}, {@link #DST_OFFSET DST_OFFSET}, 1684 * and {@link #ZONE_OFFSET ZONE_OFFSET}. Subclasses may, of course, add support for 1685 * additional fields in their overrides of <code>roll</code>. 1686 * <p> 1687 * <b>Note:</b> You should always use <tt>roll</tt> and <tt>add</tt> rather 1688 * than attempting to perform arithmetic operations directly on the fields 1689 * of a <tt>Calendar</tt>. It is quite possible for <tt>Calendar</tt> subclasses 1690 * to have fields with non-linear behavior, for example missing months 1691 * or days during non-leap years. The subclasses' <tt>add</tt> and <tt>roll</tt> 1692 * methods will take this into account, while simple arithmetic manipulations 1693 * may give invalid results. 1694 * <p> 1695 * <b>Subclassing:</b><br> 1696 * This implementation of <code>roll</code> assumes that the behavior of the 1697 * field is continuous between its minimum and maximum, which are found by 1698 * calling {@link #getActualMinimum getActualMinimum} and {@link #getActualMaximum getActualMaximum}. 1699 * For most such fields, simple addition, subtraction, and modulus operations 1700 * are sufficient to perform the roll. For week-related fields, 1701 * the results of {@link #getFirstDayOfWeek getFirstDayOfWeek} and 1702 * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek} are also necessary. 1703 * Subclasses can override these two methods if their values differ from the defaults. 1704 * <p> 1705 * Subclasses that have fields for which the assumption of continuity breaks 1706 * down must overide <code>roll</code> to handle those fields specially. 1707 * For example, in the Hebrew calendar the month "Adar I" 1708 * only occurs in leap years; in other years the calendar jumps from 1709 * Shevat (month #4) to Adar (month #6). The 1710 * {@link HebrewCalendar#roll HebrewCalendar.roll} method takes this into account, 1711 * so that rolling the month of Shevat by one gives the proper result (Adar) in a 1712 * non-leap year. 1713 * <p> 1714 * @param field the calendar field to roll. 1715 * @param amount the amount by which the field should be rolled. 1716 * 1717 * @exception IllegalArgumentException if the field is invalid or refers 1718 * to a field that cannot be handled by this method. 1719 * @see #roll(int, boolean) 1720 * @see #add 1721 * @stable ICU 2.0 1722 */ 1723 public void roll(int field, int amount) { 1724 calendar.roll(getJDKField(field), amount); 1725 } 1726 1727 /** 1728 * Add a signed amount to a specified field, using this calendar's rules. 1729 * For example, to add three days to the current date, you can call 1730 * <code>add(Calendar.DATE, 3)</code>. 1731 * <p> 1732 * When adding to certain fields, the values of other fields may conflict and 1733 * need to be changed. For example, when adding one to the {@link #MONTH MONTH} field 1734 * for the Gregorian date 1/31/96, the {@link #DAY_OF_MONTH DAY_OF_MONTH} field 1735 * must be adjusted so that the result is 2/29/96 rather than the invalid 1736 * 2/31/96. 1737 * <p> 1738 * {@icunote} The ICU implementation of this method is able to add to 1739 * all fields except for {@link #ERA ERA}, {@link #DST_OFFSET DST_OFFSET}, 1740 * and {@link #ZONE_OFFSET ZONE_OFFSET}. Subclasses may, of course, add support for 1741 * additional fields in their overrides of <code>add</code>. 1742 * <p> 1743 * <b>Note:</b> You should always use <tt>roll</tt> and <tt>add</tt> rather 1744 * than attempting to perform arithmetic operations directly on the fields 1745 * of a <tt>Calendar</tt>. It is quite possible for <tt>Calendar</tt> subclasses 1746 * to have fields with non-linear behavior, for example missing months 1747 * or days during non-leap years. The subclasses' <tt>add</tt> and <tt>roll</tt> 1748 * methods will take this into account, while simple arithmetic manipulations 1749 * may give invalid results. 1750 * <p> 1751 * <b>Subclassing:</b><br> 1752 * This implementation of <code>add</code> assumes that the behavior of the 1753 * field is continuous between its minimum and maximum, which are found by 1754 * calling {@link #getActualMinimum getActualMinimum} and 1755 * {@link #getActualMaximum getActualMaximum}. 1756 * For such fields, simple arithmetic operations are sufficient to 1757 * perform the add. 1758 * <p> 1759 * Subclasses that have fields for which this assumption of continuity breaks 1760 * down must overide <code>add</code> to handle those fields specially. 1761 * For example, in the Hebrew calendar the month "Adar I" 1762 * only occurs in leap years; in other years the calendar jumps from 1763 * Shevat (month #4) to Adar (month #6). The 1764 * {@link HebrewCalendar#add HebrewCalendar.add} method takes this into account, 1765 * so that adding one month 1766 * to a date in Shevat gives the proper result (Adar) in a non-leap year. 1767 * <p> 1768 * @param field the time field. 1769 * @param amount the amount to add to the field. 1770 * 1771 * @exception IllegalArgumentException if the field is invalid or refers 1772 * to a field that cannot be handled by this method. 1773 * @see #roll(int, int) 1774 * @stable ICU 2.0 1775 */ 1776 public void add(int field, int amount) { 1777 calendar.add(getJDKField(field), amount); 1778 } 1779 1780 private static String _getDisplayName(Calendar cal) { 1781 String type = cal.getType(); 1782 if (type.equals("japanese")) { 1783 return "Japanese Calendar"; 1784 } else if (type.equals("buddhist")) { 1785 return "Buddhist Calendar"; 1786 } 1787 return "Gregorian Calendar"; 1788 } 1789 1790 /** 1791 * Returns the name of this calendar in the language of the given locale. 1792 * @stable ICU 2.0 1793 */ 1794 public String getDisplayName(Locale loc) { 1795 return _getDisplayName(this); 1796 } 1797 1798 /** 1799 * Returns the name of this calendar in the language of the given locale. 1800 * @stable ICU 3.2 1801 */ 1802 public String getDisplayName(ULocale loc) { 1803 return _getDisplayName(this); 1804 } 1805 1806 /** 1807 * Compares the times (in millis) represented by two 1808 * <code>Calendar</code> objects. 1809 * 1810 * @param that the <code>Calendar</code> to compare to this. 1811 * @return <code>0</code> if the time represented by 1812 * this <code>Calendar</code> is equal to the time represented 1813 * by that <code>Calendar</code>, a value less than 1814 * <code>0</code> if the time represented by this is before 1815 * the time represented by that, and a value greater than 1816 * <code>0</code> if the time represented by this 1817 * is after the time represented by that. 1818 * @throws NullPointerException if that 1819 * <code>Calendar</code> is null. 1820 * @throws IllegalArgumentException if the time of that 1821 * <code>Calendar</code> can't be obtained because of invalid 1822 * calendar values. 1823 * @stable ICU 3.4 1824 */ 1825 public int compareTo(Calendar that) { 1826 return calendar.compareTo(that.calendar); 1827 } 1828 1829 //------------------------------------------------------------------------- 1830 // Interface for creating custon DateFormats for different types of Calendars 1831 //------------------------------------------------------------------------- 1832 1833 /** 1834 * {@icu} Returns a <code>DateFormat</code> appropriate to this calendar. 1835 * Subclasses wishing to specialize this behavior should override 1836 * {@link #handleGetDateFormat}. 1837 * @stable ICU 2.0 1838 */ 1839 public DateFormat getDateTimeFormat(int dateStyle, int timeStyle, Locale loc) { 1840 if (dateStyle != DateFormat.NONE) { 1841 if (timeStyle == DateFormat.NONE) { 1842 return DateFormat.getDateInstance((Calendar)this.clone(), dateStyle, loc); 1843 } else { 1844 return DateFormat.getDateTimeInstance((Calendar)this.clone(), dateStyle, timeStyle, loc); 1845 } 1846 } else if (timeStyle != DateFormat.NONE) { 1847 return DateFormat.getTimeInstance((Calendar)this.clone(), timeStyle, loc); 1848 } else { 1849 return null; 1850 } 1851 } 1852 1853 /** 1854 * {@icu} Returns a <code>DateFormat</code> appropriate to this calendar. 1855 * Subclasses wishing to specialize this behavior should override 1856 * {@link #handleGetDateFormat}. 1857 * @stable ICU 3.2 1858 */ 1859 public DateFormat getDateTimeFormat(int dateStyle, int timeStyle, ULocale loc) { 1860 return getDateTimeFormat(dateStyle, timeStyle, loc.toLocale()); 1861 } 1862 1863 //------------------------------------------------------------------------- 1864 // Constants 1865 //------------------------------------------------------------------------- 1866 1867 /** 1868 * {@icu} Returns the difference between the given time and the time this 1869 * calendar object is set to. If this calendar is set 1870 * <em>before</em> the given time, the returned value will be 1871 * positive. If this calendar is set <em>after</em> the given 1872 * time, the returned value will be negative. The 1873 * <code>field</code> parameter specifies the units of the return 1874 * value. For example, if <code>fieldDifference(when, 1875 * Calendar.MONTH)</code> returns 3, then this calendar is set to 1876 * 3 months before <code>when</code>, and possibly some additional 1877 * time less than one month. 1878 * 1879 * <p>As a side effect of this call, this calendar is advanced 1880 * toward <code>when</code> by the given amount. That is, calling 1881 * this method has the side effect of calling <code>add(field, 1882 * n)</code>, where <code>n</code> is the return value. 1883 * 1884 * <p>Usage: To use this method, call it first with the largest 1885 * field of interest, then with progressively smaller fields. For 1886 * example: 1887 * 1888 * <pre> 1889 * int y = cal.fieldDifference(when, Calendar.YEAR); 1890 * int m = cal.fieldDifference(when, Calendar.MONTH); 1891 * int d = cal.fieldDifference(when, Calendar.DATE);</pre> 1892 * 1893 * computes the difference between <code>cal</code> and 1894 * <code>when</code> in years, months, and days. 1895 * 1896 * <p>Note: <code>fieldDifference()</code> is 1897 * <em>asymmetrical</em>. That is, in the following code: 1898 * 1899 * <pre> 1900 * cal.setTime(date1); 1901 * int m1 = cal.fieldDifference(date2, Calendar.MONTH); 1902 * int d1 = cal.fieldDifference(date2, Calendar.DATE); 1903 * cal.setTime(date2); 1904 * int m2 = cal.fieldDifference(date1, Calendar.MONTH); 1905 * int d2 = cal.fieldDifference(date1, Calendar.DATE);</pre> 1906 * 1907 * one might expect that <code>m1 == -m2 && d1 == -d2</code>. 1908 * However, this is not generally the case, because of 1909 * irregularities in the underlying calendar system (e.g., the 1910 * Gregorian calendar has a varying number of days per month). 1911 * 1912 * @param when the date to compare this calendar's time to 1913 * @param field the field in which to compute the result 1914 * @return the difference, either positive or negative, between 1915 * this calendar's time and <code>when</code>, in terms of 1916 * <code>field</code>. 1917 * @stable ICU 2.0 1918 */ 1919 public int fieldDifference(Date when, int field) { 1920 int min = 0; 1921 long startMs = getTimeInMillis(); 1922 long targetMs = when.getTime(); 1923 // Always add from the start millis. This accomodates 1924 // operations like adding years from February 29, 2000 up to 1925 // February 29, 2004. If 1, 1, 1, 1 is added to the year 1926 // field, the DOM gets pinned to 28 and stays there, giving an 1927 // incorrect DOM difference of 1. We have to add 1, reset, 2, 1928 // reset, 3, reset, 4. 1929 if (startMs < targetMs) { 1930 int max = 1; 1931 // Find a value that is too large 1932 for (;;) { 1933 setTimeInMillis(startMs); 1934 add(field, max); 1935 long ms = getTimeInMillis(); 1936 if (ms == targetMs) { 1937 return max; 1938 } else if (ms > targetMs) { 1939 break; 1940 } else { 1941 max <<= 1; 1942 if (max < 0) { 1943 // Field difference too large to fit into int 1944 throw new RuntimeException(); 1945 } 1946 } 1947 } 1948 // Do a binary search 1949 while ((max - min) > 1) { 1950 int t = (min + max) / 2; 1951 setTimeInMillis(startMs); 1952 add(field, t); 1953 long ms = getTimeInMillis(); 1954 if (ms == targetMs) { 1955 return t; 1956 } else if (ms > targetMs) { 1957 max = t; 1958 } else { 1959 min = t; 1960 } 1961 } 1962 } else if (startMs > targetMs) { 1963 //Eclipse stated the following is "dead code" 1964 /*if (false) { 1965 // This works, and makes the code smaller, but costs 1966 // an extra object creation and an extra couple cycles 1967 // of calendar computation. 1968 setTimeInMillis(targetMs); 1969 min = -fieldDifference(new Date(startMs), field); 1970 }*/ 1971 int max = -1; 1972 // Find a value that is too small 1973 for (;;) { 1974 setTimeInMillis(startMs); 1975 add(field, max); 1976 long ms = getTimeInMillis(); 1977 if (ms == targetMs) { 1978 return max; 1979 } else if (ms < targetMs) { 1980 break; 1981 } else { 1982 max <<= 1; 1983 if (max == 0) { 1984 // Field difference too large to fit into int 1985 throw new RuntimeException(); 1986 } 1987 } 1988 } 1989 // Do a binary search 1990 while ((min - max) > 1) { 1991 int t = (min + max) / 2; 1992 setTimeInMillis(startMs); 1993 add(field, t); 1994 long ms = getTimeInMillis(); 1995 if (ms == targetMs) { 1996 return t; 1997 } else if (ms < targetMs) { 1998 max = t; 1999 } else { 2000 min = t; 2001 } 2002 } 2003 } 2004 // Set calendar to end point 2005 setTimeInMillis(startMs); 2006 add(field, min); 2007 return min; 2008 } 2009 2010 /** 2011 * Sets the time zone with the given time zone value. 2012 * @param value the given time zone. 2013 * @stable ICU 2.0 2014 */ 2015 public void setTimeZone(TimeZone value) 2016 { 2017 calendar.setTimeZone(value.timeZone); 2018 } 2019 2020 /** 2021 * Returns the time zone. 2022 * @return the time zone object associated with this calendar. 2023 * @stable ICU 2.0 2024 */ 2025 public TimeZone getTimeZone() 2026 { 2027 return new TimeZone(calendar.getTimeZone()); 2028 } 2029 2030 /** 2031 * Specify whether or not date/time interpretation is to be lenient. With 2032 * lenient interpretation, a date such as "February 942, 1996" will be 2033 * treated as being equivalent to the 941st day after February 1, 1996. 2034 * With strict interpretation, such dates will cause an exception to be 2035 * thrown. 2036 * 2037 * @see DateFormat#setLenient 2038 * @stable ICU 2.0 2039 */ 2040 public void setLenient(boolean lenient) 2041 { 2042 calendar.setLenient(lenient); 2043 } 2044 2045 /** 2046 * Tell whether date/time interpretation is to be lenient. 2047 * @stable ICU 2.0 2048 */ 2049 public boolean isLenient() 2050 { 2051 return calendar.isLenient(); 2052 } 2053 2054// /** 2055// * {@icu}Sets the behavior for handling wall time repeating multiple times 2056// * at negative time zone offset transitions. For example, 1:30 AM on 2057// * November 6, 2011 in US Eastern time (Ameirca/New_York) occurs twice; 2058// * 1:30 AM EDT, then 1:30 AM EST one hour later. When <code>WALLTIME_FIRST</code> 2059// * is used, the wall time 1:30AM in this example will be interpreted as 1:30 AM EDT 2060// * (first occurrence). When <code>WALLTIME_LAST</code> is used, it will be 2061// * interpreted as 1:30 AM EST (last occurrence). The default value is 2062// * <code>WALLTIME_LAST</code>. 2063// * 2064// * @param option the behavior for handling repeating wall time, either 2065// * <code>WALLTIME_FIRST</code> or <code>WALLTIME_LAST</code>. 2066// * @throws IllegalArgumentException when <code>option</code> is neither 2067// * <code>WALLTIME_FIRST</code> nor <code>WALLTIME_LAST</code>. 2068// * 2069// * @see #getRepeatedWallTimeOption() 2070// * @see #WALLTIME_FIRST 2071// * @see #WALLTIME_LAST 2072// * 2073// * @draft ICU 49 2074// * @provisional This API might change or be removed in a future release. 2075// */ 2076// public void setRepeatedWallTimeOption(int option) { 2077// if (option != WALLTIME_LAST) { 2078// throw new UnsupportedOperationException("The option not supported by com.ibm.icu.base"); 2079// } 2080// } 2081 2082 /** 2083 * {@icu}Gets the behavior for handling wall time repeating multiple times 2084 * at negative time zone offset transitions. 2085 * 2086 * @return the behavior for handling repeating wall time, either 2087 * <code>WALLTIME_FIRST</code> or <code>WALLTIME_LAST</code>. 2088 * 2089 * @see #setRepeatedWallTimeOption(int) 2090 * @see #WALLTIME_FIRST 2091 * @see #WALLTIME_LAST 2092 * 2093 * @draft ICU 49 2094 * @provisional This API might change or be removed in a future release. 2095 */ 2096 public int getRepeatedWallTimeOption() { 2097 return WALLTIME_LAST; 2098 } 2099 2100// /** 2101// * {@icu}Sets the behavior for handling skipped wall time at positive time zone offset 2102// * transitions. For example, 2:30 AM on March 13, 2011 in US Eastern time (America/New_York) 2103// * does not exist because the wall time jump from 1:59 AM EST to 3:00 AM EDT. When 2104// * <code>WALLTIME_FIRST</code> is used, 2:30 AM is interpreted as 30 minutes before 3:00 AM 2105// * EDT, therefore, it will be resolved as 1:30 AM EST. When <code>WALLTIME_LAST</code> 2106// * is used, 2:30 AM is interpreted as 31 minutes after 1:59 AM EST, therefore, it will be 2107// * resolved as 3:30 AM EDT. When <code>WALLTIME_NEXT_VALID</code> is used, 2:30 AM will 2108// * be resolved as next valid wall time, that is 3:00 AM EDT. The default value is 2109// * <code>WALLTIME_LAST</code>. 2110// * <p> 2111// * <b>Note:</b>This option is effective only when this calendar is {@link #isLenient() lenient}. 2112// * When the calendar is strict, such non-existing wall time will cause an exception. 2113// * 2114// * @param option the behavior for handling skipped wall time at positive time zone 2115// * offset transitions, one of <code>WALLTIME_FIRST</code>, <code>WALLTIME_LAST</code> and 2116// * <code>WALLTIME_NEXT_VALID</code>. 2117// * @throws IllegalArgumentException when <code>option</code> is not any of 2118// * <code>WALLTIME_FIRST</code>, <code>WALLTIME_LAST</code> and <code>WALLTIME_NEXT_VALID</code>. 2119// * 2120// * @see #getSkippedWallTimeOption() 2121// * @see #WALLTIME_FIRST 2122// * @see #WALLTIME_LAST 2123// * @see #WALLTIME_NEXT_VALID 2124// * 2125// * @draft ICU 49 2126// * @provisional This API might change or be removed in a future release. 2127// */ 2128// public void setSkippedWallTimeOption(int option) { 2129// if (option != WALLTIME_LAST) { 2130// throw new UnsupportedOperationException("The option not supported by com.ibm.icu.base"); 2131// } 2132// } 2133 2134 /** 2135 * {@icu}Gets the behavior for handling skipped wall time at positive time zone offset 2136 * transitions. 2137 * 2138 * @return the behavior for handling skipped wall time, one of 2139 * <code>WALLTIME_FIRST</code>, <code>WALLTIME_LAST</code> and <code>WALLTIME_NEXT_VALID</code>. 2140 * 2141 * @see #setSkippedWallTimeOption(int) 2142 * @see #WALLTIME_FIRST 2143 * @see #WALLTIME_LAST 2144 * @see #WALLTIME_NEXT_VALID 2145 * 2146 * @draft ICU 49 2147 * @provisional This API might change or be removed in a future release. 2148 */ 2149 public int getSkippedWallTimeOption() { 2150 return WALLTIME_LAST; 2151 } 2152 2153 /** 2154 * Sets what the first day of the week is; e.g., Sunday in US, 2155 * Monday in France. 2156 * @param value the given first day of the week. 2157 * @stable ICU 2.0 2158 */ 2159 public void setFirstDayOfWeek(int value) 2160 { 2161 calendar.setFirstDayOfWeek(value); 2162 } 2163 2164 /** 2165 * Returns what the first day of the week is; e.g., Sunday in US, 2166 * Monday in France. 2167 * @return the first day of the week. 2168 * @stable ICU 2.0 2169 */ 2170 public int getFirstDayOfWeek() 2171 { 2172 return calendar.getFirstDayOfWeek(); 2173 } 2174 2175 /** 2176 * Sets what the minimal days required in the first week of the year are. 2177 * For example, if the first week is defined as one that contains the first 2178 * day of the first month of a year, call the method with value 1. If it 2179 * must be a full week, use value 7. 2180 * @param value the given minimal days required in the first week 2181 * of the year. 2182 * @stable ICU 2.0 2183 */ 2184 public void setMinimalDaysInFirstWeek(int value) 2185 { 2186 calendar.setMinimalDaysInFirstWeek(value); 2187 } 2188 2189 /** 2190 * Returns what the minimal days required in the first week of the year are; 2191 * e.g., if the first week is defined as one that contains the first day 2192 * of the first month of a year, getMinimalDaysInFirstWeek returns 1. If 2193 * the minimal days required must be a full week, getMinimalDaysInFirstWeek 2194 * returns 7. 2195 * @return the minimal days required in the first week of the year. 2196 * @stable ICU 2.0 2197 */ 2198 public int getMinimalDaysInFirstWeek() 2199 { 2200 return calendar.getMinimalDaysInFirstWeek(); 2201 } 2202 2203 /** 2204 * Returns the minimum value for the given time field. 2205 * e.g., for Gregorian DAY_OF_MONTH, 1. 2206 * @param field the given time field. 2207 * @return the minimum value for the given time field. 2208 * @stable ICU 2.0 2209 */ 2210 public final int getMinimum(int field) { 2211 return calendar.getMinimum(getJDKField(field)); 2212 } 2213 2214 /** 2215 * Returns the maximum value for the given time field. 2216 * e.g. for Gregorian DAY_OF_MONTH, 31. 2217 * @param field the given time field. 2218 * @return the maximum value for the given time field. 2219 * @stable ICU 2.0 2220 */ 2221 public final int getMaximum(int field) { 2222 return calendar.getMaximum(getJDKField(field)); 2223 } 2224 2225 /** 2226 * Returns the highest minimum value for the given field if varies. 2227 * Otherwise same as getMinimum(). For Gregorian, no difference. 2228 * @param field the given time field. 2229 * @return the highest minimum value for the given time field. 2230 * @stable ICU 2.0 2231 */ 2232 public final int getGreatestMinimum(int field) { 2233 return calendar.getGreatestMinimum(getJDKField(field)); 2234 } 2235 2236 /** 2237 * Returns the lowest maximum value for the given field if varies. 2238 * Otherwise same as getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28. 2239 * @param field the given time field. 2240 * @return the lowest maximum value for the given time field. 2241 * @stable ICU 2.0 2242 */ 2243 public final int getLeastMaximum(int field) { 2244 return calendar.getLeastMaximum(getJDKField(field)); 2245 } 2246 2247 //------------------------------------------------------------------------- 2248 // Weekend support -- determining which days of the week are the weekend 2249 // in a given locale 2250 //------------------------------------------------------------------------- 2251 2252 /** 2253 * {@icu} Returns whether the given day of the week is a weekday, a 2254 * weekend day, or a day that transitions from one to the other, 2255 * in this calendar system. If a transition occurs at midnight, 2256 * then the days before and after the transition will have the 2257 * type WEEKDAY or WEEKEND. If a transition occurs at a time 2258 * other than midnight, then the day of the transition will have 2259 * the type WEEKEND_ONSET or WEEKEND_CEASE. In this case, the 2260 * method getWeekendTransition() will return the point of 2261 * transition. 2262 * @param dayOfWeek either SUNDAY, MONDAY, TUESDAY, WEDNESDAY, 2263 * THURSDAY, FRIDAY, or SATURDAY 2264 * @return either WEEKDAY, WEEKEND, WEEKEND_ONSET, or 2265 * WEEKEND_CEASE 2266 * @exception IllegalArgumentException if dayOfWeek is not 2267 * between SUNDAY and SATURDAY, inclusive 2268 * @see #WEEKDAY 2269 * @see #WEEKEND 2270 * @see #WEEKEND_ONSET 2271 * @see #WEEKEND_CEASE 2272 * @see #getWeekendTransition 2273 * @see #isWeekend(Date) 2274 * @see #isWeekend() 2275 * @stable ICU 2.0 2276 */ 2277 public int getDayOfWeekType(int dayOfWeek) { 2278 // weekend always full saturday and sunday with com.ibm.icu.base 2279 if (dayOfWeek < SUNDAY || dayOfWeek > 7) { 2280 throw new IllegalArgumentException("illegal day of week: " + dayOfWeek); 2281 } else if (dayOfWeek == SATURDAY || dayOfWeek == SUNDAY) { 2282 return WEEKEND; 2283 } 2284 return WEEKDAY;} 2285 2286// /** 2287// * {@icu} Returns the time during the day at which the weekend begins or end in this 2288// * calendar system. If getDayOfWeekType(dayOfWeek) == WEEKEND_ONSET return the time 2289// * at which the weekend begins. If getDayOfWeekType(dayOfWeek) == WEEKEND_CEASE 2290// * return the time at which the weekend ends. If getDayOfWeekType(dayOfWeek) has some 2291// * other value, then throw an exception. 2292// * @param dayOfWeek either SUNDAY, MONDAY, TUESDAY, WEDNESDAY, 2293// * THURSDAY, FRIDAY, or SATURDAY 2294// * @return the milliseconds after midnight at which the 2295// * weekend begins or ends 2296// * @exception IllegalArgumentException if dayOfWeek is not 2297// * WEEKEND_ONSET or WEEKEND_CEASE 2298// * @see #getDayOfWeekType 2299// * @see #isWeekend(Date) 2300// * @see #isWeekend() 2301// * @stable ICU 2.0 2302// */ 2303// public int getWeekendTransition(int dayOfWeek) { 2304// throw new UnsupportedOperationException("Method not supported by com.ibm.icu.base"); 2305// } 2306 2307 /** 2308 * {@icu} Returns true if the given date and time is in the weekend in this calendar 2309 * system. Equivalent to calling setTime() followed by isWeekend(). Note: This 2310 * method changes the time this calendar is set to. 2311 * @param date the date and time 2312 * @return true if the given date and time is part of the 2313 * weekend 2314 * @see #getDayOfWeekType 2315 * @see #getWeekendTransition 2316 * @see #isWeekend() 2317 * @stable ICU 2.0 2318 */ 2319 public boolean isWeekend(Date date) { 2320 calendar.setTime(date); 2321 return isWeekend(); 2322 } 2323 2324 /** 2325 * {@icu} Returns true if this Calendar's current date and time is in the weekend in 2326 * this calendar system. 2327 * @return true if the given date and time is part of the 2328 * weekend 2329 * @see #getDayOfWeekType 2330 * @see #getWeekendTransition 2331 * @see #isWeekend(Date) 2332 * @stable ICU 2.0 2333 */ 2334 public boolean isWeekend() { 2335 // weekend always full saturday and sunday with com.ibm.icu.base 2336 int dow = calendar.get(Calendar.DAY_OF_WEEK); 2337 if (dow == SATURDAY || dow == SUNDAY) { 2338 return true; 2339 } 2340 return false; 2341 } 2342 2343 //------------------------------------------------------------------------- 2344 // End of weekend support 2345 //------------------------------------------------------------------------- 2346 2347 /** 2348 * Overrides Cloneable 2349 * @stable ICU 2.0 2350 */ 2351 public Object clone() 2352 { 2353 return new Calendar((java.util.Calendar)calendar.clone()); 2354 } 2355 2356 /** 2357 * Returns a string representation of this calendar. This method 2358 * is intended to be used only for debugging purposes, and the 2359 * format of the returned string may vary between implementations. 2360 * The returned string may be empty but may not be <code>null</code>. 2361 * 2362 * @return a string representation of this calendar. 2363 * @stable ICU 2.0 2364 */ 2365 public String toString() { 2366 return calendar.toString(); 2367 } 2368 2369 /** 2370 * {@icu} Returns the number of fields defined by this calendar. Valid field 2371 * arguments to <code>set()</code> and <code>get()</code> are 2372 * <code>0..getFieldCount()-1</code>. 2373 * @stable ICU 2.0 2374 */ 2375 public final int getFieldCount() { 2376 return FIELD_COUNT; 2377 } 2378 2379 private static final int FIELD_COUNT = /* IS_LEAP_MONTH */ DST_OFFSET + 1; 2380 2381 /** 2382 * {@icu} Returns the current Calendar type. Note, in 3.0 this function will return 2383 * 'gregorian' in Calendar to emulate legacy behavior 2384 * @return type of calendar (gregorian, etc) 2385 * @stable ICU 3.8 2386 */ 2387 public String getType() { 2388 // JDK supports Gregorian, Japanese and Buddhist 2389 String name = calendar.getClass().getSimpleName().toLowerCase(Locale.US); 2390 if (name.contains("japanese")) { 2391 return "japanese"; 2392 } else if (name.contains("buddhist")) { 2393 return "buddhist"; 2394 } 2395 return "gregorian"; 2396 } 2397 2398 // -------- BEGIN ULocale boilerplate -------- 2399 2400// /** 2401// * {@icu} Returns the locale that was used to create this object, or null. 2402// * This may may differ from the locale requested at the time of 2403// * this object's creation. For example, if an object is created 2404// * for locale <tt>en_US_CALIFORNIA</tt>, the actual data may be 2405// * drawn from <tt>en</tt> (the <i>actual</i> locale), and 2406// * <tt>en_US</tt> may be the most specific locale that exists (the 2407// * <i>valid</i> locale). 2408// * 2409// * <p>Note: This method will be implemented in ICU 3.0; ICU 2.8 2410// * contains a partial preview implementation. The * <i>actual</i> 2411// * locale is returned correctly, but the <i>valid</i> locale is 2412// * not, in most cases. 2413// * @param type type of information requested, either {@link 2414// * com.ibm.icu.util.ULocale#VALID_LOCALE} or {@link 2415// * com.ibm.icu.util.ULocale#ACTUAL_LOCALE}. 2416// * @return the information specified by <i>type</i>, or null if 2417// * this object was not constructed from locale data. 2418// * @see com.ibm.icu.util.ULocale 2419// * @see com.ibm.icu.util.ULocale#VALID_LOCALE 2420// * @see com.ibm.icu.util.ULocale#ACTUAL_LOCALE 2421// * @draft ICU 2.8 (retain) 2422// * @provisional This API might change or be removed in a future release. 2423// */ 2424// public final ULocale getLocale(ULocale.Type type) { 2425// throw new UnsupportedOperationException("Method not supported by com.ibm.icu.base"); 2426// } 2427 2428 // -------- END ULocale boilerplate -------- 2429 2430 2431 private static int getJDKField(int icuField) { 2432 switch (icuField) { 2433 case ERA: 2434 return java.util.Calendar.ERA; 2435 case YEAR: 2436 return java.util.Calendar.YEAR; 2437 case MONTH: 2438 return java.util.Calendar.MONTH; 2439 case WEEK_OF_YEAR: 2440 return java.util.Calendar.WEEK_OF_YEAR; 2441 case WEEK_OF_MONTH: 2442 return java.util.Calendar.WEEK_OF_MONTH; 2443 case DATE: 2444 return java.util.Calendar.DATE; 2445// case DAY_OF_MONTH: 2446// return java.util.Calendar.DAY_OF_MONTH; 2447 case DAY_OF_YEAR: 2448 return java.util.Calendar.DAY_OF_YEAR; 2449 case DAY_OF_WEEK: 2450 return java.util.Calendar.DAY_OF_WEEK; 2451 case DAY_OF_WEEK_IN_MONTH: 2452 return java.util.Calendar.DAY_OF_WEEK_IN_MONTH; 2453 case AM_PM: 2454 return java.util.Calendar.AM_PM; 2455 case HOUR: 2456 return java.util.Calendar.HOUR; 2457 case HOUR_OF_DAY: 2458 return java.util.Calendar.HOUR_OF_DAY; 2459 case MINUTE: 2460 return java.util.Calendar.MINUTE; 2461 case SECOND: 2462 return java.util.Calendar.SECOND; 2463 case MILLISECOND: 2464 return java.util.Calendar.MILLISECOND; 2465 case ZONE_OFFSET: 2466 return java.util.Calendar.ZONE_OFFSET; 2467 case DST_OFFSET: 2468 return java.util.Calendar.DST_OFFSET; 2469 2470// case YEAR_WOY: 2471// case DOW_LOCAL: 2472// case EXTENDED_YEAR: 2473// case JULIAN_DAY: 2474// case MILLISECONDS_IN_DAY: 2475// // Unmappable 2476// throw new UnsupportedOperationException("Calendar field type not supported by com.ibm.icu.base"); 2477 default: 2478 // Illegal 2479 throw new ArrayIndexOutOfBoundsException("Specified calendar field is out of range"); 2480 } 2481 } 2482} 2483