Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.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(Time otherTime)`
`Object` | `copy()`
`int` | `get(int flag)` Allows to retrieve time fields and a rendering of Time to integer.
`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
`equals, getClass, hashCode, 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: ``

  - raw_millis=0
    Time: "00:00:00"
  - raw_millis=86399999
    Time: "23:59:59.999" (or result of: 23*3600000+59*60000+59*1000+999)

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:

  - 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:

           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:
    - `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 `Time`.

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

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD