org.oorexx.datergf

## Class DateTimeRGF

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

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

      public class DateTimeRGF
      extends java.lang.Object
      implements java.lang.Cloneable, java.lang.Comparable, java.io.Serializable

  `DateTimeRGF` implements a class consisting of a `DateRGF` and `TimeRGF`.

  This class has a Waba and a Java version, due to the following methods, which are implemented depending on the runtime environment:

  Implemented? |  |
  Java | Waba | Method name | Short Description
  yes | yes | public static void update(Object obj) | Updates a `DateTimeRGF` object, a `DateRGF` object or a `TimeRGF` object to the local time of the machine.

  This version was created with Waba (e.g. http://www.SuperWaba.org) family of Java-compatible mobile systems (PDAs, Handies, etc.) in mind. Hence this package does not use threads or exceptions. The Waba version does not use the datatypes double and long.
  (Though there are two methods in this class employing long, meant for running under virtual machines offering that datatype: `toLong(int epoch)` and `valueOf(int epoch, long millis)`.) The original Waba as well as many other Java VMs for small devices do not support datatype long.

  Some of the available operations are:

  - Calculating the difference in days between two DateTimeRGFs (`subtract(DateTimeRGF other)`),

  - creating a DateTimeRGF object from `unsigned` `int` (yep!) on Waba (as well as creating them) which allows one e.g. to use/create the Palm `unsigned int` values directly from Waba.

  Examples:

            DateTimeRGF dt1, dt2;
            dt1=new DateTimeRGF(2001,1,1,0,0,0);      // yields: 2001-01-01 00:00:00
            dt2=new DateTimeRGF(2005,12,31,11,59,59); // yields: 2005-12-31 11:59:59

            float  diff1=dt2.subtract(dt1);           // yields: "1825.5" (1825 and 1/2 days)
            double diff2=dt2.subtractDouble(dt1);     // yields: "1825.499988436699"

                           // if running under Waba yields actual date and time:
            dt2.update();
            diff1=dt2.subtract(dt1);       // yields: number of days and time since the
                                           //         beginning of the new millenium

      ------------------------ Apache Version 2.0 license -------------------------
          Copyright (C) 2001-2006 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-21      - catering for changes in TimeRGF
                                   - deleted float/double subtract(), and their add()-counterparts
                                   - new subtract (and add()) working on a two-element int-array) under
                                     Waba exact to the millisecond (now using int only)!
                                   - corrected a bug with toLong()

                                   - added the Serializable interface; DateRGF(), TimeRGF() have
                                     in addition readObject() and writeObject() implemented

                   2001-04-02      - introduced variant "JAVA" and "WABA"
                   2005-12-28      - added Apache license 2.0, put sources with BSF4Rexx

  Version:
    0.92, date: 2001-02-08 through 2001-04-02, 2006-01-01
  Author:
    Rony G. Flatscher
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `DateRGF` | `date` DateRGF field to store the date portion.
    `TimeRGF` | `time` TimeRGF field to store the time portion.
    `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.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DateTimeRGF()` Creates a DateTimeRGF object set to "0001-01-01 00:00:00.000".
    `DateTimeRGF(DateRGF date, TimeRGF time)` Creates a DateTimeRGF object set to the arguments `date` and `time`.
    `DateTimeRGF(int year, int month, int day, int hour, int minute, int second)` Creates a DateTimeRGF object set to the values from the arguments.
    `DateTimeRGF(int year, int month, int day, int hour, int minute, int second, int millis)` Creates a DateTimeRGF object set to the values from the arguments.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `DateTimeRGF` | `add(int days, int millis)` Adds the number of days to the date field and the number of milliseconds to the time field of this DateTimeRGF object.
    `DateTimeRGF` | `assign(DateTimeRGF otherDateTimeRGF)` Assigns otherDateTimeRGF to this DateTimeRGF.
    `java.lang.Object` | `clone()` Implements the "Clonable" interface.
    `int` | `compareTo(java.lang.Object otherDateTimeRGF)` Implements the "Comparable" interface.
    `boolean` | `equals(DateTimeRGF otherDateTimeRGF)` Implements the "Comparator.equals(Object obj)" interface.
    `int[]` | `subtract(DateTimeRGF other)` Subtracts a DateTimeRGF object from this one.
    `int` | `toInt(int epoch)` Renders the DateTimeRGF object into an `int`, encoded as seconds since/until the given epoch.
    `long` | `toLong(int epoch)` Renders the DateTimeRGF object into a long, encoded as milliseconds since/until the given epoch.
    `java.lang.String` | `toString()` Render the DateTimeRGF object to a string.
    `DateTimeRGF` | `update()` Updates the DateTimeRGF object to the actual local date and time of the machine.
    `static DateTimeRGF` | `valueOf(int epoch, int unsigned_seconds)` Creates a DateTimeRGF from the unsigned int relative to the given epoch.
    `static DateTimeRGF` | `valueOf(int epoch, long millis)` Creates a DateTimeRGF object from the number of milliseconds since/to the given epoch.

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

    - #### date

          public DateRGF date

      DateRGF field to store the date portion.

    - #### time

          public TimeRGF time

      TimeRGF field to store the time portion.

  - ### Constructor Detail

    - #### DateTimeRGF

          public DateTimeRGF()

      Creates a DateTimeRGF object set to "0001-01-01 00:00:00.000".

    - #### DateTimeRGF

          public DateTimeRGF(DateRGF date,
                             TimeRGF time)

      Creates a DateTimeRGF object set to the arguments `date` and `time`.

    - #### DateTimeRGF

          public DateTimeRGF(int year,
                             int month,
                             int day,
                             int hour,
                             int minute,
                             int second)

      Creates a DateTimeRGF object set to the values from the arguments.
      Parameters:
        `year` - a value between 1 and 9999.
        `month` - a value between 1 and 12.
        `day` - a value between 1 and the maximum number of days of the appropriate month.
        `hour` - a value between 0 and 23.
        `minute` - a value between 0 and 59.
        `second` - a value between 0 and 59.

    - #### DateTimeRGF

          public DateTimeRGF(int year,
                             int month,
                             int day,
                             int hour,
                             int minute,
                             int second,
                             int millis)

      Creates a DateTimeRGF object set to the values from the arguments.
      Parameters:
        `year` - a value between 1 and 9999.
        `month` - a value between 1 and 12.
        `day` - a value between 1 and the maximum number of days of the appropriate month.
        `hour` - a value between 0 and 23.
        `minute` - a value between 0 and 59.
        `second` - a value between 0 and 59.
        `millis` - a value between 0 and 999.

  - ### Method Detail

    - #### add

          public DateTimeRGF add(int days,
                                 int millis)

      Adds the number of days to the date field and the number of milliseconds to the time field of this DateTimeRGF object.

      Works on any Java-VM, even ones with no implementations of the `long` or `double` datatype, like some for for PDAs (like the classic Waba); therefore there may be rounding errors, if the integer part (representing whole days) is too large.

                                       // create a DateTimeRGF object with a
                                       // value of: "2010-01-12 14:05:47.123"
                DateTimeRGF dt=new DateTimeRGF(2010,01,12,14,05,47,123);

                dt.add(1, 64800000);    // add 1 3/4 days == 1 day, 18 hours (= 64800000 millis)
                                       // "dt" now: "2010-01-14 08:05:47.123"

      Parameters:
        `days` - number of days to add to DateTimeRGF.
        `millis` - number of milliseconds to add to DateTimeRGF.

    - #### subtract

          public int[] subtract(DateTimeRGF other)

      Subtracts a DateTimeRGF object from this one.

      Works on any Java-VM, even ones with no implementations of the `double` datatype, like some for for PDAs (like the classic Waba); therefore there may be rounding errors, if the integer part (representing whole days) is too large.

      Example:

                                       // create a DateTimeRGF object with a
                                       // value of: "2010-01-12 14:05:47"
                DateTimeRGF dt1=new DateTimeRGF(2010,01,12,14,05,47);

                                       // create a DateTimeRGF object with a
                                       // value of: "2010-01-14 08:05:47"
                DateTimeRGF dt2=new DateTimeRGF(2010,01,14,8,05,47);

                int []      diff=dt2.subtract(dt1);    // yields: {1, 64800000};

      Parameters:
        `other` - the DateTimeRGF object to subtract.
      Returns:
        an `int` array with two elements
        - at index '0': the difference in number of days,
        - at index '1': the difference in milliseconds.

    - #### assign

          public DateTimeRGF assign(DateTimeRGF otherDateTimeRGF)

      Assigns otherDateTimeRGF to this DateTimeRGF.

    - #### compareTo

          public int compareTo(java.lang.Object otherDateTimeRGF)

      Implements the "Comparable" interface.
      Specified by:
        `compareTo` in interface `java.lang.Comparable`
      Parameters:
        `otherDateTimeRGF` - a DateTimeRGF
      Returns:
        `-1` if this DateTimeRGF is earlier (smaller) than `otherDateTimeRGF`, `0` if both times are equal, `+1` if this DateTimeRGF is later (greater) than `otherDateTimeRGF`

    - #### clone

          public java.lang.Object clone()

      Implements the "Clonable" interface.
      Overrides:
        `clone` in class `java.lang.Object`
      Returns:
        a newly created DateTimeRGF object with all fields set to this DateTimeRGF object.

    - #### equals

          public boolean equals(DateTimeRGF otherDateTimeRGF)

      Implements the "Comparator.equals(Object obj)" interface.
      Parameters:
        `otherDateTimeRGF` - a DateTimeRGF
      Returns:
        `true` if DateTimes are equal (have both the same value in the fields `date` and `time`), `false` else.

    - #### toString

          public java.lang.String toString()

      Render the DateTimeRGF object to a string.
      Overrides:
        `toString` in class `java.lang.Object`

    - #### toLong

          public long toLong(int epoch)

      Renders the DateTimeRGF object into a long, encoded as milliseconds since/until the given epoch. The 'epoch' is the basedate (at midnight) used to calculate the number of seconds from/to this DateTimeRGF object.

      Does not Work on Java-VMs with no implementation of the `long` datatype (e.g. early versions of Waba for PDAs).

      Remark: If your system is using seconds, then you need to mulitply the second value by `1000` in order to arrive at the needed millisecond value.

                DateTimeRGF dt=new DateTimeRGF(2010,1,12, 14,5,47);
                               // "dt" is now: "2010-01-12 14:05:47"

                long secs_long=dt.toLong(DTC.EPOCH_PALM);
                               // "secs_long" is now: "3.346.149.947" seconds
                               //                     since DateRGF.EPOCH_PALM

      Parameters:
        `epoch` - one of: `DTC.EPOCH_MACINTOSH`, `DTC.EPOCH_PALM`, `DTC.EPOCH_JAVA`, `DTC.EPOCH_DOS`, `DTC.EPOCH_WIN32`, `DTC.EPOCH_MJD`.

        It is possible to use an integer encoded date (a positive number in the form of: `year*10000+month*100+day`) as the `epoch`. In such a case that date (starting at midnight) is used as the epoch. If an illegal epoch is given, the default epoch of `DateRGF.getDefaultEpochDate()` is used.

    - #### valueOf

          public static DateTimeRGF valueOf(int epoch,
                                            long millis)

      Creates a DateTimeRGF object from the number of milliseconds since/to the given epoch.

      Does not Work on Java-VMs with no implementation of the `long` datatype (e.g. early versions of Waba for PDAs).

      Remark: If your system is using seconds, then you need to mulitply the second value by `1000` in order to arrive at the needed millisecond value.

                               // 3.346.149.947 seconds since DateRGF.EPOCH_PALM,
                               // which is exactly: "2010-01-12 14:05:47"
                long secs_long=3346149947l;

                DateTimeRGF dt=valueOf(DTC.EPOCH_PALM, secs_long);
                               // "dt" is now: "2010-01-12 14:05:47"

      Parameters:
        `epoch` - one of: `DTC.EPOCH_MACINTOSH`, `DTC.EPOCH_PALM`, `DTC.EPOCH_JAVA`, `DTC.EPOCH_DOS`, `DTC.EPOCH_WIN32`, `DTC.EPOCH_MJD`. If an illegal epoch is given, the default epoch of `DateRGF.getDefaultEpochDate()` is used.
        `millis` - number of milliseconds since/to the epoch date (midnight).

    - #### toInt

          public int toInt(int epoch)

      Renders the DateTimeRGF object into an `int`, encoded as seconds since/until the given epoch. The 'epoch' is the basedate used to calculate the number of seconds from/to this DateTimeRGF object.

      Use this returned `unsigned int` as a parameter for `valueOf(int unsigned_int, int epoch)`.

      Remark: An int - if regarded as an unsigned int - can store at most 49710 days and 23295 secs (or a value range between 0 and 4.294.967.295). Therefore, one can only cover the date/time-range between the epoch date (midnight) and a little bit more than 135 years after it. E.g. for the `DTC.EPOCH_PALM` the maximum date/time value storable is exactly: '2040-02-06 06:28:15' (an unsigned integer with all bits set is represented as `-1` if interpreted as a signed integer).

      This was written to support the Palm operating system which uses an unsigned int representing the seconds elapsed since its epoch (1904-01-01, midnight), cf. `DTC.EPOCH_PALM`.

                     // create "dt" and set it to: "2010-01-12 14:05:47"
                DateTimeRGF dt=new DateTimeRGF(2010,1,12, 14,5,47);

                int secs_int=dt.toInt(DTC.EPOCH_PALM);
                     // "secs_int" is now: "-948.817.349", which is equivelant to
                     // an unsigned int with a value of '3.346.149.947'
                     // (seconds elapsed since DateRGF.EPOCH_PALM)

      Parameters:
        `epoch` - one of: `DTC.EPOCH_MACINTOSH`, `DTC.EPOCH_PALM`, `DTC.EPOCH_JAVA`, `DTC.EPOCH_DOS`, `DTC.EPOCH_WIN32`, `DTC.EPOCH_MJD`.

        It is possible to use an integer encoded date (a positive number in the form of: `year*10000+month*100+day`) as the `epoch`. In such a case that date (starting at midnight) is used as the epoch. If an illegal epoch is given, the default epoch of `DateRGF.getDefaultEpochDate()` is used.

      Returns:
        an (unsigned!) `int` representing the seconds to add to the epoch in order to arrive at this DateTimeRGF; if this DateTimeRGF is before the epoch or after `epoch+49710days+23295secs` then 0 is returned.

    - #### valueOf

          public static DateTimeRGF valueOf(int epoch,
                                            int unsigned_seconds)

      Creates a DateTimeRGF from the unsigned int relative to the given epoch.

      This was written to support the Palm operating system which uses an unsigned int representing the seconds elapsed since its epoch (1904-01-01, midnight), cf. `DTC.EPOCH_PALM`.

      The algorithm uses (signed) `int` only, such that this method can be used on Java-bytecode systems, which do not support long (or double), e.g. PDA's.

                               // The date and time "2010-01-12 14:05:47" lies
                               // 3.346.149.947 seconds after DateRGF.EPOCH_PALM;
                               // if stored as an 'unsigned int' but referred to as
                               // a 'signed int', one needs to use the value
                               // '-948.817.349' in order to set the appropriate
                               // bits.
                int secs_int=-948817349;

                DateTimeRGF dt=valueOf(DTC.EPOCH_PALM, secs_int);
                               // "dt" is now: "2010-01-12 14:05:47"

      Parameters:
        `epoch` - one of: `DTC.EPOCH_MACINTOSH`, `DTC.EPOCH_PALM`, `DTC.EPOCH_JAVA`, `DTC.EPOCH_DOS`, `DTC.EPOCH_WIN32`, `DTC.EPOCH_MJD`.
        `unsigned_seconds` - an `int` which gets interpreted as an `unsigned int` (cf. `toInt(int epoch)`).

        It is possible to use an integer encoded date (a positive number in the form of: `year*10000+month*100+day`) as the `epoch`. In such a case that date (starting at midnight) is used as the epoch. If an illegal epoch is given, the default epoch of `DateRGF.getDefaultEpochDate()` is used.

      Returns:
        a DateTimeRGF object set according to the given epoch.

    - #### update

          public DateTimeRGF update()

      Updates the DateTimeRGF object to the actual local date and time of the machine. For this purpose class java.util.GregorianCalendar is instantiated.

      This method guarantees, that for both, the DateRGF and the TimeRGF object, the `same` timestamp is used. Otherwise it is thinkable, that while the TimeRGF object is updated the day rolls over and the update of the DateRGF object reflects a different day (and vice versa).

      Examples:

               DateTimeRGF dt=new DateTimeRGF();     // yields: '0001-01-01 00:00:00.000'

                     // if run on "2010-09-22" at "17:49:01.987", then
               dt.update();  // yields: '2010-09-22 17:49:01.987'