Package org.oorexx.datergf

Class DateRGF

java.lang.Object
org.oorexx.datergf.DateRGF
All Implemented Interfaces:
Serializable, Cloneable, Comparable
public class DateRGF extends Object implements Cloneable, Comparable, Serializable
DateRGF(int, int, int) is an implementation of Date which allows for date manipulations and date arithmetics.

The philosophy of this class follows the "DateRGF.cmd", a date arithmetic function written for the scripting language Rexx, which is available as commercial and (opensourced) free interpreters for practically every operating system in the world.

DateRGF(int, int, int) allows dates in the range of 0001-01-01 and 9999-12-31. By default (can be changed with setGregorianChange(int year, int month, int day)) it switches from the Julian calendar to the Gregorian calendar in October of 1582 (October 4th of 1582 is followed by October 15th of 1582). It uses the ISO-values for indicating the days and the ISO-rules to determine which week is the first week for a year.

Some of the available operations are:

  • Calculating the difference in days between two DateRGFs,
  • adding days to a DateRGF (using negative days one subtracts them from a DateRGF),
  • creating various DateRGF-values, like beginning (end) of a week (month, quarter, half-year = semester, year) a DateRGF falls into, optionally adding (subtracting) days from it,
  • getting information about DateRGFs like year, month, day, day-of-week, number of days in a month etc.

