TimeStruct (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.record

## Interface TimeStruct

- All Known Implementing Classes:
    TimeStructImpl

      public interface TimeStruct

  Specifies the time component of date and time values specified according to Coordinated Universal Time (UTC), including hour, minute, second and 1/250th of a second. The time structure is itself a component of a timestamp.

  To make values of this type, use the following methods from the MAJ forge:

  - From its component parts: `Forge.makeTime(byte, byte, byte)` and `Forge.makeTime(byte, byte, byte, byte)`;
  - From a `Calendar` value: `Forge.makeTime(java.util.Calendar)`;
  - The time now: `Forge.timeNow()`;
  - From a string representation as generated by `toString()`: `Forge.parseTime(String)`.
  See Also:
    `TimeStamp`, `DateStruct`, `TypeDefinitions.TimeStruct`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `TimeStruct` | `clone()` Create a cloned copy of this time value.
    `byte` | `getFraction()` Returns the fractions of a second component of the time value, measured in 1/250ths of a second..
    `byte` | `getHour()` Returns the hours component of the time value.
    `byte` | `getMinute()` Returns the minutes component of the time value.
    `byte` | `getSecond()` Returns the seconds component of the time value.
    `void` | `setFraction(byte fraction)` Sets the fractions of a second component of the time value, meansured in 1/250ths of a second and so in the range 0 to 249.
    `void` | `setHour(byte hour)` Sets the hours component of the time value, in the range 0 to 23.
    `void` | `setMinute(byte minute)` Sets the minutes component of the time value, in the range 0 to 59.
    `void` | `setSecond(byte second)` Sets the second component of the time value, normally in the range 0 to 59.
    `void` | `setTime(byte hour, byte minute, byte second)` Set the values of the time structure using an hour, minute and second values provided.
    `void` | `setTime(byte hour, byte minute, byte second, byte fraction)` Sets all the values of the time structure using the hour, minute, second and fraction of a second values provided.
    `String` | `toString()` Formats a UTC-style string representation of the time structure's value, including the timezone offset.

- - ### Method Detail

    - #### setTime

          void setTime(@UInt8
                       byte hour,
                       @UInt8
                       byte minute,
                       @UInt8
                       byte second)
                throws IllegalArgumentException

      Set the values of the time structure using an hour, minute and second values provided. The fraction of the second represented is set to be 0.

      Parameters:
        `hour` - Hours component of the time value, represented in 24-hour clock format.
        `minute` - Minutes component of the time value.
        `second` - Seconds component of the time value.
      Throws:
        `IllegalArgumentException` - One or more of the values is outside the acceptable range for a time value.

    - #### setTime

          void setTime(@UInt8
                       byte hour,
                       @UInt8
                       byte minute,
                       @UInt8
                       byte second,
                       @UInt8
                       byte fraction)
                throws IllegalArgumentException

      Sets all the values of the time structure using the hour, minute, second and fraction of a second values provided.

      Parameters:
        `hour` - Hours component of the time value, represented in 24-hour clock format.
        `minute` - Minutes component of the time value.
        `second` - Seconds component of the time value.
        `fraction` - Fractions of a second component of the time value, measured in 1/250ths of a second.
      Throws:
        `IllegalArgumentException` - One or more of the values is outside the acceptable range for a time value.

    - #### getFraction

          @UInt8
          byte getFraction()

      Returns the fractions of a second component of the time value, measured in 1/250ths of a second..

      Returns:
        Fractions of a second component of the time value.

    - #### setFraction

          void setFraction(@UInt8
                           byte fraction)
                    throws IllegalArgumentException

      Sets the fractions of a second component of the time value, meansured in 1/250ths of a second and so in the range 0 to 249.

      Parameters:
        `fraction` - Fractions of a second component of the time value.
      Throws:
        `IllegalArgumentException` - The fractions of a second value is outside the acceptable range.

    - #### getHour

          @UInt8
          byte getHour()

      Returns the hours component of the time value.

      Returns:
        Hours component of the time value.

    - #### setHour

          void setHour(@UInt8
                       byte hour)
                throws IllegalArgumentException

      Sets the hours component of the time value, in the range 0 to 23.

      Parameters:
        `hour` - Hours component of the time value.
      Throws:
        `IllegalArgumentException` - The hours value is outside the acceptable range.

    - #### getMinute

          @UInt8
          byte getMinute()

      Returns the minutes component of the time value.

      Returns:
        Minutes component of the time value.

    - #### setMinute

          void setMinute(@UInt8
                         byte minute)
                  throws IllegalArgumentException

      Sets the minutes component of the time value, in the range 0 to 59.

      Parameters:
        `minute` - Minutes component of the time value.
      Throws:
        `IllegalArgumentException` - The minute value is outside the acceptable range.

    - #### getSecond

          @UInt8
          byte getSecond()

      Returns the seconds component of the time value. Note that advanced implementations may allow for very occasional leap second values of 60 or 61.

      Returns:
        Seconds component of the time value.

    - #### setSecond

          void setSecond(@UInt8
                         byte second)
                  throws IllegalArgumentException

      Sets the second component of the time value, normally in the range 0 to 59. Note that advanced implementations may allow for very occasional leap second values of 60 or 61.

      Parameters:
        `second` - Seconds component of the time value.
      Throws:
        `IllegalArgumentException` - The second value is outside the acceptable range.

    - #### clone

          TimeStruct clone()

      Create a cloned copy of this time value.

      Returns:
        Cloned copy of this time value.

    - #### toString

          String toString()

      Formats a UTC-style string representation of the time structure's value, including the timezone offset. The format used is "`HH:mm:ss.SSSZ`", where:

      - "HH" is the two digit hour of the day in 24-hour clock;
      - "mm" is the two digit minute;
      - "ss" is the two digit second;
      - "SSS" is the three digital millisecond value to the nearest 1/250th of a second;
      - "Z" is the timezone offset from UTC, measure in positive or negative hours and minutes, e.g. "+0000" for GMT and "-0800" for PST.

      The representation created by this method can be converted back to a time value by the `Forge.parseTime(String)` method.

      Overrides:
        `toString` in class `Object`
      Returns:
        String representation of the time value according to the local time zone.
      See Also:
        `Forge.parseTime(String)`, `SimpleDateFormat`

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.