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

## ix.util
Class Duration

    java.lang.Object
      ix.util.Duration

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

    public class Duration

extends java.lang.Object
implements SemiPrimitive, java.lang.Comparable, java.io.Serializable

The difference between two dates. (There must be a decent Duration class out there somewhere, but I was unable to find it and so wrote this one. There is a lot that it doesn't do, but it allows durations to be created and to be output in a readable form. It also supports most of the XML Schema / ISO 8601 syntax for durations.)

Durations should be understood as periods of time without fixed endpoints, such as 10 minutes or 3 hours.

The full XML Schema duration datatype is difficult to work with, because the number of days in a month varies. Hence durations aren't even totally ordered. However, in the 1.1 version of the Schema definition, there are two derived types that are each totally ordered: yearMonthDuration and dayTimeDuration. That also means that full durations can be represented by two values: months and seconds. In the earlier 1.0 version, durations were in a 6-dimensional space: years, months, days, hours, minutes, and seconds. That had the unfortunate consequence that 1 day and 24 hours ("PT1D" and "PT24H") were considered different values rather than two (lexical) representations of the same value.

This class avoids some of the complexity by disallowing year and month values, thus making it close to the dayTimeDuration type. For long durations, the number of days can become large instead. However, this class retains the idea of a multi-dimensional space and instances needn't always have the number of hours be less than 24, the number of minutes less than 60, and so on. Users should not reply on the details of this class's behaviour in this area, because they are likely to change.

The canonical numeric representation of an instance of this class is as a long holding the total number of milliseconds in the period of time represented by the duration. The breakdown into days, hours, minutes, etc is normally visible only when a Duration is converted to a String.

See Also:
  Serialized Form

Nested Class Summary
`static class` | `Duration.SyntaxException` Describes a syntax error found when constructing a duration from a string.

Field Summary
`protected long` | `days`
`protected int` | `hours`
`protected LList` | `isoSequence`
`protected long` | `milliseconds`
`protected int` | `minutes`
`protected int` | `ms`
`protected boolean` | `negative`
`protected int` | `seconds`

Constructor Summary
`Duration(java.util.Date from, java.util.Date to)` Constructs a duration by taking the difference of two dates.
`Duration(long milliseconds)` Constructs a duration that corresponds to the specified number of milliseconds.
`Duration(long days, int hours, int minutes, int seconds, int ms)` Constructs a duration from the specified component times.
`Duration(java.lang.String isoString)` Constructs a duration from a string written in a subset of the ISO 8601 notation used for the XML Schema duration datatype.

Method Summary
`long` | `asMilliseconds()` Return the total number of milliseconds represented by this Duration.
`protected void` | `breakup(long total)` Separate the total milliseconds into days, hours, minutes, ...
`protected long` | `combine(long days, int hours, int minutes, int seconds, int ms)` Combine the components into a total number of milliseconds.
`int` | `compareTo(java.lang.Object obj)` Compares two durations.
`boolean` | `equals(java.lang.Object obj)` Determines whether two durations represent the same amount of time.
`int` | `hashCode()` Returns a hash value for this duration.
`static void` | `main(java.lang.String[] argv)` Simple test program.
`protected void` | `parseISOString(java.lang.String s)` Fills in fields in this duration by parsing a string that is written in the subset of ISO 8601 notation that is supported by this class.
`Duration` | `round(long granularity)` Returns this Duration after rounding the time to the nearest multiple of the specified granularity.
`Duration` | `roundToMinutes()` Equivalent to round(60 * 1000).
`Duration` | `roundToSeconds()` Equivalent to round(1000).
`java.lang.String` | `toISOString()` Returns a string that represents this duration in ISO 8601 syntax.
`java.lang.String` | `toString()` Returns an easy-to-read description of this duration.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### milliseconds

    protected long milliseconds

### negative

    protected boolean negative

### days

    protected long days

### hours

    protected int hours

### minutes

    protected int minutes

### seconds

    protected int seconds

### ms

    protected int ms

### isoSequence

    protected LList isoSequence

Constructor Detail

### Duration

    public Duration(java.util.Date from,
                    java.util.Date to)

  Constructs a duration by taking the difference of two dates. This is equivalent to

          new Duration(to.getTime() - from.getTime())

### Duration

    public Duration(long milliseconds)

  Constructs a duration that corresponds to the specified number of milliseconds. This is the inverse of the `asMilliseconds()` method. This constructor always produces a duration in which the number of hours is less than 24, the number of minutes is less than 60, and so on.

### Duration

    public Duration(long days,
                    int hours,
                    int minutes,
                    int seconds,
                    int ms)

  Constructs a duration from the specified component times.

### Duration

    public Duration(java.lang.String isoString)

  Constructs a duration from a string written in a subset of the ISO 8601 notation used for the XML Schema duration datatype.

  The full syntax is PnYnMnDTnHnMnS, optionally preceded by a minus sign, where each n is a possibly different unsigned number, 'Y', 'M', 'D', 'H', 'M, and 'S' stand for years, months, days, hours, minutes, and seconds respectively, 'P' stands for "period", and 'T' separates the year-month date portion from the time portion. 'P' must always be present, and 'T' must be present if any hours, minutes, or seconds are specified. The number-letter combinations are all optional, so long as at least one is specified. All of the numbers must have no decimal point except for the number of seconds. None of the numbers is restricted in range.

  This class does not support year or month values and they must not be given. Second fractions are stored only to the nearest millisecond, although they can be written to arbitrary precision.

  Throws:
    `Duration.SyntaxException` - if the string does not conform to the required syntax.
  See Also:
    `toISOString()`, `parseISOString(String)`

Method Detail

### breakup

    protected void breakup(long total)

  Separate the total milliseconds into days, hours, minutes, ...

### combine

    protected long combine(long days,
                           int hours,
                           int minutes,
                           int seconds,
                           int ms)

  Combine the components into a total number of milliseconds.

### round

    public Duration round(long granularity)

  Returns this Duration after rounding the time to the nearest multiple of the specified granularity. For example, to create a duration rounded to the nearest minute, you could do

         Duration d = new Duration(...).round(60 * 1000);

  Parameters:
    `granularity` - milliseconds, usually a value that represents one larger unit such as a day, hour, or minute.
  See Also:
    `roundToSeconds()`, `roundToMinutes()`

### roundToSeconds

    public Duration roundToSeconds()

  Equivalent to round(1000).

### roundToMinutes

    public Duration roundToMinutes()

  Equivalent to round(60 * 1000).

### asMilliseconds

    public long asMilliseconds()

  Return the total number of milliseconds represented by this Duration. This method is the inverse of the `Duration(long)` constructor.

### toISOString

    public java.lang.String toISOString()

  Returns a string that represents this duration in ISO 8601 syntax. This method is a rough inverse of the `Duration(String)` constructor. It will return only strings that can be parsed by that constructor, but if s is the string returned for this duration, it is not absolutely guaranteed that

          new Duration(s).toISOString().equals(s)

  However, this duration and one greated from s will have the same value as milliseconds.

  See Also:
    `toString()`

### parseISOString

    protected void parseISOString(java.lang.String s)

  Fills in fields in this duration by parsing a string that is written in the subset of ISO 8601 notation that is supported by this class. This method is called by the `Duration(String)` constructor.

  Throws:
    `Duration.SyntaxException` - if the string does not conform to the required syntax.

### toString

    public java.lang.String toString()

  Returns an easy-to-read description of this duration. For example, `"10 days, 23 hours, 1 minute"`.

  Overrides:
    `toString` in class `java.lang.Object`
  See Also:
    `toISOString()`

### hashCode

    public int hashCode()

  Returns a hash value for this duration. This is computed as the exclusive OR of the two halves of the number of milliseconds in this duration represented as a long.

  Overrides:
    `hashCode` in class `java.lang.Object`

### equals

    public boolean equals(java.lang.Object obj)

  Determines whether two durations represent the same amount of time.

  Overrides:
    `equals` in class `java.lang.Object`
  Returns:
    true if the argument duration represents the same amount of time as this duration and false if it does not.
  Throws:
    `java.lang.ClassCastException` - if the argument is not a Duration.

### compareTo

    public int compareTo(java.lang.Object obj)

  Compares two durations.

  Specified by:
    `compareTo` in interface `java.lang.Comparable`
  Returns:
    0 if the durations are equal, a value less than 0 if this duration is a shorter time than the argument duration, and a value greater than 0 if this duration is longer than the argument duration.
  Throws:
    `java.lang.ClassCastException` - if the argument is not a Duration.

### main

    public static void main(java.lang.String[] argv)

  Simple test program.

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