superwaba.ext.xplat.util.datergf
Class Time

java.lang.Object
  |
  +--superwaba.ext.xplat.util.datergf.Time

public class Time
extends Object

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:

      Time time1, time2, time3, time4;

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

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

      time3=Time.valueOf(diff);           // yields: "11:21:31"
      time4=Time.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'
 
 Temporary dev-infos:

    version  date            remark

    0.91.0   2003-04-07      - rgf; changed equals() to match the signature of Object.equals();
                               added method hashCode(),
                               documents explicitly that the interface Comparable is implemented in this class


    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 Time)
                               taking care with supplied readObject(), writeObject()

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


Field Summary
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().
 
Constructor Summary
Time()
          Creates a Time object with all fields set to 0.
Time(int hour, int minute, int second)
          Creates a Time from the three integers, representing hour, minute and second.
Time(int hour, int minute, int second, int millis)
          Creates a Time from the three integers, representing hour, minute and second.
 
Method Summary
 Time assign(Time other)
          Assigns other Time to this Time.
 int compareTo(Object otherTime)
           
 Object copy()
           
 boolean equals(Object otherTime)
          The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, this method returns true if and only if x and y refer to the same object (x==y has the value true).
 int get(int flag)
          Allows to retrieve time fields and a rendering of Time to integer.
 int hashCode()
          Returns a hashcode value for this time object.
 Time set(int flag, int new_value)
          Allows to set the indicated time portion.
 float subtract(Time otherTime)
          Subtracts otherTime and returns the difference as a fraction.
 float toFloat()
          Renders Time as a fraction of a day.
 String toString()
          Renders Time as a String.
 Time update()
          This method sets the TimeRGF object to to the actual local time of the system.
static Time valueOf(float fraction)
          Creates a Time object from a fraction of a day.
static Time valueOf(int flag, int intTime)
          Creates a Time object from an integer, representing the time.
static Time valueOf(String value)
          Create a Time object from a string containing a Time encoded exactly according to the present setting of the fields: timeSeparator, is24Hour and am_pm_string.
 
Methods inherited from class java.lang.Object
getClass, notify, wait, wait
 

Field Detail

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:

Constructor Detail

Time

public Time()
Creates a Time object with all fields set to 0.

Time

public Time(int hour,
            int minute,
            int second)
Creates a Time 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

Time

public Time(int hour,
            int minute,
            int second,
            int millis)
Creates a Time 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 Detail

valueOf

public static Time valueOf(float fraction)
Creates a Time object from a fraction of a day.

Note:this value is assumed to not contain milliseconds, i.e. the resulting Time 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:

Examples:

     Time t1=Time.valueOf( 0.47399306f);   // yields: "11:22:33"
     Time t2=Time.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 Time valueOf(int flag,
                           int intTime)
Creates a Time object from an integer, representing the time.

Examples:

 Time t1=Time.valueOf(DTC.ENCODED_AS_INTEGER, 112233);   // yields: "11:22:33"
 Time t2=Time.valueOf(DTC.ENCODED_AS_INTEGER,-112233);   // yields: "12:37:27"

 Time t3=Time.valueOf(DTC.ENCODED_AS_SECONDS,  40953);   // yields: "11:22:33"
 Time t4=Time.valueOf(DTC.ENCODED_AS_SECONDS, -40953);   // yields: "12:37:27"

 Time t5=Time.valueOf(DTC.ENCODED_AS_MILLIS ,  40953123);   // yields: "11:22:33.123"
 Time t6=Time.valueOf(DTC.ENCODED_AS_MILLIS , -40953123);   // yields: "12:37:26.877"

 Time t7=Time.valueOf(DTC.ENCODED_AS_MILLIS ,  86399999);   // yields: "23:59:59.999"
 
Parameters:
intTime - 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 intTime, can be one of:

valueOf

public static Time valueOf(String value)
Create a Time object from a string containing a Time 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 Time object will have millis set to 0.

Examples assuming timeSeparator with a value of ':' and is24Hour with a value of true:

      Time t1=Time.valueOf("00:01:02");    // yields: '00:01:02'
      Time t2=Time.valueOf("11:59:59");    // yields: '11:59:59'
      Time t3=Time.valueOf("12:55:44");    // yields: '12:55:44'
      Time t4=Time.valueOf("17:01:59");    // yields: '17:01:59'
      Time t5=Time.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"}:

      Time t1=Time.valueOf("12:01:02 am"); // yields: '00:01:02'
      Time t2=Time.valueOf("11:59:59 am"); // yields: '11:59:59'
      Time t3=Time.valueOf("12:55:44 pm"); // yields: '12:55:44'
      Time t4=Time.valueOf("05:01:59 pm"); // yields: '17:01:59'
      Time t5=Time.valueOf("11:11:22 pm"); // yields: '23:11:22'
 
Parameters:
value - a string containing a string representation of Time.
Returns:
the appropriate Time object, or null, if there are not at least hour and minute available.

assign

public Time assign(Time other)
Assigns other Time to this Time.

compareTo

public int compareTo(Object otherTime)
Parameters:
otherTime - a Time
Returns:
-1 if this Time is earlier (smaller) than otherTime, 0 if both times are equal, +1 if this Time is later (greater) than otherTime

copy

public Object copy()
Returns:
A newly created Time object with all fields set to this Time object.

equals

public boolean equals(Object otherTime)
Description copied from class: Object
The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, this method returns true if and only if x and y refer to the same object (x==y has the value true).
Overrides:
equals in class Object
Parameters:
otherTime - a Time
Returns:
true if Times are equal (have both the same values in their appropriate time fields), false else.

hashCode

public int hashCode()
Returns a hashcode value for this time object. If time objects represent the same time, then the same hashcode is generated and returned for them.
Overrides:
hashCode in class Object
Returns:
a hashcode value for this object (the value of the raw_millis field)

get

public int get(int flag)
Allows to retrieve time fields and a rendering of Time to integer.

Examples:

     Time t1=new Time(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 Time set(int flag,
                int new_value)
Allows to set the indicated time portion.

Examples:

     Time t1=new Time(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(Time otherTime)
Subtracts otherTime 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 Time 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:

     Time t1=new Time(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 Time 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:

     Time t1=new Time(14,23,56);   // yields: "14:23:56"

     Time.is24Hour=true;             // changing global setting
     Time.showSecs =true;             // changing global setting
     String  s1=t1.toString();           // yields: "14:23:56"

     Time.is24Hour=false;            // changing global setting
     Time.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 Time object freely (using all fields)

update

public Time update()
This method sets the TimeRGF object to to the actual local time of the system.

Examples:

     TimeRGF t =new TimeRGF(); // yields: '00:00:00'

           // if run at "17:49:01.987", then
     t.update();               // yields: '17:49:01.987'