com.tomgibara.pronto.util
Class Duration

java.lang.Object
  com.tomgibara.pronto.util.Duration

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable

public final class Duration
extends java.lang.Object
implements java.lang.Comparable, java.io.Serializable

This class may be used to convert between a textual representation for a unit of time and its millisecond equivalent or vice versa. Instances are immutable and are safe for concurrent use.

The duration format parsable by this class consists of list of positively valued fields in descending order of unit magnitude. The recognized field units are:

• Days - unit: d, day or days
• Hours - unit: h, hr, hrs, hour, hours
• Minutes - unit: m, min, mins, minute, minutes
• Seconds - unit: s, sec, secs, second, seconds
• Milliseconds - unit: ms, milli, millis, millisecond, milliseconds

Spaces may appear between fields but not between numbers and units. Unit plurality is inconsequential. A string containing no units (eg. the empty string) may be used to represent zero milliseconds.

Examples of valid durations:

•     4days 10hours
   

  long units

•     10m2s500ms
   

  short units

•     10m2s500ms
   

  mixed units

•     2hour 1seconds
   

  inconsequential plurality

•     1day 25hrs
   

  value exceeding prior field

To convert a string into milliseconds:

 new Duration(str).getTime()
 

; to convert a time in milliseconds into a string:

 new Duration(time).toString()
 

.

Author:

Tom Gibara

See Also:

Serialized Form

Constructor Summary

Duration(long time)
Creates a duration from a number of milliseconds.

Duration(java.lang.String string)
Creates a duration from its string representation.

Method Summary

int	compareTo(java.lang.Object obj) Durations ordered by time.
boolean	equals(java.lang.Object obj) Equality is predicated on the millisecond time field.
long	getTime() The time which was passed to the constructor, or in the case that a string was supplied, the number of milliseconds to which the string equates.
int	hashCode()
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Duration

public Duration(java.lang.String string)
         throws java.lang.IllegalArgumentException

Creates a duration from its string representation.

Parameters:

string - the string representation of a duration

Throws:

java.lang.IllegalArgumentException - if the string is null or does not match the required format.

Duration

public Duration(long time)
         throws java.lang.IllegalArgumentException

Creates a duration from a number of milliseconds.

Parameters:

time - a time in milliseconds

Throws:

java.lang.IllegalArgumentException - if the supplied time is negative

Method Detail

getTime

public long getTime()

The time which was passed to the constructor, or in the case that a string was supplied, the number of milliseconds to which the string equates.

Returns:

the duration in milliseconds

compareTo

public int compareTo(java.lang.Object obj)

Durations ordered by time.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

obj - a duration object

Returns:

this is before, at or after obj

equals

public boolean equals(java.lang.Object obj)

Equality is predicated on the millisecond time field. That is, two durations are equal if the value returned from their getTime() methods is equal.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to test for equality

Returns:

whether both objects represent the same duration

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

Returns:

hashcode for this object based on the time

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

Returns:

the string which was passed to the constructor or, in the case that a time was supplied, a string which evalutes to an equal duration.