This Java-version was created for the Waba (e.g. http://www.SuperWaba.org) family of Java-compatible mobile systems (PDAs, Handies, etc.) (e.g.: not employing threading, exceptions, and the datatypes long and double).
This class attempts to use as few resources as possible, yet allow for comprehensive and fast date manipulations.

DateRGF is not modelled after Java's classes Date, Calendar! Therefore, in order for getting fast to the point of this class, most method descriptions contain short examples.

Examples: 

      DateRGF firstDate=new DateRGF(   1, 1, 1), // yields: '0001-01-01'
              lastDate =new DateRGF(9999,12,31); // yields: '9999-12-31'

      int     days=lastDate.subtract(firstDate); // yields: 3652060

      DateRGF tmpDate=(DateRGF)firstDate.clone();// yields: '0001-01-01'
      tmpDate.add(days);                         // yields: '9999-12-31'

                     // get Labor Monday in 2001
      tmpDate=new DateRGF(2001,8,31);            // yields: '2001-08-31', a Friday
      tmpDate.set(WEEKDAY, 1);                   // yields: '2001-09-03'

                     // get Labor Monday in 2001 in one line
      tmpDate=(new DateRGF(2001,8,31)).set(WEEKDAY,1); // yields: '2001-08-31', a Friday

      DateRGF d=valueOf(ENCODED_AS_INTEGER, 20190521);       // yields: '2019-05-21'

      d.set(WB, 0);              // yields: '2019-05-19', if weekStart=7 (Sunday)
      int iso_day=d.get(DOW);    // yields: 7 (ISO-number for Sunday)

      d.set(WB, 3);              // yields: '2019-05-22', if weekStart=7 (Sunday)
      d.set(WE, 0);              // yields: '2019-05-25', if weekStart=7 (Sunday)

      DateRGF easter=DateRGF.easter(d);          // yields: '2019-04-21'

      int palm_days=d.get(EPOCH_PALM);           // yields: 35430
      int java_days=d.get(EPOCH_JAVA);           // yields: 18041


           // if run on "2010-09-22 17:49:01" under Waba, then
      d.update();                // yields: '2010-09-22'

      String day_name  =getString(DN, d.get(DOW));           // yields: 'Saturday'
      String month_name=getString(MN, d.get(MONTH_FIELD));   // yields: 'May'
 
------------------------ Apache Version 2.0 license -------------------------
    Copyright (C) 2001-2016 Rony G. Flatscher

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
 -----------------------------------------------------------------------------

 Temporary dev-infos:

    version  date            remark

    0.9.2    2001-03-20      - removed all deprecated stuff from the 0.9.1 version
                             - changed:
                                  is24hours          -> is24Hour
                                  date_delimiter     -> dateSeparator
                                  week_start         -> weekStart
                                  date_order         -> dateOrder

             2001-03-21      - added Serializable (needs only one int to store the DateRGF)
                               taking care with supplied readObject(), writeObject()

             2001-04-02      - introduced variant "JAVA" and "WABA"
             2001-04-05      - included update() here

             2005-12-28      - added Apache license 2.0, put sources with BSF4Rexx
             2016-11-07      - added a static main method that gives a brief overview of this class
Version:
0.93, date: 2001-02-08 through 2001-04-05, 2006-01-01, 2019-08-13 (Javadoc fix)
Author:
Rony G. Flatscher
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static char
    dateSeparator
    Stores the desired string to be used to delimit date fields in toString().
    protected int
    day
    Stores the day, a value between 1 and 28, 29, 30, 31, depending on the month and year.
    protected int
    jdn
    Stores the "jdn" ("Julian day number") value.
    protected int
    month
    Stores the month, a value between 1 and 12.
    static String
    version
    Version string indicating version of this class (majorVersion*100+minorVersion concatenated with a dot and the sorted date of last change.
    protected int
    year
    Stores the year, a value between 1 and 9999.

  • Constructor Summary

    Constructors
    Constructor
    Description
    DateRGF()
    Creates a DateRGF object with all fields set to 1.
    DateRGF(int year, int month, int day)
    Creates a DateRGF from the three integers, representing year, month and day.

  • Method Summary

    Modifier and Type
    Method
    Description
    DateRGF
    add(int numOfDays)
    Adds the number of days to this DateRGF.
    DateRGF
    assign(DateRGF otherDateRGF)
    Assigns all DateRGF fields of otherDateRGF to this DateRGF.
    protected void
    cD()
    Checks the date.
    Object
    clone()
    Implements the "Clonable" interface.
    int
    compareTo(Object otherDateRGF)
    Implements the "Comparable" interface.
    static int
    date2jdn(int year, int month, int day, int flag)
    Calculates the Julian day number of the Julian period from a date which belongs to the Julian or Gregorian calendar, depending on the flag argument.
    static int
    date2jdn(DateRGF aDate)
    Determines into which calendar a date falls into and calls the appropriate method to calculate the respective Julian day number of the Julian period.
    static int
    daysInMonth(DateRGF date)
    Determines the number of days for the date's month.
    static int
    dow(DateRGF tmpDate)
    Calculates the day of week (DOW).
    static int
    dow_ord(DateRGF tmpDate)
    Calculates the ordinal value of the day of week (DOW), which is relative to weekStart.
    static DateRGF
    easter(int year, int flag)
    Calculate the Julian (Orthodox) or Gregorian (Western) Easter Sunday for the given year.
    static DateRGF
    easter(DateRGF date)
    Calculate Easter Sunday for the year of the date.
    boolean
    equals(DateRGF otherDateRGF)
    Returns true if DateRGFs are equal (both have the same value in the fields year month day).
    static DateRGF
    fromJulianDate(int julianDate)
    Renders a Julian date into a DateRGF.
    int
    get(int flag)
    Allows to retrieve information about this DateRGF.
    static DateRGF
    getDefaultEpochDate()
    Returns a clone (copy) of the presently defined epoch DateRGF.
    static DateRGF
    getGregorianChange()
    Returns a clone of the DateRGF object which is set to the first date of the Gregorian calendar.
    static int
    getStatic(int flag)
    Allows to query the static fields weekStart and dateOrder.
    static String
    getString(int flag, int value)
    Returns the name of the day or of the month according to flag.
    static boolean
    isLeapYear(DateRGF date)
    Determines whether the given DateRGF is a leap year.
    static int
    isoWeek(DateRGF date)
    Determines into which week of the year the given DateRGF falls into using ISO rules.
    static DateRGF
    jdn2date(int jdn, DateRGF aDate)
    Determines into which calendar a Julian day number of the Julian period falls into (Julian calendar or Gregorian calendar) and calls the appropriate method to set the date accordingly.
    static DateRGF
    jdn2date(int jdn, DateRGF aDate, int flag)
    Sets the date belonging to the Julian calendar or Graegorian calendar according to the given Julian day number of the Julian period.
    static void
    main(String[] args)
    Main method to give a few hints on the command line.
    protected static String
    ri(int value, int len)
    Convert the primitive Java int tmp to a String and right adjust value with a leading 0 to two places, if necessary.
    DateRGF
    set(int flag, int number)
    Allows to set this DateRGF object to a specific date.
    DateRGF
    set(int year, int month, int day)
    Set all three DateRGF fields at once.
    static DateRGF
    setDefaultEpochDate(int value)
    Sets the DateRGF which presently serves as the epoch.
    static DateRGF
    setGivenWeekday(int weekdays, DateRGF date)
    From a given DateRGF calculate the previous or next date, which falls on one of the given weekdays.
    static DateRGF
    setGregorianChange(int year, int month, int day)
    Allows to set the date on which the usage of the Gregorian calendar starts.
    static int
    setStatic(int flag, int number)
    Allows to set the static fields weekStart and dateOrder.
    static void
    setString(int flag, String[] value)
    Allows to set the names of the days or months in either the field dayNames or monthNames according to flag.
    int
    subtract(DateRGF other)
    Calculates the differences (in number of days) between two DateRGFs.
    static int
    toJulianDate(DateRGF date)
    Renders the DateRGF into a Julian date.
    String
    toString()
    Returns time formatted into a string according to the fields dateSeparator, dateOrder.
    DateRGF
    update()
    This method sets the DateRGF object to the actual local date of the system.
    static DateRGF
    valueOf(int flag, int daysToAdd)
    Creates a DateRGF object by adding days to the given DateRGF (which may be an epoch date indicated by the appropriate constant).
    static DateRGF
    valueOf(String value)
    Create a DateRGF object from a string containing a DateRGF encoded according to the present setting of dateOrder.

    Methods inherited from class java.lang.Object

    equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • version

      public static String version
      Version string indicating version of this class (majorVersion*100+minorVersion concatenated with a dot and the sorted date of last change.

    • dateSeparator

      public static char dateSeparator
      Stores the desired string to be used to delimit date fields in toString(). Will get set on class load from preferences. The default value is: '-'.

    • year

      protected transient int year
      Stores the year, a value between 1 and 9999. If changing this value directly, set jdn to DTC.NAD and call cD() which checks the resulting DateRGF and sets jdn to its appropriate value.

    • month

      protected transient int month
      Stores the month, a value between 1 and 12. If changing this value directly, set jdn to DTC.NAD and call cD() which checks the resulting DateRGF and sets jdn to its appropriate value.

    • day

      protected transient int day
      Stores the day, a value between 1 and 28, 29, 30, 31, depending on the month and year. If changing this value directly, set jdn to DTC.NAD and call cD() which checks the resulting DateRGF and sets jdn to its appropriate value.

    • jdn

      protected transient int jdn
      Stores the "jdn" ("Julian day number") value. This number uniquely numbers each day in the "Julian period" and may be represented by different calendar dates depending on the calendar one uses: the Gregorian calendar (used for civil purposes throughout the world!) or the Julian calendar (used sometimes for religious purposes, e.g. in the Orthodox Christian world for determining Christmas and Easter).

      This is a unique value assigned to each day irrespectible of the calendar system one uses. Cf. "Frequently Asked Questions about Calendars" and read about 'Julian period', 'Julian day (number)', 'Julian calendar' and 'Gregorian calendar'.

      Use the get(int flag) method, to access this field, using the flag DTC.JDN. (If this field has a value of DTC.NAD then the actual jdn value will get calculated and returned.)

  • Constructor Details

    • DateRGF

      public DateRGF()
      Creates a DateRGF object with all fields set to 1.

    • DateRGF

      public DateRGF(int year, int month, int day)
      Creates a DateRGF from the three integers, representing year, month and day. The valid range is '0001-01-01' through '9999-12-31'.

      Please note: due to the underlying algorithms, it is not an error to use '0' or a value larger than the maximum value for month or day. In such a case the date will be used which comes 'closest' to the indicated values. E.g. '2004-03-00' will be translated to '2004-02-29', '2005-01-00' to '2004-12-31', '2005-00-00' to '2004-11-30', '2005-12-40' to '2006-01-09', '2005-13-40' to '2006-02-09', etc.

  • Method Details

    • main

      public static void main(String[] args)
      Main method to give a few hints on the command line.
      Since:
      2016-11-07

    • valueOf

      public static DateRGF valueOf(int flag, int daysToAdd)
      Creates a DateRGF object by adding days to the given DateRGF (which may be an epoch date indicated by the appropriate constant).

      Examples: 

            DateRGF e=DateRGF.valueOf(DateRGF.EPOCH_PALM, 0),         // yields: '1904-01-01'
              m=new DateRGF(2001, 1, 1);                        // yields: '2001-01-01', the
                                                                // new millenium

      int palm_days=m.subtract(e);                              // yields: 35430

      DateRGF d=DateRGF.valueOf(DateRGF.EPOCH_PALM, palm_days); // yields: '2001-01-01'

      e.add(palm_days);                                         // yields: '2001-01-01'

      Parameters:
      flag - one of the constants of epoch (DTC.EPOCH_MACINTOSH, DTC.EPOCH_PALM, DTC.EPOCH_JAVA, DTC.EPOCH_DOS, DTC.EPOCH_WIN32, DTC.EPOCH_MJD, DTC.EPOCH_DEFAULT), or an explicit date serving as an epoch, formed according to the DTC.ENCODED_AS_INTEGER rule.
      daysToAdd - days to add/subtract to/from epoch or integer encoded date, indicated by the second parameteras. If the second parameter flag is DTC.ENCODED_AS_INTEGER than this parameter is interpreted as a date encoded as an integer.
      Returns:
      a DateRGF object.

    • valueOf

      public static DateRGF valueOf(String value)
      Create a DateRGF object from a string containing a DateRGF encoded according to the present setting of dateOrder.

      Extraction of digits is very lenient, i.e. everything but a digit is skipped, all digits (up to eight) are concatenated and then turned into a DateRGF date.

      If the length of the extracted string of digits is six characters, then it is assumed that the year is two digits long and '2000' is added to the year.

      If the number of digits is not exactly eight (the year consists of four digits) or not exactly six (the year consists of two digits), null is returned. Therefore the day and the month must be given with two digits (i.e. leading 0, if necessary).

      Examples (assuming dateOrder: DTC.YMD): 

            DateRGF a=valueOf("1989-05-21") ,  // yields: '1989-05-21'
              b=valueOf("19930922"  ) ,  // yields: '1993-09-22'
              c=valueOf("1782.10.15") ,  // yields: '1782-10-15'
              d=valueOf("2010 02 28") ,  // yields: '2010-02-28'
              e=valueOf("030201"    ) ,  // yields: '2003-02-01'
              f=valueOf("123"       ) ;  // yields: null
      Parameters:
      value - a string containing a string representation of DateRGF.
      Returns:
      the appropriate DateRGF object, or null, if there are not exactly eight or six digits in the parsed (after removing delimiters) string.

    • add

      public DateRGF add(int numOfDays)
      Adds the number of days to this DateRGF. If that number is negative, the DateRGF gets the number of days subtracted.

      Examples: 

            DateRGF newMillenium=new DateRGF(2001,01,01); // yields: '2001-01-01'
      newMillenium.add(100000);   // add 100.000 days, yields: '2274-10-17'
      Parameters:
      numOfDays - number of days to add to this DateRGF.
      Returns:
      the DateRGF object (set to the new values).

    • subtract

      public int subtract(DateRGF other)
      Calculates the differences (in number of days) between two DateRGFs. This subtracts otherDateRGF from this DateRGF.

      Examples: 

            DateRGF firstDate=new DateRGF(   1, 1, 1), // yields: '0001-01-01'
              lastDate =new DateRGF(9999,12,31); // yields: '9999-12-31'

      int     days=lastDate.subtract(firstDate); // yields: 3652060
      Parameters:
      other - DateRGF object to subtract from this DateRGF.
      Returns:
      number of days between this DateRGF and otherDateRGF.

    • assign

      public DateRGF assign(DateRGF otherDateRGF)
      Assigns all DateRGF fields of otherDateRGF to this DateRGF. After this operation this.equals(otherDateRGF) will be true.
      Parameters:
      otherDateRGF - date to assign from.
      Returns:
      the DateRGF object (set to the new values).

    • cD

      protected void cD()
      Checks the date. The DateRGF may get adjusted to the 'closest' date, if the values of one of the DateRGF fields month or day are beyond their appropriate limits. (E.g. '2005-12-32' will be turned into '2006-01-01', or '2717-01-00' into '2716-12-31'!)

      This method is executed only, if jdn is set to DTC.NAD. At the end of the method jdn will be set to the value fully representing the given DateRGF.

    • compareTo

      public int compareTo(Object otherDateRGF)
      Implements the "Comparable" interface. Returns -1, if this time is earlier (smaller) than the argument, returns 0, if both are equal, returns +1, if this time is later (greater) than the argument.
      Specified by:
      compareTo in interface Comparable

    • clone

      public Object clone()
      Implements the "Clonable" interface. Returns a newly created DateRGF object with all fields set to this DateRGF object.
      Overrides:
      clone in class Object

    • equals

      public boolean equals(DateRGF otherDateRGF)
      Returns true if DateRGFs are equal (both have the same value in the fields year month day).

    • get

      public int get(int flag)
      Allows to retrieve information about this DateRGF.

      flag returns
      DTC.YEAR_FIELD year
      DTC.MONTH_FIELD month
      DTC.DAY_FIELD day
      DTC.WEEK_START DTC.WEEK_START
      DTC.JDN jdn
      DTC.DOW day of week (according to ISO)
      DTC.DOW_ORDINAL the number of day in the week, relative to weekStart
      DTC.JULIAN Julian date, e.g. the date 19590202 (February, 2nd) will return the Julian date 1959033 (33rd day in the year)
      DTC.WEEK the week number according to ISO
      DTC.DAYS_IN_MONTH number of days in this date's month
      DTC.HY 1, if date is in first half (semester) of the year, 2 else.
      DTC.Q the quarter of the date (1 through 4).
      DTC.EPOCH_MACINTOSH, DTC.EPOCH_PALM, DTC.EPOCH_JAVA, DTC.EPOCH_DOS, DTC.EPOCH_WIN32, DTC.EPOCH_MJD, DTC.EPOCH_DEFAULT the number of days between this DateRGF and the given epoch. If using EPOCH_DEFAULT, then the default epoch is used. The default epoch may be set with setDefaultEpochDate(int value) and queried/gotten with getDefaultEpochDate().
      DTC.ENCODED_AS_INTEGER returns this DateRGF encoded as an integer: year*10000+month*100+day.

      Examples: 

            DateRGF d=new DateRGF(2059, 5, 20);            // yields: '2059-05-20'
      int     this_date  =d.get(DTC.ENCODED_AS_INTEGER), // yields: 20590520
              quarter    =d.get(DTC.Q),                  // yields: 2
              semester   =d.get(DTC.HY),                 // yields: 1
              dow        =d.get(DTC.DOW),                // yields: 2
              ws         =d.get(DTC.WEEK_START),         // yields: 7
              dow_ord    =d.get(DTC.DOW_ORDINAL),        // yields: 3
              dim        =d.get(DTC.DAYS_IN_MONTH),      // yields: 31
              palm_days  =d.get(DTC.EPOCH_PALM),         // yields: 56753
              java_days  =d.get(DTC.EPOCH_JAVA);         // yields: 32646
      Parameters:
      flag - indicates the desired value.
      Returns:
      the value according to the given flag, -1, if unknown flag is used.

    • set

      public DateRGF set(int flag, int number)
      Allows to set this DateRGF object to a specific date.

      flag comment
      The following flags use the parameter number for setting the desired values.
      DTC.YEAR_FIELD set year to the value of parameter number.
      DTC.MONTH_FIELD set month to the value of parameter number.
      DTC.DAY_FIELD set day to the value of parameter number.
      DTC.ENCODED_AS_INTEGER set year, month and day to the Date value encoded as an int in parameter number.
      DTC.WEEKDAY set date to one of the weekdays encoded in parameter parameter number. This uses the setGivenWeekday(int weekdays, DateRGF date) to carry out the operation.
      DTC.WEEK_START set weekStart to the day as indicated by the parameter number. If an invalid value is passed, the present setting is not changed.

      Examples: 

            DateRGF d=DateRGF.valueOf(20010101, 0);    // yields: '2001-01-01'

      d.set(YEAR_FIELD, 2345);             // yields: '2345-01-01'
      d.set(MONTH_FIELD, 12);              // yields: '2345-12-01'
      d.set(DAY_FIELD, 15);                // yields: '2345-12-15', a Saturday

      d.set(WEEKDAY, 1);                   // yields: '2345-12-17', the next Monday

      d.set(ENCODED_AS_INTEGER, 17280228); // yields: '1728-02-28'

      flag comment
      The following flags cause the DateRGF object to be firstly set to the desired date, then number of days are added to (subtracted from, if negative) to it.
      DTC.HYB set the date to the beginning of its semester and add the value of parameter number to it.
      DTC.HYE set the date to the end of its semester and add the value of parameter number to it.
      DTC.MB set the date to the beginning of its month and add the value of parameter number to it.
      DTC.ME set the date to the end of its month and add the value of parameter number to it.
      DTC.QB set the date to the beginning of its quarter and add the value of parameter number to it.
      DTC.QE set the date to the end of its quarter and add the value of parameter number to it.
      DTC.WB set the date to the beginning of its week and add the value of parameter number to it. The beginning of a week is determined by weekStart.
      DTC.WE set the date to the end of its week and add the value of parameter number to it. The end of a week is always six days after the day of weekStart.
      DTC.YB set the date to the beginning of its year and add the value of parameter number to it.
      DTC.YE set the date to the end of its year and add the value of parameter number to it.

      Examples: 

            d.set(DTC.ENCODED_AS_INTEGER, 17280128);  // yields: '1728-02-28'
      d.set(DTC.WB, 0);              // yields: '1728-02-22', if weekStart=7
      d.set(DTC.WB, 3);              // yields: '1728-02-25', if weekStart=7
      d.set(DTC.WE, 0);              // yields: '1728-02-28', if weekStart=7

      d.set(DTC.QB, 0);              // yields: '1728-01-01'
      d.set(DTC.QE, 0);              // yields: '1728-03-31'
      d.set(DTC.QE, -21);            // yields: '1728-03-10
                                 // i.e. three weeks before the end of the quarter
      Parameters:
      flag - indicates type of set operation
      number - either a value for a DateRGF-field (year, month, day) or may be a number indicating how many days to add/subtract from the desired date.
      Returns:
      this DateRGF object (set to the new values).

    • getStatic

      public static int getStatic(int flag)
      Allows to query the static fields weekStart and dateOrder.

      flag returns
      DTC.DATE_ORDER dateOrder
      DTC.WEEK_START weekStart
      Parameters:
      flag - indicates the desired value.
      Returns:
      the value according to the given flag, -1, if unknown flag is used.

    • setStatic

      public static int setStatic(int flag, int number)
      Allows to set the static fields weekStart and dateOrder.

      flag sets and returns
      DTC.DATE_ORDER dateOrder
      DTC.WEEK_START weekStart
      Parameters:
      flag - indicates the desired value.
      Returns:
      the value according to the given flag, -1, if unknown flag is used. Illegal values are ignored, instead the present set value for the indicated field is returned.

    • set

      public DateRGF set(int year, int month, int day)
      Set all three DateRGF fields at once.
      Parameters:
      year - the DateRGF field year.
      month - the DateRGF field month.
      day - the DateRGF field day.
      Returns:
      this DateRGF object (set to the new values).

    • toString

      public String toString()
      Returns time formatted into a string according to the fields dateSeparator, dateOrder.
      Overrides:
      toString in class Object

    • ri

      protected static String ri(int value, int len)
      Convert the primitive Java int tmp to a String and right adjust value with a leading 0 to two places, if necessary.

    • dow

      public static int dow(DateRGF tmpDate)
      Calculates the day of week (DOW).
      Parameters:
      tmpDate - DateRGF to work on.
      Returns:
      a value between 1 (Monday as per ISO) and 7 (Sunday as per ISO).

    • dow_ord

      public static int dow_ord(DateRGF tmpDate)
      Calculates the ordinal value of the day of week (DOW), which is relative to weekStart. Hence, if weeks start on Sundays, then Mondays will be the second day relative to the start of week. If weeks start on Monday, then Monday will be the first day of the week.
      Parameters:
      tmpDate - DateRGF to work on.
      Returns:
      a value between 1 and 7, indicating the ordinal value relative to the beginning of the week as defined in weekStart.

    • setGivenWeekday

      public static DateRGF setGivenWeekday(int weekdays, DateRGF date)
      From a given DateRGF calculate the previous or next date, which falls on one of the given weekdays. This algorithm moves the date between one and seven days depending on the argument weekdays.

      Each decimal character represents a weekday, starting with DTC.MONDAY (=1) and ending with DTC.SUNDAY (=7). One needs to encode them into an integer, e.g. '12345' represents the next weekdays from Monday to Friday, whereas '67' represents the next weekdays Saturday and Sunday. Therefore to find the next Monday or Friday, use '15'. If seeking a previous date being one of the indicated weekdays, use negative numbers (e.g. '-12345', '-67', '-15' etc.).

      Examples: 

                        // get Labor Day of 2001 (first Monday in September)
      DateRGF d=new DateRGF(2001, 8, 31); // yields: '2001-08-31'
      setGivenWeekday(1, d);              // yields: '2001-09-03'

                  // get the date the summer time ends in 2006 (last Sunday in October)
      d=new DateRGF(2006, 11, 01);        // yields: '2006-11-01'
      setGivenWeekday(-7, d);             // yields: '2006-10-29'

                  // get last working day of this quarter
      d.set(DTC.QE, 1);                   // yields: '2007-01-01', first day of next quarter
      setGivenWeekday(-12345, d);         // yields: '2006-12-29', a Friday
      Parameters:
      weekdays - an integer number indicating which days to match with. If this number is negative, then the closest previous weekday is searched, else the closest next one.
      date - to be used.
      Returns:
      DateRGF set to the given weekday.

    • date2jdn

      public static int date2jdn(DateRGF aDate)
      Determines into which calendar a date falls into and calls the appropriate method to calculate the respective Julian day number of the Julian period. This method decides which calendar (Gregorian or Julian) to use by taking getGregorianChange() into account.

      Examples: 

                        // assuming getGregorianChange(): '1582-10-15'
     DateRGF d1=new DateRGF(1582, 10,  4),  // yields: '1582-10-04' (using Julian calendar)
             d2=new DateRGF(1582, 10,  15), // yields: '1582-10-15' (using Gregorian calendar)
             d3=new DateRGF(),
             d4=new DateRGF();

     int   jdn1=DateRGF.date2jdn(d1),       // yields: 2299160
           jdn2=DateRGF.date2jdn(d2);       // yields: 2299161

     DateRGF.jdn2date(jdn1, d3);            // yields: '1582-10-04' (using Julian calendar)
     DateRGF.jdn2date(jdn2, d4);            // yields: '1582-10-15' (using Gregorian calendar)
      Parameters:
      aDate - the DateRGF for which to calculate the Julian day number.
      Returns:
      the Julian day number of the Julian period.
      See Also:

    • date2jdn

      public static int date2jdn(int year, int month, int day, int flag)
      Calculates the Julian day number of the Julian period from a date which belongs to the Julian or Gregorian calendar, depending on the flag argument.

      Refer to the excellent source on Calendars at Frequently Asked Questions about Calendars (did find it the first time on 2001-03-06!, ---rgf).

      Example ("translating a Julian calendar date to a Gregorian calendar date"): 

                // get Julian day numer for '2010-01-01' in the Julian calendar
    int     jdn=date2jdn(2010,1,1,JULIAN);        // yields: 2455211
    DateRGF   d=new DateRGF();

    DateRGF.jdn2date(jdn, d, DateRGF.JULIAN);     // yields: '2010-01-01' (JULIAN)
    DateRGF.jdn2date(jdn, d, DateRGF.GREGORIAN);  // yields: '2010-01-14' (GREGORIAN)
      Parameters:
      flag - one of DTC.JULIAN (default) or DTC.GREGORIAN indicating which calendar is targeted.
      Returns:
      the Julian day number of the Julian period with the given date belonging either to the Julian calendar or Gregorian calendar. (This number is unique for each day and independent of the calendar one uses.)

    • jdn2date

      public static DateRGF jdn2date(int jdn, DateRGF aDate)
      Determines into which calendar a Julian day number of the Julian period falls into (Julian calendar or Gregorian calendar) and calls the appropriate method to set the date accordingly. This method decides which of these calendar to use by taking getGregorianChange() into account.
      Parameters:
      jdn - the Julian day number of the Julian period.
      aDate - the DateRGF to be set accordingly.
      Returns:
      the DateRGF object (set to the new values).
      See Also:

    • jdn2date

      public static DateRGF jdn2date(int jdn, DateRGF aDate, int flag)
      Sets the date belonging to the Julian calendar or Graegorian calendar according to the given Julian day number of the Julian period.

      Refer to the excellent source on Calendars at Frequently Asked Questions about Calendars (did find it the first time on 2001-03-06!).

      Example ("translating a Gregorian calendar date to a Julian calendar date"): 

                // get Julian day numer for '2010-01-01' in the Gregorian calendar
    int     jdn=date2jdn(2010,1,1,DTC.GREGORIAN);     // yields: 2455198
    DateRGF   d=new DateRGF();

    DateRGF.jdn2date(jdn, d, DTC.GREGORIAN);          // yields: '2010-01-01' (GREGORIAN)
    DateRGF.jdn2date(jdn, d, DTC.JULIAN);             // yields: '2009-12-19' (JULIAN)
      Parameters:
      jdn - the Julian day number of the Julian period.
      aDate - the DateRGF to be set accordingly.
      flag - one of DTC.JULIAN or DTC.GREGORIAN indicating which calendar is targeted.
      Returns:
      the DateRGF object (set to the new values).

    • isLeapYear

      public static boolean isLeapYear(DateRGF date)
      Determines whether the given DateRGF is a leap year. A leap year will have 29 days in February instead of 28.
      Parameters:
      date - the date to be checked on.
      Returns:
      true, if the date falls into a leap year.

    • daysInMonth

      public static int daysInMonth(DateRGF date)
      Determines the number of days for the date's month.
      Parameters:
      date - the date to be used.
      Returns:
      number of days.

    • toJulianDate

      public static int toJulianDate(DateRGF date)
      Renders the DateRGF into a Julian date. A Julian date is calculated as: year*1000+day_of_year. E.g. the date "20191231" yields the Julian date "2019365".
      Parameters:
      date - the date to be rendered.
      Returns:
      the appropriate Julian date.

    • fromJulianDate

      public static DateRGF fromJulianDate(int julianDate)
      Renders a Julian date into a DateRGF.
      Parameters:
      julianDate - a date in the form: YYYYddd, where ddd indicates the day of the year.
      Returns:
      a DateRGF

    • isoWeek

      public static int isoWeek(DateRGF date)
      Determines into which week of the year the given DateRGF falls into using ISO rules. The first ISO week of a year is the one which contains the first Thursday of January. Therefore there may be years with 53 (!) weeks, e.g. 20041231 through 20050102.
      Parameters:
      date - the date for which the week of the year has to be determined.
      Returns:
      a value between 1 and 53 indicating the ISO week of the year.

    • getDefaultEpochDate

      public static DateRGF getDefaultEpochDate()
      Returns a clone (copy) of the presently defined epoch DateRGF. If a default epoch has not been defined yet, DTC.EPOCH_PALM is used.

    • setDefaultEpochDate

      public static DateRGF setDefaultEpochDate(int value)
      Sets the DateRGF which presently serves as the epoch.
      Parameters:
      value - must be either an integer encoded as defined in DTC.ENCODED_AS_INTEGER or one of DTC.EPOCH_MACINTOSH, DTC.EPOCH_PALM (default), DTC.EPOCH_JAVA, DTC.EPOCH_DOS, DTC.EPOCH_WIN32, DTC.EPOCH_MJD}.
      Returns:
      a clone of the set DateRGF object.

    • getString

      public static String getString(int flag, int value)
      Returns the name of the day or of the month according to flag.

      Examples: 

            DateRGF d  =new DateRGF(2001,1,1);         // yields: '2001-01-01'
      String  mon=getString(DTC.DN, d.get(DTC.DOW));     // yields: "Monday"
      Parameters:
      flag - DTC.DN or DTC.MN
      value - 1-based day or month, if value is smaller than 1 then it defaults to 1
      Returns:
      name of the day or month

    • setString

      public static void setString(int flag, String[] value)
      Allows to set the names of the days or months in either the field dayNames or monthNames according to flag.

      Examples: 

            String tagesnamen[]={"Montag", "Dienstag", "Mittwoch", "Donnerstag",
                           "Freitag", "Samstag", "Sonntag" };

      DateRGF.setString(DTC..DN, tagesnamen);

      DateRGF d  =new DateRGF(2001,1,1);         // yields: '2001-01-01'
      String  mon=getString(DTC.DN, d.get(DOW));     // yields: "Montag"
      Parameters:
      flag - DTC.DN or DTC.MN
      value - String[] of names, exactly 7 for DN and exactly 12 for MN

    • easter

      public static DateRGF easter(DateRGF date)
      Calculate Easter Sunday for the year of the date. Uses getGregorianChange() in order to determine whether Easter Sunday is to be created for the Julian calendar (Orthodox Easter Sunday) or for the Gregorian calendar.

      Note: In the very rare case of using a date which falls into the year where the change to the Gregorian calendar occurred, than be very careful which easter is calculated! In such a case you may want to explicitly determine which easter is to be calculated by invoking easter(int year, int flag) with flag set to either DTC.JULIAN (i.e. orthodox easter) or DTC.GREGORIAN.

      In case you are interested in those Christian (e.g. Roman Catholic) holidays depending on Easter Sunday, these are the most important ones (giving the German name too, as well as the number of days before or after Easter Sunday, to be directly used in add(int numOfDays)):

      Day dependent on Easter Sunday Number of days to add/subtract to/from Easter Sunday
      Shrove Tuesday (Mardi Gras)
      (Faschingsdienstag)       		-47
      Ash Wednesday
      (Aschermittwoch)       		-46 (six weeks and four days before Easter Sunday)
      Saturday of Lazarus -8 (one week before Easter Sunday)
      Palm Sunday
      (Palmsonntag)       		-7 (one week before Easter Sunday)
      Maundy Thursday
      (Gründonnerstag)       		-3
      Good Friday
      (Karfreitag)       		-2
      Easter Sunday
      (Ostersonntag)       		0
      Easter Monday
      (Ostermontag)       		+1
      Ascension Day
      (Christi Himmelfahrt)       		+39 (five weeks and four days after Easter Sunday)
      Whitsunday
      (Pfingstsonntag)       		+49 (seven weeks after Easter Sunday)
      Whitmonday
      (Pfingstmontag)       		+50 (seven weeks and one day after Easter Sunday)
      Corpus Christi
      (Fronleichnam)       		+60 (eight weeks and four days after Easter Sunday)

      Examples: 

                // assuming Gregorian change of most of the British Empire and
          // and USA, i.e. first Gregorian date is '1752-09-14':
    setGregorianChange(1752, 9, 14);      // set Gregorian change date

    DateRGF d1=new DateRGF(1659, 11, 17), // yields: '1659-11-17' (a Julian calendar date)
            d2=new DateRGF(2016,  2,  1), // yields: '2016-02-01' (a Gregorian calendar date)

    DateRGF d3=easter(d1);        // yields: '1659-04-03' (a Julian calendar date)
            d4=easter(d2);        // yields: '2016-03-27' (a Gregorian calendar date)
      Parameters:
      date - determines the year for which Easter Sunday is to be calculated. If it is smaller (earlier) than getGregorianChange() than the Julian calendar is used, the Gregorian calendar else.
      Returns:
      a new DateRGF object set to Easter Sunday.
      See Also:

    • easter

      public static DateRGF easter(int year, int flag)
      Calculate the Julian (Orthodox) or Gregorian (Western) Easter Sunday for the given year.

      The returned date represents the respective calendar, i.e. if flag is DTC.GREGORIAN, then the date returned belongs to to the Gregorian calendar, otherwise to the Julian calendar. Therefore you may directly use the jdn to produce the according date in the other calendar system.

      Refer to the excellent source on Calendars at Frequently Asked Questions about Calendars (did find it the first time on 2001-03-06!, ---rgf).

      Example: 

          DateRGF d1=new DateRGF(2016, 9, 1);           // yields: '2016-09-01'

    DateRGF d2=easter(d1.get(DTC.YEAR_FIELD), DTC.JULIAN);// yields: '2016-04-18'
                                                  // (a Julian calendar date)

    d2.jdn2date(d2.get(JDN), d2, DTC.GREGORIAN);      // yields: '2016-05-01'
                                                  // (a Gregorian calendar date)
      Parameters:
      year - for which Easter Sunday is to be calculated.
      flag - one of DTC.JULIAN or DTC.GREGORIAN indicating which calendar is targeted.
      Returns:
      a DateRGF set to Easter Sunday of the given year.

    • getGregorianChange

      public static DateRGF getGregorianChange()
      Returns a clone of the DateRGF object which is set to the first date of the Gregorian calendar. All days before this date are in the Julian calendar.

    • setGregorianChange

      public static DateRGF setGregorianChange(int year, int month, int day)
      Allows to set the date on which the usage of the Gregorian calendar starts. All days before this date are in the Julian calendar.
      Parameters:
      year - the year of the first Gregorian date.
      month - the month of the first Gregorian date.
      day - the day of the first Gregorian date.
      Returns:
      a clone of the set DateRGF object.

    • update

      public DateRGF update()
      This method sets the DateRGF object to the actual local date of the system. For this purpose class java.util.GregorianCalendar is instantiated.

      Examples: 

           DateRGF     d =new DateRGF(); // yields: '0001-01-01'

           // if run on "2010-09-22", then
     d.update();                   // yields: '2010-09-22'