bigdate.java

java base64

/* BigDate
  copyright (c) 1997-2008 Roedy Green, Canadian Mind Products Freeware
  that may be copied and used freely for any purpose but military.
  If you make more than casual use, please sent a registration fee of $10
  either US or Canadian to:
  BIGDATE REGISTRATIONS
  Roedy Green
  Canadian Mind Products
  #101 - 2536 Wark Street
  Victoria, BC Canada
  V8T 4G8
  roedy g at mindprod dotcom
  http://mindprod.com

  "More that casual use" would include using BigDate in a commercial product or
  using it in a project deployed on more than 5 computers. The registration
  requirement is not onerous. You need register only one copy.

  Make sure you have the latest version from http://mindprod.com.

  version history
  1.0 1997-05-03 - initial release.

  1.1 1997-05-04 - add setOrdinal, setYYYY, setMM, setDD.

  1.2 1997-05-05 - add public static toOrdinal.

  1.3 1997-05-06 - add getTimeStamp, warn about lead 0 meaning octal

  1.4 1997-05-06 - add getDayOfWeek, getDDD, rename NULL_ORDINAL,
  NULL_TIMESTAMP

  1.5 1997-05-11 - rename getJulian to getOrdinal to avoid confusion with
  old Julian vs new Gregorian calendars. Redo 1582 code with named
  constants to facilitate changing the switchover point between the old and
  new calendars.

  1.6 1997-05-12 - shorten the names of constants.

  1.7 1997-06-21 - cache last result to avoid recalculation.

  1.8 1997-07-09 - add null constructor

  1.9 1997-12-17 - add documentation on how to convert to the British
  calendar. Modify code to make it simple to switch to the British scheme.
  Allow for fact British 100 and 400 Leap year rules kicked in at different
  times. Add today method. Calculate constants based on others rather than
  specifying individually to make change easier. expose default methods to
  extenders of this class, making them protected. Fix bug. Null constructor
  was not creating a properly initialised NULL date. There was confusion
  then between a null date and a zero date = 1997/01/01.

  2.0 1998-01-26 Peter V. Gadjokov" <[e-mail]> pointed out a
  bug in isValid. The dd was not tested properly to make sure it was <= 31
  The bug did not cause incorrect execution, just slowed it, since a finer
  check was done later.

  2.1 1998-01-30 implement Cloneable, Serializable, equals, compareTo,
  hashCode add Javadoc comments. isBritish compile time switch.
  alphabetise. private, protected status changed.

  2.2 1998-06-18 add getISOWeekNumber, getISODayOfWeek.

  2.3 1998-11-19 new mailing address and phone.

  2.4 1998-11-27 more examples on how to use BigDate in TestDate.
  warnings about today and time zones. today is now two methods localToday
  and UTCToday. added age method to compute age in years, months and days.
  exposed daysInMonth as public. made most methods final for speed. Since
  you have source, you can always unfinal them if you need to.

  2.5 1998-11-28 added test harness to prove age routine is working
  correctly. Note about ISO 8601:1988 international standard for dates is
  YYYY-MM-DD. Corrected major bugs in age. Now works for mixed BC/AD. Works
  if as of date is not today. More comments in age routine on how it works.
  Now accepts two BigDates instead of two ordinals. Added more examples of
  how to use BigDate.

  2.6 1998-11-30 Added more examples to TestDate.

  2.7 1999-08-23 getTimeStamp renamed to getUTCTimeStamp add
  getLocalTimeStamp, getUTCDate, getLocalDate today(TimeZone)

  2.8 1999-09-04add daysInMonth to take the year instead of a
  boolean. That way you can usually avoid the isLeap calculation.

  2.9 1999-09-08add sample isHolidayimplementationn to TestDate. add
  dayOfWeek and isoDayOfWeek static versions.

  3.0 1999-09-08add nthXXXDay and ordinalOfnthXXXDay.

  3.1 1999-09-15 add constructor and access for Astronomer's
  Proleptic Julian day numbers. to be consistent with the US Naval
  observatory, BC leap years are now 1 5 9, not 4, 8, 12.

  3.2 1999-09-20 add getWeekNumber to complement getISOWeekNumber.

  3.3 1999-09-22 correct toString to display very old or very future
  dates correctly

  3.4 1999-10-18 speed up leap year calcs by replacing yyyy % 4 with
  yyyy & 3

  3.5 1999-11-23 give Timezone.getOffset a 1-based Sunday. Avoid
  IllegalArgumentException in some JVMs. Place warnings about Sunday base
  incompatibilities.

  3.6 1999-11-24 add getCalendarDayOfWeek and calendarDayOfWeek

  3.7 2001-01-26 properly implement Comparable with Object instead of
  BigDate

  3.8 2001-03-17 add code to TestDate to calculate how many sleeps until
  Christmas.

  3.9 2002-03-16 make toString non-final so you can override it.

  4.0 2002-04-10 addDays convenience method toString now displays ISO
  format yyyy-mm-dd TestDate examples changed to use addDays.

  4.3 2003-05-18 Default is now British rather than Pope Gregory's rules
  for when the missing days were dealt with.

  4.4 2003-08-05 getDowMMDDYY -- alternative to toString, mainly to show
  how to roll your own methods.

  4.5 2003-09-12 Added constructor that takes a Date and TimeZone. added
  setDateAtTime.

  4.6 2004-05-15 getSeason

  4.7 2005-07-15 isValid( yyyy-mm-dd), new package, com.mindprod.common11,
  getCopyright

  4.8 2005-08-28 added constructor that takes a String
  argument.

  4.9 2006-03-04 convert to Intellij. Make code more robust by moving
  initialisation to a static block so field reordering will not screw it up.

  5.0 2007-10-15 new methods, nearestXXXDay, dayOfWeek, calendarDayOfWeek.
  Improved documentation.

  5.1 2008-02-01 add named constants for the months and days of the week.

  5.2 2008-03-20 add dayAbbr, dayName, monthAbbr, monthName
 */
