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.