org.clapper.util.text
Class Duration

java.lang.Object
  org.clapper.util.text.Duration

public final class Duration
extends java.lang.Object

This class contains methods to parse and format time durations. A time duration is a string like "1 second", "10 minutes", "360 days", "4 hours, 30 seconds". This class can

• parse strings of that form to produce delta values (long integers)
• produce such strings by subtracting two dates or subtracting a date and a duration,
• add a duration to or subtract a duration from a Date, producing a new Date

The parser recognizes the following intervals and synonyms. (The names are in English; if resource bundles for other languages exist, the names will obviously be different.)

• milliseconds (millisecond, ms)
• seconds (seconds, sec, secs)
• minutes (minute, min, mins)
• hours (hour, hr, hrs)
• days (day)
• weeks (week)

Years and months are omitted to avoid the irregularity of leap years and different month lengths, respectively. Weeks are honored on input only.

Since:

org.clapper.util version 2.4.1

Version:

$Revision: 6687 $

Author:

Copyright © 2004-2007 Brian M. Clapper

Constructor Summary

Duration()
Default constructor.

Duration(java.util.Date date1, java.util.Date date2)
Create a new Duration object by determining the amount of time between two dates.

Duration(long milliseconds)
Create a new Duration object from a long integer representing some elapsed number of milliseconds.

Duration(java.lang.String s)
Create a new Duration object by parsing the specified duration string.

Duration(java.lang.String s, java.util.Locale locale)
Create a new Duration object by parsing the specified duration string.

Method Summary

java.lang.String	format() Format the duration value as a string, like the kind of string handled by the parse(java.lang.String) method.
java.lang.String	format(java.util.Locale locale) Format the duration value as a string, like the kind of string handled by the parse(java.lang.String) method.
long	getDuration() Get the stored duration value, in milliseconds.
void	parse(java.lang.String s) Parse a string containing a textual description of a duration, setting this object's value to the result of the parse.
void	parse(java.lang.String s, java.util.Locale locale) Parse a string containing a textual description of a duration, setting this object's value to the result of the parse.
java.lang.String	toString() Return a string representation of this duration.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Duration

public Duration()

Default constructor. Equivalent to Duration(0).

Duration

public Duration(long milliseconds)

Create a new Duration object from a long integer representing some elapsed number of milliseconds.

Parameters:

milliseconds - the elapsed milliseconds

Duration

public Duration(java.util.Date date1,
                java.util.Date date2)

Create a new Duration object by determining the amount of time between two dates.

Parameters:

date1 - the first date

date2 - the second date

Duration

public Duration(java.lang.String s,
                java.util.Locale locale)
         throws java.text.ParseException

Create a new Duration object by parsing the specified duration string. The words in the string are interpreted according to the specified locale. If this method cannot locate an appropriate resource bundle for the locale, it uses the default bundle (which may result in an exception).

Parameters:

s - the string to parse

locale - locale to use

Throws:

java.text.ParseException - bad string

Duration

public Duration(java.lang.String s)
         throws java.text.ParseException

Create a new Duration object by parsing the specified duration string. The current locale is used to interpret the strings.

Parameters:

s - the string to parse

Throws:

java.text.ParseException - bad string

Method Detail

getDuration

public long getDuration()

Get the stored duration value, in milliseconds.

Returns:

the stored duration value

format

public java.lang.String format()

Format the duration value as a string, like the kind of string handled by the parse(java.lang.String) method. This version formats the string using the default locale. For a complete description of what this method produces, see format(Locale).

Returns:

the formatted string

format

public java.lang.String format(java.util.Locale locale)

Format the duration value as a string, like the kind of string handled by the parse(java.lang.String) method. For instance, a duration value of 1 is formatted as "1 millisecond". A duration value of 86460000 is formatted as "1 day, 1 hour".

Parameters:

locale - Locale to use for the strings, or null for the default. If there's no bundle for the specified locale, English is used.

Returns:

the string

parse

public void parse(java.lang.String s)
           throws java.text.ParseException

Parse a string containing a textual description of a duration, setting this object's value to the result of the parse. This method parses the tokens using the default locale. See the version of parse() that takes a Locale parameter for a more complete explanation of the supported tokens.

Parameters:

s - the string to parse

Throws:

java.text.ParseException - parse error

parse

public void parse(java.lang.String s,
                  java.util.Locale locale)
           throws java.text.ParseException

Parse a string containing a textual description of a duration, setting this object's value to the result of the parse. The string contains one or more token pairs. The token pairs are separated by commas or white space. Each resulting token pair has a numeric token followed by a duration value. Examples will clarify:

• 3 days, 19 hours
• 12 minutes
• 1 hour, 10 minutes, 33 seconds, 5 milliseconds
• 5 minutes 3 seconds

Parameters:

s - the string to parse

locale - the locale to use when interpreting the tokens, or null for the default.

Throws:

java.text.ParseException - parse error

toString

public java.lang.String toString()

Return a string representation of this duration. Note that this method is not the same as the format() method. format() produces a natural language phrase, whereas toString() just returns the equivalent of String.valueOf(Duration.getDuration()).

Overrides:

toString in class java.lang.Object

Returns:

the stringified duration value