| A duration is an immutable length of time stored as a number of milliseconds.
Various factory and conversion methods are available for convenience.
These static factory methods allow easy construction of value objects using
either long values like seconds(2034) or hours(3):
- Duration.milliseconds(long)
- Duration.seconds(int)
- Duration.minutes(int)
- Duration.hours(int)
- Duration.days(int)
or double precision floating point values like days(3.2):
- Duration.milliseconds(double)
- Duration.seconds(double)
- Duration.minutes(double)
- Duration.hours(double)
- Duration.days(double)
In the case of milliseconds(double), the value will be rounded off to the
nearest integral millisecond using Math.round().
The precise number of milliseconds represented by a Duration object can be
retrieved by calling the milliseconds() method. The value of a Duration
object in a given unit like days or hours can be retrieved by calling one of
the following unit methods, each of which returns a double precision floating
point number:
- seconds()
- minutes()
- hours()
- days()
Values can be added and subtracted using the add() and subtract() methods,
each of which returns a new immutable Duration object.
String values can be converted to Duration objects using the static valueOf
factory methods. The string format is the opposite of the one created by
toString(), which converts a Duration object to a readable form, such as "3.2
hours" or "32.5 minutes". Valid units are: milliseconds, seconds, minutes
hours and days. Correct English plural forms are used in creating string
values and are parsed as well. The Locale is respected and "," will be used
instead of "." in the Eurozone.
The benchmark method will "benchmark" a Runnable or an ICode implementing
object, returning a Duration object that represents the amount of time
elapsed in running the code.
Finally, the sleep() method will sleep for the value of a Duration.
author:
Jonathan Locke | 