TimeRGF (The Vienna Version of BSF4Rexx with Add-ons, 20080913, Rony G. Flatscher)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

20080913, rgf

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.oorexx.datergf
Class TimeRGF

java.lang.Object
  org.oorexx.datergf.TimeRGF

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

public class TimeRGF
extends java.lang.Object
implements java.lang.Cloneable, java.lang.Comparable, java.io.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
`static java.lang.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 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
`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
`TimeRGF`	`assign(TimeRGF other)` Assigns other TimeRGF to this TimeRGF.
`java.lang.Object`	`clone()` Implements the "Clonable" interface.
`int`	`compareTo(java.lang.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.
`java.lang.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(java.lang.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 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.

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

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 Detail

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(java.lang.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(java.lang.Object otherTimeRGF)

Implements the "Comparable" interface.

Specified by:: compareTo in interface java.lang.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 java.lang.Object clone()

Implements the "Clonable" interface.

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 java.lang.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"

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'

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

20080913, rgf

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.oorexx.datergf Class TimeRGF

version

timeSeparator

am_pm_string

is24Hour

showSecs

hour

minute

second

millis

raw_millis

TimeRGF

TimeRGF

TimeRGF

valueOf

valueOf

valueOf

assign

compareTo

clone

equals

get

set

subtract

toFloat

toString

update

org.oorexx.datergf
Class TimeRGF