org.oorexx.datergf

## Class TimeRGF

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

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

      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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

    Constructors
    Constructor and 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

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
      Overrides:
        `clone` in class `java.lang.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 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"

      Overrides:
        `toString` in class `java.lang.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'