org.oorexx.datergf.TimeRGF

All Implemented Interfaces:: Serializable, Cloneable, Comparable

public class TimeRGF extends Object implements Cloneable, Comparable, Serializable

Class to implement the time of the day, consisting of the fields hour, minute, second and millis(econds).

This class was created with the Waba family (e.g. http://www.SuperWaba.org) of Java-compatible mobile systems (PDAs, Handies, etc.) in mind (e.g.: does not employ threads, exceptions, long and double).

Examples:

      TimeRGF time1, time2, time3, time4;

      time =new TimeRGF(23,59,59,999);       // yields: "23:59:59.999"

      time1=new TimeRGF(19,29,39);           // yields: "19:29:39"
      time2=new TimeRGF( 8, 8, 8);           // yields: "08:08:08"
      float diff=time1.subtract(time2);      // yields: "0.47327545"

      time3=TimeRGF.valueOf(diff);           // yields: "11:21:31"
      time4=TimeRGF.valueOf(-diff);          // yields: "12:38:29"

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

------------------------ 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-20      - added a millisecond field, changed code appropriately
                               (added: MILLIS_FIELD, millis, MILLIS_PER_DAY, MILLIS_PER_HOUR,
                                       MILLIS_PER_MINUTE, MILLIS_PER_SECOND,
                                       RAW_MILLIS_FIELD, raw_millis
                                removed: RAW_SECS_FIELD, raw_secs
                             - changed static "time_delimiter" to "timeSeparator"
             2001-03-21      - corrected a bug in set()
                             - added Serializable (needs only one int to store the TimeRGF)
                               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

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

static String[]

am_pm_string

An array of two strings representing "am" and "pm".

protected int

hour

Stores the hour, a value between 0 and 23.

static boolean

is24Hour

Indicates whether 24 hour clock (military time) or am/pm style is in effect in toString().

protected int

millis

Stores the milliseconds, a value between 0 and 999.

protected int

minute

Stores the minute, a value between 0 and 59.

protected int

raw_millis

Stores the "raw milliseconds".

protected int

second

Stores the second, a value between 0 and 59.

static boolean

showSecs

Indicates whether second portion should be shown in toString().

static char

timeSeparator

Character to be used to delimit time fields in toString().

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

TimeRGF()

Creates a TimeRGF object with all fields set to 0.

TimeRGF(int hour, int minute, int second)

Creates a TimeRGF from the three integers, representing hour, minute and second.

TimeRGF(int hour, int minute, int second, int millis)

Creates a TimeRGF from the three integers, representing hour, minute and second.
Method Summary

Modifier and Type

Method

Description

TimeRGF

assign(TimeRGF other)

Assigns other TimeRGF to this TimeRGF.

Object

clone()

Implements the "Clonable" interface.

int

compareTo(Object otherTimeRGF)

Implements the "Comparable" interface.

boolean

equals(TimeRGF otherTimeRGF)

Implements the "Comparator.equals(Object obj)" interface.

int

get(int flag)

Allows to retrieve time fields and a rendering of TimeRGF to integer.

TimeRGF

set(int flag, int new_value)

Allows to set the indicated time portion.

float

subtract(TimeRGF otherTimeRGF)

Subtracts otherTimeRGF and returns the difference as a fraction.

float

toFloat()

Renders TimeRGF as a fraction of a day.

String

toString()

Renders TimeRGF as a String.

TimeRGF

update()

This method sets the TimeRGF object to to the actual local time of the system.

static TimeRGF

valueOf(float fraction)

Creates a TimeRGF object from a fraction of a day.

static TimeRGF

valueOf(int flag, int intTimeRGF)

Creates a TimeRGF object from an integer, representing the time.

static TimeRGF

valueOf(String value)

Create a TimeRGF object from a string containing a TimeRGF encoded exactly according to the present setting of the fields: timeSeparator, is24Hour and am_pm_string.

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.
- timeSeparator
  
  public static char timeSeparator
  
  Character to be used to delimit time fields in toString(). Will get set on class load from preferences. This field can be queried/set directly. The default value is: ':'.
- am_pm_string
  
  public static String[] am_pm_string
  
  An array of two strings representing "am" and "pm". These two Strings are referred to in toString(), if is24Hour is set to false. The default value is (note the leading single blank): {"am", "pm"}.
- is24Hour
  
  public static boolean is24Hour
  
  Indicates whether 24 hour clock (military time) or am/pm style is in effect in toString(). Will get set on class load from preferences. If am/pm style is in effect, then 12:00:00 am is midnight and 12:00:00 pm is noon. This field can be queried/set directly. The default value is: true.
- showSecs
  
  public static boolean showSecs
  
  Indicates whether second portion should be shown in toString(). This field can be queried/set directly. The default value is: true.
- hour
  
  protected transient int hour
  
  Stores the hour, a value between 0 and 23.
- minute
  
  protected transient int minute
  
  Stores the minute, a value between 0 and 59.
- second
  
  protected transient int second
  
  Stores the second, a value between 0 and 59.
- millis
  
  protected transient int millis
  
  Stores the milliseconds, a value between 0 and 999.
- raw_millis
  
  protected transient int raw_millis
  Stores the "raw milliseconds". This is the total of milliseconds for this time, i.e. 0 >= raw_millis < 86400000 (cf. DTC.MILLIS_PER_DAY). Value is calculated as: raw_millis=hour*3600000+minute*60000+second*1000+millis.
  
  Examples:
  
  raw_millis=0
  TimeRGF: "00:00:00"
  
  raw_millis=86399999
  TimeRGF: "23:59:59.999" (or result of: 23*3600000+59*60000+59*1000+999)
Constructor Details
- TimeRGF
  
  public TimeRGF()
  
  Creates a TimeRGF object with all fields set to 0.
- TimeRGF
  
  public TimeRGF(int hour, int minute, int second)
  
  Creates a TimeRGF from the three integers, representing hour, minute and second. This constructor uses the absolute values of its arguments. If a field has a value, larger than its upper limit (e.g. '25' for hour), than the modulo (using the upper limit) result is used (e.g. '27' for hour yields '3', the result of '27 % 24').
  
  Parameters:
  
  hour - an int value between 0 and 23
  
  minute - an int value between 0 and 59
  
  second - an int value between 0 and 59
- TimeRGF
  
  public TimeRGF(int hour, int minute, int second, int millis)
  
  Creates a TimeRGF from the three integers, representing hour, minute and second. This constructor uses the absolute values of its arguments. If a field has a value, larger than its upper limit (e.g. '25' for hour), than the modulo (using the upper limit) result is used (e.g. '27' for hour yields '3', the result of '27 % 24').
  
  Parameters:
  
  hour - an int value between 0 and 23
  
  minute - an int value between 0 and 59
  
  second - an int value between 0 and 59
  
  millis - an int value between 0 and 999 representing milliseconds
Method Details
- valueOf
  
  public static TimeRGF valueOf(float fraction)
  Creates a TimeRGF object from a fraction of a day.
  Note:this value is assumed to not contain milliseconds, i.e. the resulting TimeRGF object will have millis set to 0.
  To produce the time the fractional part only is used. These are the rules to build the time:
  
  If the fraction is positive, the time is built as the number of hours, minutes and seconds increasing from midnight. E.g. '0.25' (1/4th of a day, i.e. 6 hours) yields the time: '06:00:00'.
  If the fraction is negative, the time is built as the number of hours, minutes and seconds decreasing from midnight. E.g. '-0.25' (1/4th of a day, i.e. 6 hours) yields the time: '18:00:00'.
  
  Examples:
  TimeRGF t1=TimeRGF.valueOf( 0.47399306f); // yields: "11:22:33" TimeRGF t2=TimeRGF.valueOf(-0.47399306f); // yields: "12:37:27"
  Parameters:
  
  fraction - represents the time as a fraction of a day. One second is represented as: 1f/86400.
- valueOf
  
  public static TimeRGF valueOf(int flag, int intTimeRGF)
  Creates a TimeRGF object from an integer, representing the time.
  Examples:
  TimeRGF t1=TimeRGF.valueOf(DTC.ENCODED_AS_INTEGER, 112233); // yields: "11:22:33" TimeRGF t2=TimeRGF.valueOf(DTC.ENCODED_AS_INTEGER,-112233); // yields: "12:37:27" TimeRGF t3=TimeRGF.valueOf(DTC.ENCODED_AS_SECONDS, 40953); // yields: "11:22:33" TimeRGF t4=TimeRGF.valueOf(DTC.ENCODED_AS_SECONDS, -40953); // yields: "12:37:27" TimeRGF t5=TimeRGF.valueOf(DTC.ENCODED_AS_MILLIS , 40953123); // yields: "11:22:33.123" TimeRGF t6=TimeRGF.valueOf(DTC.ENCODED_AS_MILLIS , -40953123); // yields: "12:37:26.877" TimeRGF t7=TimeRGF.valueOf(DTC.ENCODED_AS_MILLIS , 86399999); // yields: "23:59:59.999"
  Parameters:
  
  intTimeRGF - an integer representation of the time. If negative, the time is constructed by deducting the resulting time from midnight.
  
  flag - indicates how the time is encoded in intTimeRGF, can be one of:
  
  DTC.ENCODED_AS_INTEGER, an integer number in the form of: hour*10000+minute*100+second
  DTC.ENCODED_AS_MILLIS, an integer number representing the number of milliseconds,
  DTC.ENCODED_AS_SECONDS (default), an integer number representing the number of seconds.
  
  Returns:
  
  the appropriate set TimeRGF.
- valueOf
  
  public static TimeRGF valueOf(String value)
  Create a TimeRGF object from a string containing a TimeRGF encoded exactly according to the present setting of the fields: timeSeparator, is24Hour and am_pm_string. Only the first seven characters are inspected. If they do not contain at least three digits, then null is returned.
  Note:this value is assumed to not contain milliseconds, i.e. the resulting TimeRGF object will have millis set to 0.
  
  Examples assuming timeSeparator with a value of ':' and is24Hour with a value of true:
  TimeRGF t1=TimeRGF.valueOf("00:01:02"); // yields: '00:01:02' TimeRGF t2=TimeRGF.valueOf("11:59:59"); // yields: '11:59:59' TimeRGF t3=TimeRGF.valueOf("12:55:44"); // yields: '12:55:44' TimeRGF t4=TimeRGF.valueOf("17:01:59"); // yields: '17:01:59' TimeRGF t5=TimeRGF.valueOf("23:11:22"); // yields: '23:11:22'
  
  Examples assuming timeSeparator with a value of ':', is24Hour with a value of false and am_pm_string with a value of {"am", "pm"}:
  TimeRGF t1=TimeRGF.valueOf("12:01:02 am"); // yields: '00:01:02' TimeRGF t2=TimeRGF.valueOf("11:59:59 am"); // yields: '11:59:59' TimeRGF t3=TimeRGF.valueOf("12:55:44 pm"); // yields: '12:55:44' TimeRGF t4=TimeRGF.valueOf("05:01:59 pm"); // yields: '17:01:59' TimeRGF t5=TimeRGF.valueOf("11:11:22 pm"); // yields: '23:11:22'
  Parameters:
  
  value - a string containing a string representation of TimeRGF.
  
  Returns:
  
  the appropriate TimeRGF object, or null, if there are not at least hour and minute available.
- assign
  
  public TimeRGF assign(TimeRGF other)
  
  Assigns other TimeRGF to this TimeRGF.
- compareTo
  
  public int compareTo(Object otherTimeRGF)
  
  Implements the "Comparable" interface.
  
  Specified by:
  
  compareTo in interface Comparable
  
  Parameters:
  
  otherTimeRGF - a TimeRGF
  
  Returns:
  
  -1 if this TimeRGF is earlier (smaller) than otherTimeRGF, 0 if both times are equal, +1 if this TimeRGF is later (greater) than otherTimeRGF
- clone
  
  public Object clone()
  
  Implements the "Clonable" interface.
  
  Overrides:
  
  clone in class Object
  
  Returns:
  
  A newly created TimeRGF object with all fields set to this TimeRGF object.
- equals
  
  public boolean equals(TimeRGF otherTimeRGF)
  
  Implements the "Comparator.equals(Object obj)" interface.
  
  Parameters:
  
  otherTimeRGF - a TimeRGF
  
  Returns:
  
  true if Times are equal (have both the same values in their appropriate time fields), false else.
- get
  
  public int get(int flag)
  Allows to retrieve time fields and a rendering of TimeRGF to integer.
  Examples:
  TimeRGF t1=new TimeRGF(11,22,33); // yields: "11:22:33" int hour =t1.get(DTC.HOUR_FIELD), // yields: "11" minute=t1.get(MINUTE_FIELD), // yields: "22" sec =t1.get(SECOND_FIELD); // yields: "33" int a1=t1.get(ENCODED_AS_INTEGER); // yields: "112233" int a2=t1.get(ENCODED_AS_SECONDS); // yields: "40953" int a3=t1.get(RAW_MILLIS_FIELD); // yields: "40953000"
  Parameters:
  
  flag - one of DTC.HOUR_FIELD, DTC.MINUTE_FIELD, DTC.SECOND_FIELD, DTC.MILLIS_FIELD, DTC.RAW_MILLIS_FIELD, same as: DTC.ENCODED_AS_MILLIS, DTC.ENCODED_AS_SECONDS, DTC.ENCODED_AS_INTEGER (hour*10000+minute*100+second).
  
  Returns:
  
  the appropriate value, or -1, if an unknown flag was received.
- set
  
  public TimeRGF set(int flag, int new_value)
  Allows to set the indicated time portion.
  Examples:
  TimeRGF t1=new TimeRGF(23,59,59); // yields: "23:59:59" t1.set(DTC.HOUR_FIELD, 11); // yields: "11:59:59" t1.set(MINUTE_FIELD, 22); // yields: "11:22:59" t1.set(SECOND_FIELD, 33); // yields: "11:22:33" t1.set(ENCODED_AS_INTEGER, 10001); // yields: "01:00:01" t1.set(ENCODED_AS_SECONDS, 40953); // yields: "11:22:33" t1.set(RAW_MILLIS_FIELD, 40954000); // yields: "11:22:34"
  Parameters:
  
  flag - one of DTC.HOUR_FIELD, DTC.MINUTE_FIELD, DTC.SECOND_FIELD, DTC.MILLIS_FIELD, DTC.RAW_MILLIS_FIELD, same as: DTC.ENCODED_AS_MILLIS, DTC.ENCODED_AS_SECONDS, DTC.ENCODED_AS_INTEGER.
  
  new_value - a value appropriate for the fields to be set (cf. hour, minute, second, millis, raw_millis).
- subtract
  
  public float subtract(TimeRGF otherTimeRGF)
  
  Subtracts otherTimeRGF and returns the difference as a fraction.
  Note:the calculation is carried out without using the millis field (as if the millis field is set to 0. Reason: to cater for the limited precision of digits available with a float.
- toFloat
  
  public float toFloat()
  Renders TimeRGF as a fraction of a day.
  Note:the calculation is carried out without using the millis field (as if the millis field is set to 0. Reason: to cater for the limited precision of digits available with a float. This is the result of: (raw_millis-millis) / DTC.MILLIS_PER_DAY.
  Example:
  TimeRGF t1=new TimeRGF(11,22,33); // yields: "11:22:33" float f1=t1.toFloat(); // yields: "0.47399306"
  Returns:
  
  a float representing the time as a fraction of a day.
- toString
  
  public String toString()
  Renders TimeRGF as a String. The formatting is done according to the values of the fields: timeSeparator, showSecs, is24Hour and am_pm_string (with a preceeding blank).
  Hint: The millis field is never used by this method.
  Examples:
  TimeRGF t1=new TimeRGF(14,23,56); // yields: "14:23:56" TimeRGF.is24Hour=true; // changing global setting TimeRGF.showSecs =true; // changing global setting String s1=t1.toString(); // yields: "14:23:56" TimeRGF.is24Hour=false; // changing global setting TimeRGF.showSecs =false; // changing global setting s1=t1.toString(); // yields: "2:23 pm"
  Overrides:
  
  toString in class Object
  
  Returns:
  
  a string representing the time of a day.
  
  See Also:
  
  for formatting a TimeRGF object freely (using all fields)
- update
  
  public TimeRGF update()
  This method sets the TimeRGF object to to the actual local time of the system. For this purpose class java.util.GregorianCalendar is instantiated.
  Examples:
  TimeRGF t =new TimeRGF(); // yields: '00:00:00' // if run at "17:49:01.987", then t.update(); // yields: '17:49:01.987'

Class TimeRGF

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

version

timeSeparator

am_pm_string

is24Hour

showSecs

hour

minute

second

millis

raw_millis

Constructor Details

TimeRGF

TimeRGF

TimeRGF

Method Details

valueOf

valueOf

valueOf

assign

compareTo

clone

equals

get

set

subtract

toFloat

toString

update