org.oorexx.datergf

## Class DateRGF

- java.lang.Object
- - org.oorexx.datergf.DateRGF

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

      public class DateRGF
      extends java.lang.Object
      implements java.lang.Cloneable, java.lang.Comparable, java.io.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:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and 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 java.lang.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 and 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

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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.
    `java.lang.Object` | `clone()` Implements the "Clonable" interface.
    `int` | `compareTo(java.lang.Object otherDateRGF)` Implements the "Comparable" interface.
    `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` | `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` | `daysInMonth(DateRGF date)` Determines the number of days for the date's month.
    `static int` | `dow_ord(DateRGF tmpDate)` Calculates the ordinal value of the day of week (DOW), which is relative to `weekStart`.
    `static int` | `dow(DateRGF tmpDate)` Calculates the day of week (DOW).
    `static DateRGF` | `easter(DateRGF date)` Calculate Easter Sunday for the year of the date.
    `static DateRGF` | `easter(int year, int flag)` Calculate the Julian (Orthodox) or Gregorian (Western) Easter Sunday for the given year.
    `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 java.lang.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(java.lang.String[] args)` Main method to give a few hints on the command line.
    `protected static java.lang.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, java.lang.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.
    `java.lang.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(java.lang.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 Detail

    - #### version

          public static java.lang.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 Detail

    - #### 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 Detail

    - #### main

          public static void main(java.lang.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(java.lang.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(java.lang.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 `java.lang.Comparable`

    - #### clone

          public java.lang.Object clone()

      Implements the "Clonable" interface. Returns a newly created DateRGF object with all fields set to this DateRGF object.
      Overrides:
        `clone` in class `java.lang.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 java.lang.String toString()

      Returns time formatted into a string according to the fields `dateSeparator`, `dateOrder`.
      Overrides:
        `toString` in class `java.lang.Object`

    - #### ri

          protected static java.lang.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(int year, int month, int day, int flag)`

    - #### 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(int jdn, DateRGF aDate, int flag)`

    - #### 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 java.lang.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,
                                       java.lang.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(int year, int flag)`

    - #### 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'