Class DurationFormatUtils
- java.lang.Object
-
- org.apache.commons.lang3.time.DurationFormatUtils
-
public class DurationFormatUtils extends java.lang.Object
Duration formatting utilities and constants. The following table describes the tokens used in the pattern language for formatting.Pattern Tokens character duration element y years M months d days H hours m minutes s seconds S milliseconds 'text' arbitrary text content
Token values are printed using decimal digits. A token character can be repeated to ensure that the field occupies a certain minimum size. Values will be left-padded with 0 unless padding is disabled in the method invocation.- Since:
- 2.1
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
ISO_EXTENDED_FORMAT_PATTERN
Pattern used withFastDateFormat
andSimpleDateFormat
for the ISO 8601 period format used in durations.
-
Constructor Summary
Constructors Constructor Description DurationFormatUtils()
DurationFormatUtils instances should NOT be constructed in standard programming.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static java.lang.String
formatDuration(long durationMillis, java.lang.String format)
Formats the time gap as a string, using the specified format, and padding with zeros.static java.lang.String
formatDuration(long durationMillis, java.lang.String format, boolean padWithZeros)
Formats the time gap as a string, using the specified format.static java.lang.String
formatDurationHMS(long durationMillis)
Formats the time gap as a string.static java.lang.String
formatDurationISO(long durationMillis)
Formats the time gap as a string.static java.lang.String
formatDurationWords(long durationMillis, boolean suppressLeadingZeroElements, boolean suppressTrailingZeroElements)
Formats an elapsed time into a pluralization correct string.static java.lang.String
formatPeriod(long startMillis, long endMillis, java.lang.String format)
Formats the time gap as a string, using the specified format.static java.lang.String
formatPeriod(long startMillis, long endMillis, java.lang.String format, boolean padWithZeros, java.util.TimeZone timezone)
Formats the time gap as a string, using the specified format.static java.lang.String
formatPeriodISO(long startMillis, long endMillis)
Formats the time gap as a string.
-
-
-
Field Detail
-
ISO_EXTENDED_FORMAT_PATTERN
public static final java.lang.String ISO_EXTENDED_FORMAT_PATTERN
Pattern used withFastDateFormat
andSimpleDateFormat
for the ISO 8601 period format used in durations.- See Also:
FastDateFormat
,SimpleDateFormat
, Constant Field Values
-
-
Method Detail
-
formatDurationHMS
public static java.lang.String formatDurationHMS(long durationMillis)
Formats the time gap as a string.The format used is ISO 8601-like:
HH:mm:ss.SSS
.- Parameters:
durationMillis
- the duration to format- Returns:
- the formatted duration, not null
- Throws:
java.lang.IllegalArgumentException
- if durationMillis is negative
-
formatDurationISO
public static java.lang.String formatDurationISO(long durationMillis)
Formats the time gap as a string.The format used is the ISO 8601 period format.
This method formats durations using the days and lower fields of the ISO format pattern, such as P7D6TH5M4.321S.
- Parameters:
durationMillis
- the duration to format- Returns:
- the formatted duration, not null
- Throws:
java.lang.IllegalArgumentException
- if durationMillis is negative
-
formatDuration
public static java.lang.String formatDuration(long durationMillis, java.lang.String format)
Formats the time gap as a string, using the specified format, and padding with zeros.This method formats durations using the days and lower fields of the format pattern. Months and larger are not used.
- Parameters:
durationMillis
- the duration to formatformat
- the way in which to format the duration, not null- Returns:
- the formatted duration, not null
- Throws:
java.lang.IllegalArgumentException
- if durationMillis is negative
-
formatDuration
public static java.lang.String formatDuration(long durationMillis, java.lang.String format, boolean padWithZeros)
Formats the time gap as a string, using the specified format. Padding the left-hand side of numbers with zeroes is optional.This method formats durations using the days and lower fields of the format pattern. Months and larger are not used.
- Parameters:
durationMillis
- the duration to formatformat
- the way in which to format the duration, not nullpadWithZeros
- whether to pad the left-hand side of numbers with 0's- Returns:
- the formatted duration, not null
- Throws:
java.lang.IllegalArgumentException
- if durationMillis is negative
-
formatDurationWords
public static java.lang.String formatDurationWords(long durationMillis, boolean suppressLeadingZeroElements, boolean suppressTrailingZeroElements)
Formats an elapsed time into a pluralization correct string.This method formats durations using the days and lower fields of the format pattern. Months and larger are not used.
- Parameters:
durationMillis
- the elapsed time to report in millisecondssuppressLeadingZeroElements
- suppresses leading 0 elementssuppressTrailingZeroElements
- suppresses trailing 0 elements- Returns:
- the formatted text in days/hours/minutes/seconds, not null
- Throws:
java.lang.IllegalArgumentException
- if durationMillis is negative
-
formatPeriodISO
public static java.lang.String formatPeriodISO(long startMillis, long endMillis)
Formats the time gap as a string.The format used is the ISO 8601 period format.
- Parameters:
startMillis
- the start of the duration to formatendMillis
- the end of the duration to format- Returns:
- the formatted duration, not null
- Throws:
java.lang.IllegalArgumentException
- if startMillis is greater than endMillis
-
formatPeriod
public static java.lang.String formatPeriod(long startMillis, long endMillis, java.lang.String format)
Formats the time gap as a string, using the specified format. Padding the left-hand side of numbers with zeroes is optional.- Parameters:
startMillis
- the start of the durationendMillis
- the end of the durationformat
- the way in which to format the duration, not null- Returns:
- the formatted duration, not null
- Throws:
java.lang.IllegalArgumentException
- if startMillis is greater than endMillis
-
formatPeriod
public static java.lang.String formatPeriod(long startMillis, long endMillis, java.lang.String format, boolean padWithZeros, java.util.TimeZone timezone)
Formats the time gap as a string, using the specified format. Padding the left-hand side of numbers with zeroes is optional and the time zone may be specified.
When calculating the difference between months/days, it chooses to calculate months first. So when working out the number of months and days between January 15th and March 10th, it choose 1 month and 23 days gained by choosing January->February = 1 month and then calculating days forwards, and not the 1 month and 26 days gained by choosing March -> February = 1 month and then calculating days backwards.
For more control, the Joda-Time library is recommended.
- Parameters:
startMillis
- the start of the durationendMillis
- the end of the durationformat
- the way in which to format the duration, not nullpadWithZeros
- whether to pad the left-hand side of numbers with 0'stimezone
- the millis are defined in- Returns:
- the formatted duration, not null
- Throws:
java.lang.IllegalArgumentException
- if startMillis is greater than endMillis
-
-