package com.mindprod.common11;

import java.io.IOException;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.io.Serializable;
import java.util.Date;
import java.util.TimeZone;

/**
 * Convert Gregorian YYYY MM DD back and forth to ordinal days since 1970 Jan 1, Thursday (sometimes called Julian or
 * datestamp form). BigDate objects are not designed for <b>storing</b> dates in a database, just for conversion. Long
 * term storage should store the ordinal either as an int, or possibly as a short. The BigDate constructor stores the
 * date both in ordinal and Gregorian forms internally. If you store one, it creates the other.
 * <p/>
 * The standard Sun Date won't handle dates prior to 1970 among other problems. BigDate handles dates 999,999 BC Jan 1
 * to 999,999 AD Dec 31, 0 = 1970 Jan 1.
 * <p/>
 * Are the following quirks of the calendar considered in this code?
 * <p/>
 * 1900  is not a leap year (mod 100): <b>yes</b>.
 * <p/>
 * 2000 is a leap year (mod 400): <b>yes</b>.
 * <p/>
 * The 10 missing days in 1582 October.: <b>yes</b> (Pope Gregory's correction) 1582 Oct 5 to 1582 Oct 14 never
 * happened.
 * <p/>
 * Britain and its territories (including the USA and Canada) adopted the Gregorian correction in 1752: <b>Yes</b>.  By
 * then, 11 days had to be dropped. 1752 September 3 to 1752 September 13 never happened. However, you can modify
 * constants in BigDate to use the British calendar. Such a change only affects dates prior to 1753 since BigDate
 * calendar is based on Jan 1, 1970. toOrdinal with the Gregorian and British scheme will give the same number for
 * recent dates. <b>You must recompile BigDate with the <b>isBritish</b> boolean changed to true.</b>. It was used by
 * Britain and its colonies which later became the USA and Canada.  However Nova Scotia used Pope Gregory's calendar.
 * see http://mindprod.com/jgloss/missingdays.html PLEASE CONFIGURE isBritish AND RECOMPILE BIGDATE IF YOU WISH TO USE
 * THE BRITISH CALENDAR.
 * <p/>
 * missing year 0 between 1 BC and 1 AD. <b>yes</b>.
 * <p/>
 * in Roman times leap years occurred at irregular intervals, Considered inauspicious, they were avoided during war.
 * <b>no</b>. Instead we presume leap years every 4 years even back to 999,999BC.
 * <p/>
 * leap seconds: <b>no</b>
 * <p/>
 * Normally all you need is one BigDate object that you use for all interconversions with set(ordinal), set(yyy,mm,dd)
 * and getOrdinal(), getYYYY(), getMM(), getDD().
 * <p/>
 * java.util.Date has some odd habits, using 101 to represent the year 2001, and 11 to represent December. BigDate is
 * more conventional. You use 2001 to represent the year 2001 and 12 to represent December.
 * <p/>
 * BigDate implements proleptic Gregorian and Julian calendars. That is, dates are computed by extrapolating the current
 * rules indefinitely far backward and forward in time. As a result, BigDate may be used for all years to generate
 * meaningful and consistent results. However, dates obtained using BigDate are historically accurate only from March 1,
 * 4 AD onward, when modern Julian calendar rules were adopted. Before this date, leap year rules were applied
 * irregularly, and before 45 BC the Julian calendar did not even exist. Prior to the institution of the Gregorian
 * calendar, New Year's Day was March 25. To avoid confusion, this calendar always uses January 1.
 * <p/>
 * TODO Future enhancements: - handle time, and timezones, interconversion with GregorianCalendar dates.
 *
 * @author Roedy Green, Canadian Mind Products
 * @version 5.0 2007-10-15 new methods, nearestXXXDay, dayOfWeek, calendarDayOfWeek.
 *          <p/>
 * @noinspection WeakerAccess,UnusedDeclaration
 */
