org.oorexx.datergf.DateTimeRGF

All Implemented Interfaces:: Serializable, Cloneable, Comparable

public class DateTimeRGF extends Object implements Cloneable, Comparable, 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

Description

DateRGF

date

DateRGF field to store the date portion.

TimeRGF

time

TimeRGF field to store the time portion.

static 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

Description

DateTimeRGF()

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

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.

DateTimeRGF(DateRGF date, TimeRGF time)

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

Modifier and Type

Method

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.

Object

clone()

Implements the "Clonable" interface.

int

compareTo(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 <b<unsigned 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.

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 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.
- date
  
  public DateRGF date
  
  DateRGF field to store the date portion.
- time
  
  public TimeRGF time
  
  TimeRGF field to store the time portion.
Constructor Details
- 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 Details
- 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(Object otherDateTimeRGF)
  
  Implements the "Comparable" interface.
  
  Specified by:
  
  compareTo in interface 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 Object clone()
  
  Implements the "Clonable" interface.
  
  Overrides:
  
  clone in class 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 String toString()
  
  Render the DateTimeRGF object to a string.
  
  Overrides:
  
  toString in class 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 <b<unsigned 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'

Class DateTimeRGF

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

version

date

time

Constructor Details

DateTimeRGF

DateTimeRGF

DateTimeRGF

DateTimeRGF

Method Details

add

subtract

assign

compareTo

clone

equals

toString

toLong

valueOf

toInt

valueOf

update