jars/icu4j-4_8_1_1/main/classes/core/src/com/ibm/icu/util/GregorianCalendar.java

   1 /*
   2  * Copyright (C) 1996-2011, International Business Machines
   3  * Corporation and others.  All Rights Reserved.
   4  */
   5
   6 package com.ibm.icu.util;
   7
   8 import java.util.Date;
   9 import java.util.Locale;
  10
  11 import com.ibm.icu.util.ULocale.Category;
  12
  13 /**
  14  * {@icuenhanced java.util.GregorianCalendar}.{@icu _usage_}
  15  *
  16  * <p><code>GregorianCalendar</code> is a concrete subclass of
  17  * {@link Calendar}
  18  * and provides the standard calendar used by most of the world.
  19  *
  20  * <p>The standard (Gregorian) calendar has 2 eras, BC and AD.
  21  *
  22  * <p>This implementation handles a single discontinuity, which corresponds by
  23  * default to the date the Gregorian calendar was instituted (October 15, 1582
  24  * in some countries, later in others).  The cutover date may be changed by the
  25  * caller by calling <code>setGregorianChange()</code>.
  26  *
  27  * <p>Historically, in those countries which adopted the Gregorian calendar first,
  28  * October 4, 1582 was thus followed by October 15, 1582. This calendar models
  29  * this correctly.  Before the Gregorian cutover, <code>GregorianCalendar</code>
  30  * implements the Julian calendar.  The only difference between the Gregorian
  31  * and the Julian calendar is the leap year rule. The Julian calendar specifies
  32  * leap years every four years, whereas the Gregorian calendar omits century
  33  * years which are not divisible by 400.
  34  *
  35  * <p><code>GregorianCalendar</code> implements <em>proleptic</em> Gregorian and
  36  * Julian calendars. That is, dates are computed by extrapolating the current
  37  * rules indefinitely far backward and forward in time. As a result,
  38  * <code>GregorianCalendar</code> may be used for all years to generate
  39  * meaningful and consistent results. However, dates obtained using
  40  * <code>GregorianCalendar</code> are historically accurate only from March 1, 4
  41  * AD onward, when modern Julian calendar rules were adopted.  Before this date,
  42  * leap year rules were applied irregularly, and before 45 BC the Julian
  43  * calendar did not even exist.
  44  *
  45  * <p>Prior to the institution of the Gregorian calendar, New Year's Day was
  46  * March 25. To avoid confusion, this calendar always uses January 1. A manual
  47  * adjustment may be made if desired for dates that are prior to the Gregorian
  48  * changeover and which fall between January 1 and March 24.
  49  *
  50  * <p>Values calculated for the <code>WEEK_OF_YEAR</code> field range from 1 to
  51  * 53.  Week 1 for a year is the earliest seven day period starting on
  52  * <code>getFirstDayOfWeek()</code> that contains at least
  53  * <code>getMinimalDaysInFirstWeek()</code> days from that year.  It thus
  54  * depends on the values of <code>getMinimalDaysInFirstWeek()</code>,
  55  * <code>getFirstDayOfWeek()</code>, and the day of the week of January 1.
  56  * Weeks between week 1 of one year and week 1 of the following year are
  57  * numbered sequentially from 2 to 52 or 53 (as needed).
  58
  59  * <p>For example, January 1, 1998 was a Thursday.  If
  60  * <code>getFirstDayOfWeek()</code> is <code>MONDAY</code> and
  61  * <code>getMinimalDaysInFirstWeek()</code> is 4 (these are the values
  62  * reflecting ISO 8601 and many national standards), then week 1 of 1998 starts
  63  * on December 29, 1997, and ends on January 4, 1998.  If, however,
  64  * <code>getFirstDayOfWeek()</code> is <code>SUNDAY</code>, then week 1 of 1998
  65  * starts on January 4, 1998, and ends on January 10, 1998; the first three days
  66  * of 1998 then are part of week 53 of 1997.
  67  *
  68  * <p>Values calculated for the <code>WEEK_OF_MONTH</code> field range from 0 or
  69  * 1 to 4 or 5.  Week 1 of a month (the days with <code>WEEK_OF_MONTH =
  70  * 1</code>) is the earliest set of at least
  71  * <code>getMinimalDaysInFirstWeek()</code> contiguous days in that month,
  72  * ending on the day before <code>getFirstDayOfWeek()</code>.  Unlike
  73  * week 1 of a year, week 1 of a month may be shorter than 7 days, need
  74  * not start on <code>getFirstDayOfWeek()</code>, and will not include days of
  75  * the previous month.  Days of a month before week 1 have a
  76  * <code>WEEK_OF_MONTH</code> of 0.
  77  *
  78  * <p>For example, if <code>getFirstDayOfWeek()</code> is <code>SUNDAY</code>
  79  * and <code>getMinimalDaysInFirstWeek()</code> is 4, then the first week of
  80  * January 1998 is Sunday, January 4 through Saturday, January 10.  These days
  81  * have a <code>WEEK_OF_MONTH</code> of 1.  Thursday, January 1 through
  82  * Saturday, January 3 have a <code>WEEK_OF_MONTH</code> of 0.  If
  83  * <code>getMinimalDaysInFirstWeek()</code> is changed to 3, then January 1
  84  * through January 3 have a <code>WEEK_OF_MONTH</code> of 1.
  85  *
  86  * <p>
  87  * <strong>Example:</strong>
  88  * <blockquote>
  89  * <pre>
  90  * // get the supported ids for GMT-08:00 (Pacific Standard Time)
  91  * String[] ids = TimeZone.getAvailableIDs(-8 * 60 * 60 * 1000);
  92  * // if no ids were returned, something is wrong. get out.
  93  * if (ids.length == 0)
  94  *     System.exit(0);
  95  *
  96  *  // begin output
  97  * System.out.println("Current Time");
  98  *
  99  * // create a Pacific Standard Time time zone
 100  * SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, ids[0]);
 101  *
 102  * // set up rules for daylight savings time
 103  * pdt.setStartRule(Calendar.MARCH, 2, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
 104  * pdt.setEndRule(Calendar.NOVEMBER, 1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
 105  *
 106  * // create a GregorianCalendar with the Pacific Daylight time zone
 107  * // and the current date and time
 108  * Calendar calendar = new GregorianCalendar(pdt);
 109  * Date trialTime = new Date();
 110  * calendar.setTime(trialTime);
 111  *
 112  * // print out a bunch of interesting things
 113  * System.out.println("ERA: " + calendar.get(Calendar.ERA));
 114  * System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
 115  * System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
 116  * System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
 117  * System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
 118  * System.out.println("DATE: " + calendar.get(Calendar.DATE));
 119  * System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
 120  * System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
 121  * System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
 122  * System.out.println("DAY_OF_WEEK_IN_MONTH: "
 123  *                    + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
 124  * System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
 125  * System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
 126  * System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
 127  * System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
 128  * System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
 129  * System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
 130  * System.out.println("ZONE_OFFSET: "
 131  *                    + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000)));
 132  * System.out.println("DST_OFFSET: "
 133  *                    + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000)));
 134
 135  * System.out.println("Current Time, with hour reset to 3");
 136  * calendar.clear(Calendar.HOUR_OF_DAY); // so doesn't override
 137  * calendar.set(Calendar.HOUR, 3);
 138  * System.out.println("ERA: " + calendar.get(Calendar.ERA));
 139  * System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
 140  * System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
 141  * System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
 142  * System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
 143  * System.out.println("DATE: " + calendar.get(Calendar.DATE));
 144  * System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
 145  * System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
 146  * System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
 147  * System.out.println("DAY_OF_WEEK_IN_MONTH: "
 148  *                    + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
 149  * System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
 150  * System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
 151  * System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
 152  * System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
 153  * System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
 154  * System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
 155  * System.out.println("ZONE_OFFSET: "
 156  *        + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000))); // in hours
 157  * System.out.println("DST_OFFSET: "
 158  *        + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000))); // in hours</pre>
 159  * </blockquote>
 160  * <p>
 161  * GregorianCalendar usually should be instantiated using
 162  * {@link com.ibm.icu.util.Calendar#getInstance(ULocale)} passing in a <code>ULocale</code>
 163  * with the tag <code>"@calendar=gregorian"</code>.</p>
 164
 165  * @see          Calendar
 166  * @see          TimeZone
 167  * @author David Goldsmith, Mark Davis, Chen-Lieh Huang, Alan Liu
 168  * @stable ICU 2.0
 169  */
 170 public class GregorianCalendar extends Calendar {
 171     // jdk1.4.2 serialver
 172     private static final long serialVersionUID = 9199388694351062137L;
 173
 174     /*
 175      * Implementation Notes
 176      *
 177      * The Julian day number, as used here, is a modified number which has its
 178      * onset at midnight, rather than noon.
 179      *
 180      * The epoch is the number of days or milliseconds from some defined
 181      * starting point. The epoch for java.util.Date is used here; that is,
 182      * milliseconds from January 1, 1970 (Gregorian), midnight UTC.  Other
 183      * epochs which are used are January 1, year 1 (Gregorian), which is day 1
 184      * of the Gregorian calendar, and December 30, year 0 (Gregorian), which is
 185      * day 1 of the Julian calendar.
 186      *
 187      * We implement the proleptic Julian and Gregorian calendars.  This means we
 188      * implement the modern definition of the calendar even though the
 189      * historical usage differs.  For example, if the Gregorian change is set
 190      * to new Date(Long.MIN_VALUE), we have a pure Gregorian calendar which
 191      * labels dates preceding the invention of the Gregorian calendar in 1582 as
 192      * if the calendar existed then.
 193      *
 194      * Likewise, with the Julian calendar, we assume a consistent 4-year leap
 195      * rule, even though the historical pattern of leap years is irregular,
 196      * being every 3 years from 45 BC through 9 BC, then every 4 years from 8 AD
 197      * onwards, with no leap years in-between.  Thus date computations and
 198      * functions such as isLeapYear() are not intended to be historically
 199      * accurate.
 200      *
 201      * Given that milliseconds are a long, day numbers such as Julian day
 202      * numbers, Gregorian or Julian calendar days, or epoch days, are also
 203      * longs. Years can fit into an int.
 204      */
 205
 206 //////////////////
 207 // Class Variables
 208 //////////////////
 209
 210     /**
 211      * Value of the <code>ERA</code> field indicating
 212      * the period before the common era (before Christ), also known as BCE.
 213      * The sequence of years at the transition from <code>BC</code> to <code>AD</code> is
 214      * ..., 2 BC, 1 BC, 1 AD, 2 AD,...
 215      * @see Calendar#ERA
 216      * @stable ICU 2.0
 217      */
 218     public static final int BC = 0;
 219
 220     /**
 221      * Value of the <code>ERA</code> field indicating
 222      * the common era (Anno Domini), also known as CE.
 223      * The sequence of years at the transition from <code>BC</code> to <code>AD</code> is
 224      * ..., 2 BC, 1 BC, 1 AD, 2 AD,...
 225      * @see Calendar#ERA
 226      * @stable ICU 2.0
 227      */
 228     public static final int AD = 1;
 229
 230     private static final int EPOCH_YEAR = 1970;
 231
 232     private static final int[][] MONTH_COUNT = {
 233         //len len2   st  st2
 234         {  31,  31,   0,   0 }, // Jan
 235         {  28,  29,  31,  31 }, // Feb
 236         {  31,  31,  59,  60 }, // Mar
 237         {  30,  30,  90,  91 }, // Apr
 238         {  31,  31, 120, 121 }, // May
 239         {  30,  30, 151, 152 }, // Jun
 240         {  31,  31, 181, 182 }, // Jul
 241         {  31,  31, 212, 213 }, // Aug
 242         {  30,  30, 243, 244 }, // Sep
 243         {  31,  31, 273, 274 }, // Oct
 244         {  30,  30, 304, 305 }, // Nov
 245         {  31,  31, 334, 335 }  // Dec
 246         // len  length of month
 247         // len2 length of month in a leap year
 248         // st   days in year before start of month
 249         // st2  days in year before month in leap year
 250     };
 251
 252     /**
 253      * Old year limits were least max 292269054, max 292278994.
 254      */
 255     private static final int LIMITS[][] = {
 256         // Minimum  Greatest    Least  Maximum
 257         //           Minimum  Maximum
 258         {        0,        0,       1,       1 }, // ERA
 259         {        1,        1, 5828963, 5838270 }, // YEAR
 260         {        0,        0,      11,      11 }, // MONTH
 261         {        1,        1,      52,      53 }, // WEEK_OF_YEAR
 262         {/*                                  */}, // WEEK_OF_MONTH
 263         {        1,        1,      28,      31 }, // DAY_OF_MONTH
 264         {        1,        1,     365,     366 }, // DAY_OF_YEAR
 265         {/*                                  */}, // DAY_OF_WEEK
 266         {       -1,       -1,       4,       5 }, // DAY_OF_WEEK_IN_MONTH
 267         {/*                                  */}, // AM_PM
 268         {/*                                  */}, // HOUR
 269         {/*                                  */}, // HOUR_OF_DAY
 270         {/*                                  */}, // MINUTE
 271         {/*                                  */}, // SECOND
 272         {/*                                  */}, // MILLISECOND
 273         {/*                                  */}, // ZONE_OFFSET
 274         {/*                                  */}, // DST_OFFSET
 275         { -5838270, -5838270, 5828964, 5838271 }, // YEAR_WOY
 276         {/*                                  */}, // DOW_LOCAL
 277         { -5838269, -5838269, 5828963, 5838270 }, // EXTENDED_YEAR
 278         {/*                                  */}, // JULIAN_DAY
 279         {/*                                  */}, // MILLISECONDS_IN_DAY
 280     };
 281
 282     /**
 283      * @stable ICU 2.0
 284      */
 285     protected int handleGetLimit(int field, int limitType) {
 286         return LIMITS[field][limitType];
 287     }
 288
 289 /////////////////////
 290 // Instance Variables
 291 /////////////////////
 292
 293     /**
 294      * The point at which the Gregorian calendar rules are used, measured in
 295      * milliseconds from the standard epoch.  Default is October 15, 1582
 296      * (Gregorian) 00:00:00 UTC or -12219292800000L.  For this value, October 4,
 297      * 1582 (Julian) is followed by October 15, 1582 (Gregorian).  This
 298      * corresponds to Julian day number 2299161.
 299      * @serial
 300      */
 301     private long gregorianCutover = -12219292800000L;
 302
 303     /**
 304      * Julian day number of the Gregorian cutover.
 305      */
 306     private transient int cutoverJulianDay = 2299161;
 307
 308     /**
 309      * The year of the gregorianCutover, with 0 representing
 310      * 1 BC, -1 representing 2 BC, etc.
 311      */
 312     private transient int gregorianCutoverYear = 1582;
 313
 314     /**
 315      * Used by handleComputeJulianDay() and handleComputeMonthStart().
 316      * @stable ICU 2.0
 317      */
 318     transient protected boolean isGregorian;
 319
 320     /**
 321      * Used by handleComputeJulianDay() and handleComputeMonthStart().
 322      * @stable ICU 2.0
 323      */
 324     transient protected boolean invertGregorian;
 325
 326 ///////////////
 327 // Constructors
 328 ///////////////
 329
 330     /**
 331      * Constructs a default GregorianCalendar using the current time
 332      * in the default time zone with the default <code>FORMAT</code> locale.
 333      * @see Category#FORMAT
 334      * @stable ICU 2.0
 335      */
 336     public GregorianCalendar() {
 337         this(TimeZone.getDefault(), ULocale.getDefault(Category.FORMAT));
 338     }
 339
 340     /**
 341      * Constructs a GregorianCalendar based on the current time
 342      * in the given time zone with the default <code>FORMAT</code> locale.
 343      * @param zone the given time zone.
 344      * @see Category#FORMAT
 345      * @stable ICU 2.0
 346      */
 347     public GregorianCalendar(TimeZone zone) {
 348         this(zone, ULocale.getDefault(Category.FORMAT));
 349     }
 350
 351     /**
 352      * Constructs a GregorianCalendar based on the current time
 353      * in the default time zone with the given locale.
 354      * @param aLocale the given locale.
 355      * @stable ICU 2.0
 356      */
 357     public GregorianCalendar(Locale aLocale) {
 358         this(TimeZone.getDefault(), aLocale);
 359     }
 360
 361     /**
 362      * {@icu} Constructs a GregorianCalendar based on the current time
 363      * in the default time zone with the given locale.
 364      * @param locale the given ulocale.
 365      * @stable ICU 3.2
 366      */
 367     public GregorianCalendar(ULocale locale) {
 368         this(TimeZone.getDefault(), locale);
 369     }
 370
 371     /**
 372      * {@icu} Constructs a GregorianCalendar based on the current time
 373      * in the given time zone with the given locale.
 374      * @param zone the given time zone.
 375      * @param aLocale the given locale.
 376      * @stable ICU 2.0
 377      */
 378     public GregorianCalendar(TimeZone zone, Locale aLocale) {
 379         super(zone, aLocale);
 380         setTimeInMillis(System.currentTimeMillis());
 381     }
 382
 383     /**
 384      * Constructs a GregorianCalendar based on the current time
 385      * in the given time zone with the given locale.
 386      * @param zone the given time zone.
 387      * @param locale the given ulocale.
 388      * @stable ICU 3.2
 389      */
 390     public GregorianCalendar(TimeZone zone, ULocale locale) {
 391         super(zone, locale);
 392         setTimeInMillis(System.currentTimeMillis());
 393     }
 394
 395     /**
 396      * Constructs a GregorianCalendar with the given date set
 397      * in the default time zone with the default <code>FORMAT</code> locale.
 398      * @param year the value used to set the YEAR time field in the calendar.
 399      * @param month the value used to set the MONTH time field in the calendar.
 400      * Month value is 0-based. e.g., 0 for January.
 401      * @param date the value used to set the DATE time field in the calendar.
 402      * @see Category#FORMAT
 403      * @stable ICU 2.0
 404      */
 405     public GregorianCalendar(int year, int month, int date) {
 406         super(TimeZone.getDefault(), ULocale.getDefault(Category.FORMAT));
 407         set(ERA, AD);
 408         set(YEAR, year);
 409         set(MONTH, month);
 410         set(DATE, date);
 411     }
 412
 413     /**
 414      * Constructs a GregorianCalendar with the given date
 415      * and time set for the default time zone with the default <code>FORMAT</code> locale.
 416      * @param year the value used to set the YEAR time field in the calendar.
 417      * @param month the value used to set the MONTH time field in the calendar.
 418      * Month value is 0-based. e.g., 0 for January.
 419      * @param date the value used to set the DATE time field in the calendar.
 420      * @param hour the value used to set the HOUR_OF_DAY time field
 421      * in the calendar.
 422      * @param minute the value used to set the MINUTE time field
 423      * in the calendar.
 424      * @see Category#FORMAT
 425      * @stable ICU 2.0
 426      */
 427     public GregorianCalendar(int year, int month, int date, int hour,
 428                              int minute) {
 429         super(TimeZone.getDefault(), ULocale.getDefault(Category.FORMAT));
 430         set(ERA, AD);
 431         set(YEAR, year);
 432         set(MONTH, month);
 433         set(DATE, date);
 434         set(HOUR_OF_DAY, hour);
 435         set(MINUTE, minute);
 436     }
 437
 438     /**
 439      * Constructs a GregorianCalendar with the given date
 440      * and time set for the default time zone with the default <code>FORMAT</code> locale.
 441      * @param year the value used to set the YEAR time field in the calendar.
 442      * @param month the value used to set the MONTH time field in the calendar.
 443      * Month value is 0-based. e.g., 0 for January.
 444      * @param date the value used to set the DATE time field in the calendar.
 445      * @param hour the value used to set the HOUR_OF_DAY time field
 446      * in the calendar.
 447      * @param minute the value used to set the MINUTE time field
 448      * in the calendar.
 449      * @param second the value used to set the SECOND time field
 450      * in the calendar.
 451      * @see Category#FORMAT
 452      * @stable ICU 2.0
 453      */
 454     public GregorianCalendar(int year, int month, int date, int hour,
 455                              int minute, int second) {
 456         super(TimeZone.getDefault(), ULocale.getDefault(Category.FORMAT));
 457         set(ERA, AD);
 458         set(YEAR, year);
 459         set(MONTH, month);
 460         set(DATE, date);
 461         set(HOUR_OF_DAY, hour);
 462         set(MINUTE, minute);
 463         set(SECOND, second);
 464     }
 465
 466 /////////////////
 467 // Public methods
 468 /////////////////
 469
 470     /**
 471      * Sets the GregorianCalendar change date. This is the point when the switch
 472      * from Julian dates to Gregorian dates occurred. Default is October 15,
 473      * 1582. Previous to this, dates will be in the Julian calendar.
 474      * <p>
 475      * To obtain a pure Julian calendar, set the change date to
 476      * <code>Date(Long.MAX_VALUE)</code>.  To obtain a pure Gregorian calendar,
 477      * set the change date to <code>Date(Long.MIN_VALUE)</code>.
 478      *
 479      * @param date the given Gregorian cutover date.
 480      * @stable ICU 2.0
 481      */
 482     public void setGregorianChange(Date date) {
 483         gregorianCutover = date.getTime();
 484
 485         // If the cutover has an extreme value, then create a pure
 486         // Gregorian or pure Julian calendar by giving the cutover year and
 487         // JD extreme values.
 488         if (gregorianCutover <= MIN_MILLIS) {
 489             gregorianCutoverYear = cutoverJulianDay = Integer.MIN_VALUE;
 490         } else if (gregorianCutover >= MAX_MILLIS) {
 491             gregorianCutoverYear = cutoverJulianDay = Integer.MAX_VALUE;
 492         } else {
 493             // Precompute two internal variables which we use to do the actual
 494             // cutover computations.  These are the Julian day of the cutover
 495             // and the cutover year.
 496             cutoverJulianDay = (int) floorDivide(gregorianCutover, ONE_DAY);
 497
 498             // Convert cutover millis to extended year
 499             GregorianCalendar cal = new GregorianCalendar(getTimeZone());
 500             cal.setTime(date);
 501             gregorianCutoverYear = cal.get(EXTENDED_YEAR);
 502         }
 503     }
 504
 505     /**
 506      * Gets the Gregorian Calendar change date.  This is the point when the
 507      * switch from Julian dates to Gregorian dates occurred. Default is
 508      * October 15, 1582. Previous to this, dates will be in the Julian
 509      * calendar.
 510      * @return the Gregorian cutover date for this calendar.
 511      * @stable ICU 2.0
 512      */
 513     public final Date getGregorianChange() {
 514         return new Date(gregorianCutover);
 515     }
 516
 517     /**
 518      * Determines if the given year is a leap year. Returns true if the
 519      * given year is a leap year.
 520      * @param year the given year.
 521      * @return true if the given year is a leap year; false otherwise.
 522      * @stable ICU 2.0
 523      */
 524     public boolean isLeapYear(int year) {
 525         return year >= gregorianCutoverYear ?
 526             ((year%4 == 0) && ((year%100 != 0) || (year%400 == 0))) : // Gregorian
 527             (year%4 == 0); // Julian
 528     }
 529
 530     /**
 531      * Returns true if the given Calendar object is equivalent to this
 532      * one.  Calendar override.
 533      *
 534      * @param other the Calendar to be compared with this Calendar
 535      * @stable ICU 2.4
 536      */
 537     public boolean isEquivalentTo(Calendar other) {
 538         return super.isEquivalentTo(other) &&
 539             gregorianCutover == ((GregorianCalendar)other).gregorianCutover;
 540     }
 541
 542     /**
 543      * Override hashCode.
 544      * Generates the hash code for the GregorianCalendar object
 545      * @stable ICU 2.0
 546      */
 547     public int hashCode() {
 548         return super.hashCode() ^ (int)gregorianCutover;
 549     }
 550
 551     /**
 552      * Roll a field by a signed amount.
 553      * @stable ICU 2.0
 554      */
 555     public void roll(int field, int amount) {
 556
 557         switch (field) {
 558         case WEEK_OF_YEAR:
 559             {
 560                 // Unlike WEEK_OF_MONTH, WEEK_OF_YEAR never shifts the day of the
 561                 // week.  Also, rolling the week of the year can have seemingly
 562                 // strange effects simply because the year of the week of year
 563                 // may be different from the calendar year.  For example, the
 564                 // date Dec 28, 1997 is the first day of week 1 of 1998 (if
 565                 // weeks start on Sunday and the minimal days in first week is
 566                 // <= 3).
 567                 int woy = get(WEEK_OF_YEAR);
 568                 // Get the ISO year, which matches the week of year.  This
 569                 // may be one year before or after the calendar year.
 570                 int isoYear = get(YEAR_WOY);
 571                 int isoDoy = internalGet(DAY_OF_YEAR);
 572                 if (internalGet(MONTH) == Calendar.JANUARY) {
 573                     if (woy >= 52) {
 574                         isoDoy += handleGetYearLength(isoYear);
 575                     }
 576                 } else {
 577                     if (woy == 1) {
 578                         isoDoy -= handleGetYearLength(isoYear - 1);
 579                     }
 580                 }
 581                 woy += amount;
 582                 // Do fast checks to avoid unnecessary computation:
 583                 if (woy < 1 || woy > 52) {
 584                     // Determine the last week of the ISO year.
 585                     // We do this using the standard formula we use
 586                     // everywhere in this file.  If we can see that the
 587                     // days at the end of the year are going to fall into
 588                     // week 1 of the next year, we drop the last week by
 589                     // subtracting 7 from the last day of the year.
 590                     int lastDoy = handleGetYearLength(isoYear);
 591                     int lastRelDow = (lastDoy - isoDoy + internalGet(DAY_OF_WEEK) -
 592                                       getFirstDayOfWeek()) % 7;
 593                     if (lastRelDow < 0) lastRelDow += 7;
 594                     if ((6 - lastRelDow) >= getMinimalDaysInFirstWeek()) lastDoy -= 7;
 595                     int lastWoy = weekNumber(lastDoy, lastRelDow + 1);
 596                     woy = ((woy + lastWoy - 1) % lastWoy) + 1;
 597                 }
 598                 set(WEEK_OF_YEAR, woy);
 599                 set(YEAR, isoYear); // Why not YEAR_WOY? - Alan 11/6/00
 600                 return;
 601             }
 602
 603         default:
 604             super.roll(field, amount);
 605             return;
 606         }
 607     }
 608
 609     /**
 610      * Return the minimum value that this field could have, given the current date.
 611      * For the Gregorian calendar, this is the same as getMinimum() and getGreatestMinimum().
 612      * @stable ICU 2.0
 613      */
 614     public int getActualMinimum(int field) {
 615         return getMinimum(field);
 616     }
 617
 618     /**
 619      * Return the maximum value that this field could have, given the current date.
 620      * For example, with the date "Feb 3, 1997" and the DAY_OF_MONTH field, the actual
 621      * maximum would be 28; for "Feb 3, 1996" it s 29.  Similarly for a Hebrew calendar,
 622      * for some years the actual maximum for MONTH is 12, and for others 13.
 623      * @stable ICU 2.0
 624      */
 625     public int getActualMaximum(int field) {
 626         /* It is a known limitation that the code here (and in getActualMinimum)
 627          * won't behave properly at the extreme limits of GregorianCalendar's
 628          * representable range (except for the code that handles the YEAR
 629          * field).  That's because the ends of the representable range are at
 630          * odd spots in the year.  For calendars with the default Gregorian
 631          * cutover, these limits are Sun Dec 02 16:47:04 GMT 292269055 BC to Sun
 632          * Aug 17 07:12:55 GMT 292278994 AD, somewhat different for non-GMT
 633          * zones.  As a result, if the calendar is set to Aug 1 292278994 AD,
 634          * the actual maximum of DAY_OF_MONTH is 17, not 30.  If the date is Mar
 635          * 31 in that year, the actual maximum month might be Jul, whereas is
 636          * the date is Mar 15, the actual maximum might be Aug -- depending on
 637          * the precise semantics that are desired.  Similar considerations
 638          * affect all fields.  Nonetheless, this effect is sufficiently arcane
 639          * that we permit it, rather than complicating the code to handle such
 640          * intricacies. - liu 8/20/98
 641
 642          * UPDATE: No longer true, since we have pulled in the limit values on
 643          * the year. - Liu 11/6/00 */
 644
 645         switch (field) {
 646
 647         case YEAR:
 648             /* The year computation is no different, in principle, from the
 649              * others, however, the range of possible maxima is large.  In
 650              * addition, the way we know we've exceeded the range is different.
 651              * For these reasons, we use the special case code below to handle
 652              * this field.
 653              *
 654              * The actual maxima for YEAR depend on the type of calendar:
 655              *
 656              *     Gregorian = May 17, 292275056 BC - Aug 17, 292278994 AD
 657              *     Julian    = Dec  2, 292269055 BC - Jan  3, 292272993 AD
 658              *     Hybrid    = Dec  2, 292269055 BC - Aug 17, 292278994 AD
 659              *
 660              * We know we've exceeded the maximum when either the month, date,
 661              * time, or era changes in response to setting the year.  We don't
 662              * check for month, date, and time here because the year and era are
 663              * sufficient to detect an invalid year setting.  NOTE: If code is
 664              * added to check the month and date in the future for some reason,
 665              * Feb 29 must be allowed to shift to Mar 1 when setting the year.
 666              */
 667             {
 668                 Calendar cal = (Calendar) clone();
 669                 cal.setLenient(true);
 670
 671                 int era = cal.get(ERA);
 672                 Date d = cal.getTime();
 673
 674                 /* Perform a binary search, with the invariant that lowGood is a
 675                  * valid year, and highBad is an out of range year.
 676                  */
 677                 int lowGood = LIMITS[YEAR][1];
 678                 int highBad = LIMITS[YEAR][2]+1;
 679                 while ((lowGood + 1) < highBad) {
 680                     int y = (lowGood + highBad) / 2;
 681                     cal.set(YEAR, y);
 682                     if (cal.get(YEAR) == y && cal.get(ERA) == era) {
 683                         lowGood = y;
 684                     } else {
 685                         highBad = y;
 686                         cal.setTime(d); // Restore original fields
 687                     }
 688                 }
 689
 690                 return lowGood;
 691             }
 692
 693         default:
 694             return super.getActualMaximum(field);
 695         }
 696     }
 697
 698 //////////////////////
 699 // Proposed public API
 700 //////////////////////
 701
 702     /**
 703      * Return true if the current time for this Calendar is in Daylignt
 704      * Savings Time.
 705      */
 706     boolean inDaylightTime() {
 707         if (!getTimeZone().useDaylightTime()) return false;
 708         complete(); // Force update of DST_OFFSET field
 709         return internalGet(DST_OFFSET) != 0;
 710     }
 711
 712
 713 /////////////////////
 714 // Calendar framework
 715 /////////////////////
 716
 717     /**
 718      * @stable ICU 2.0
 719      */
 720     protected int handleGetMonthLength(int extendedYear, int month) {
 721         // If the month is out of range, adjust it into range, and
 722         // modify the extended year value accordingly.
 723         if (month < 0 || month > 11) {
 724             int[] rem = new int[1];
 725             extendedYear += floorDivide(month, 12, rem);
 726             month = rem[0];
 727         }
 728
 729         return MONTH_COUNT[month][isLeapYear(extendedYear)?1:0];
 730     }
 731
 732     /**
 733      * @stable ICU 2.0
 734      */
 735     protected int handleGetYearLength(int eyear) {
 736         return isLeapYear(eyear) ? 366 : 365;
 737     }
 738
 739 /////////////////////////////
 740 // Time => Fields computation
 741 /////////////////////////////
 742
 743     /**
 744      * Override Calendar to compute several fields specific to the hybrid
 745      * Gregorian-Julian calendar system.  These are:
 746      *
 747      * <ul><li>ERA
 748      * <li>YEAR
 749      * <li>MONTH
 750      * <li>DAY_OF_MONTH
 751      * <li>DAY_OF_YEAR
 752      * <li>EXTENDED_YEAR</ul>
 753      * @stable ICU 2.0
 754      */
 755     protected void handleComputeFields(int julianDay) {
 756         int eyear, month, dayOfMonth, dayOfYear;
 757
 758         if (julianDay >= cutoverJulianDay) {
 759             month = getGregorianMonth();
 760             dayOfMonth = getGregorianDayOfMonth();
 761             dayOfYear = getGregorianDayOfYear();
 762             eyear = getGregorianYear();
 763         } else {
 764             // The Julian epoch day (not the same as Julian Day)
 765             // is zero on Saturday December 30, 0 (Gregorian).
 766             long julianEpochDay = julianDay - (JAN_1_1_JULIAN_DAY - 2);
 767             eyear = (int) floorDivide(4*julianEpochDay + 1464, 1461);
 768
 769             // Compute the Julian calendar day number for January 1, eyear
 770             long january1 = 365*(eyear-1) + floorDivide(eyear-1, 4);
 771             dayOfYear = (int)(julianEpochDay - january1); // 0-based
 772
 773             // Julian leap years occurred historically every 4 years starting
 774             // with 8 AD.  Before 8 AD the spacing is irregular; every 3 years
 775             // from 45 BC to 9 BC, and then none until 8 AD.  However, we don't
 776             // implement this historical detail; instead, we implement the
 777             // computatinally cleaner proleptic calendar, which assumes
 778             // consistent 4-year cycles throughout time.
 779             boolean isLeap = ((eyear&0x3) == 0); // equiv. to (eyear%4 == 0)
 780
 781             // Common Julian/Gregorian calculation
 782             int correction = 0;
 783             int march1 = isLeap ? 60 : 59; // zero-based DOY for March 1
 784             if (dayOfYear >= march1) {
 785                 correction = isLeap ? 1 : 2;
 786             }
 787             month = (12 * (dayOfYear + correction) + 6) / 367; // zero-based month
 788             dayOfMonth = dayOfYear - MONTH_COUNT[month][isLeap?3:2] + 1; // one-based DOM
 789             ++dayOfYear;
 790         }
 791         internalSet(MONTH, month);
 792         internalSet(DAY_OF_MONTH, dayOfMonth);
 793         internalSet(DAY_OF_YEAR, dayOfYear);
 794         internalSet(EXTENDED_YEAR, eyear);
 795         int era = AD;
 796         if (eyear < 1) {
 797             era = BC;
 798             eyear = 1 - eyear;
 799         }
 800         internalSet(ERA, era);
 801         internalSet(YEAR, eyear);
 802     }
 803
 804 /////////////////////////////
 805 // Fields => Time computation
 806 /////////////////////////////
 807
 808     /**
 809      * @stable ICU 2.0
 810      */
 811     protected int handleGetExtendedYear() {
 812         int year;
 813         if (newerField(EXTENDED_YEAR, YEAR) == EXTENDED_YEAR) {
 814             year = internalGet(EXTENDED_YEAR, EPOCH_YEAR);
 815         } else {
 816             // The year defaults to the epoch start, the era to AD
 817             int era = internalGet(ERA, AD);
 818             if (era == BC) {
 819                 year = 1 - internalGet(YEAR, 1); // Convert to extended year
 820             } else {
 821                 year = internalGet(YEAR, EPOCH_YEAR);
 822             }
 823         }
 824         return year;
 825     }
 826
 827     /**
 828      * @stable ICU 2.0
 829      */
 830     protected int handleComputeJulianDay(int bestField) {
 831
 832         invertGregorian = false;
 833
 834         int jd = super.handleComputeJulianDay(bestField);
 835
 836         // The following check handles portions of the cutover year BEFORE the
 837         // cutover itself happens.
 838         if (isGregorian != (jd >= cutoverJulianDay)) {
 839             invertGregorian = true;
 840             jd = super.handleComputeJulianDay(bestField);
 841         }
 842
 843         return jd;
 844     }
 845
 846     /**
 847      * Return JD of start of given month/year
 848      * @stable ICU 2.0
 849      */
 850     protected int handleComputeMonthStart(int eyear, int month, boolean useMonth) {
 851
 852         // If the month is out of range, adjust it into range, and
 853         // modify the extended year value accordingly.
 854         if (month < 0 || month > 11) {
 855             int[] rem = new int[1];
 856             eyear += floorDivide(month, 12, rem);
 857             month = rem[0];
 858         }
 859
 860         boolean isLeap = eyear%4 == 0;
 861         int y = eyear - 1;
 862         int julianDay = 365*y + floorDivide(y, 4) + (JAN_1_1_JULIAN_DAY - 3);
 863
 864         isGregorian = (eyear >= gregorianCutoverYear);
 865         if (invertGregorian) {
 866             isGregorian = !isGregorian;
 867         }
 868         if (isGregorian) {
 869             isLeap = isLeap && ((eyear%100 != 0) || (eyear%400 == 0));
 870             // Add 2 because Gregorian calendar starts 2 days after
 871             // Julian calendar
 872             julianDay += floorDivide(y, 400) - floorDivide(y, 100) + 2;
 873         }
 874
 875         // At this point julianDay indicates the day BEFORE the first
 876         // day of January 1, <eyear> of either the Julian or Gregorian
 877         // calendar.
 878
 879         if (month != 0) {
 880             julianDay += MONTH_COUNT[month][isLeap?3:2];
 881         }
 882
 883         return julianDay;
 884     }
 885
 886     /**
 887      * Return the current Calendar type.
 888      * @return type of calendar
 889      * @stable ICU 3.8
 890      */
 891     public String getType() {
 892         return "gregorian";
 893     }
 894
 895     /*
 896     private static CalendarFactory factory;
 897     public static CalendarFactory factory() {
 898         if (factory == null) {
 899             factory = new CalendarFactory() {
 900                 public Calendar create(TimeZone tz, ULocale loc) {
 901                     return new GregorianCalendar(tz, loc);
 902                 }
 903
 904                 public String factoryName() {
 905                     return "Gregorian";
 906                 }
 907             };
 908         }
 909         return factory;
 910     }
 911     */
 912 }