public final class BigDate implements Cloneable, Serializable, Comparable
    {
    // ------------------------------ FIELDS ------------------------------

    /**
     * PLEASE CONFIGURE isBritish BEFORE COMPILING. Mysterious missing days in the calendar. Pope Gregory: 1582 Oct 4
     * Thursday, was followed immediately by 1582 Oct 15 Friday dropping 10 days. British: 1752 Sep 2 Wednesday was
     * followed immediately by 1752 Sep 14 Thursday dropping 12 days. Constant: true if you want the British calender,
     * false if Pope Gregory's. You must recompile for it to have effect. For Britain, the USA and Canada it should be
     * true.
     */
    public static final boolean isBritish = true;

    /**
     * Constant: adjustment to make ordinal 0 come out on 1970 Jan 01 for AD date calculations. This number was computed
     * by making an estimate, seeing what value toOrdinal gave for 1970/01/01 and then adjusting this constant so that
     * 1970/01/01 would come out Ordinal 0.
     */
    private static final int AD_epochAdjustment;

    /**
     * April is 4
     */
    public static final int APR = 4;

    /**
     * April is 4
     */
    public static final int APRIL = 4;

    /**
     * August is 8
     */
    public static final int AUG = 8;

    /**
     * August is 8
     */
    public static final int AUGUST = 8;

    /**
     * Constant: adjustment to make ordinal 0 come out to 1970 Jan 01 for BC date calculations. Account for missing year
     * 0.
     */
    private static final int BC_epochAdjustment;

    /**
     * Constant: when passed to a constructor, it means caller guarantees YYYY MM DD are valid including leap year
     * effects and missing day effects. BigDate will not bother to check them.
     *
     * @noinspection WeakerAccess
     * @see #CHECK
     * @see #NORMALIZE
     * @see #NORMALISE
     */
    public static final int BYPASSCHECK = 1;

    /**
     * constant: when passed to a contructor it means BigDate should check that YYYY MM DD are valid.
     *
     * @noinspection WeakerAccess
     * @see #BYPASSCHECK
     * @see #NORMALIZE
     * @see #NORMALISE
     */
    public static final int CHECK = 0;

    /**
     * December is 12
     */
    public static final int DEC = 12;

    /**
     * December is 12
     */
    public static final int DECEMBER = 12;

    /**
     * February is 2
     */
    public static final int FEB = 2;

    /**
     * February is
     */
    public static final int FEBRUARY = 2;

    /**
     * Friday in Bigdate is 5
     */
    public static final int FRI = 5;

    /**
     * Friday in Bigdate is 5
     */
    public static final int FRIDAY = 5;

    /**
     * Constant: day of the first day of the month of the Gregorian Calendar Pope Gregory: 1582 Oct 15, British: 1752
     * Sep 14
     */
    private static final int GC_firstDD;

    /**
     * Constant: Ordinal for 1582 Dec 31, the last day of first year of the Gregorian calendar.
     */
    private static final int GC_firstDec_31;

    /**
     * Constant: month of the first date of the Gregorian Calendar. Pope Gregory: 1582 Oct 15, British: 1752 Sep 14
     *
     * @noinspection FieldCanBeLocal
     */
    private static final int GC_firstMM;

    /**
     * Constant: Ordinal for 1582 Oct 15, the first day of the Gregorian calendar.
     */
    private static final int GC_firstOrdinal;

    /**
     * Constant: year of the first date (1752 Oct 15) of the Gregorian Calendar = 1582. Just after the missing daysp.
     * Different parts of the world made the transition at different times. Pope Gregory: 1582 Oct 4, British: 1752 Sep
     * 2
     */
    private static final int GC_firstYYYY;

    /**
     * January is 1
     */
    public static final int JAN = 1;

    /**
     * Constant: Ordinal for 1 AD Jan 01
     */
    private static final int Jan_01_0001;

    // don't move this up with other publics since it requires privates
    // for its definition.

    /**
     * Constant: Ordinal for 1 BC Jan 01
     */
    private static final int Jan_01_0001BC;

    /**
     * Constant: Ordinal for 4 AD Jan 01
     */