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