Class DurationFormatUtils
| 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.
Tokens can be marked as optional by surrounding them with brackets [ ]. These tokens will only be printed if the token value is non-zero. Literals within optional blocks will only be printed if the preceding non-literal token is non-zero. Leading optional literals will only be printed if the following non-literal is non-zero. Multiple optional blocks can be used to group literals with the desired token.
 Notes on Optional Tokens:
 Multiple optional tokens without literals can result in impossible to understand output.
 Patterns where all tokens are optional can produce empty strings.
 (See examples below)
 
| pattern | Duration.ofDays(1) | Duration.ofHours(1) | Duration.ofMinutes(1) | Duration.ZERO | 
|---|---|---|---|---|
| d'd'H'h'm'm's's' | 1d0h0m0s | 0d1h0m0s | 0d0h1m0s | 0d0h0m0s | 
| d'd'[H'h'm'm']s's' | 1d0s | 0d1h0s | 0d1m0s | 0d0s | 
| [d'd'H'h'm'm']s's' | 1d0s | 1h0s | 1m0s | 0s | 
| [d'd'H'h'm'm's's'] | 1d | 1h | 1m | |
| ['{'d'}']HH':'mm | {1}00:00 | 01:00 | 00:01 | 00:00 | 
| ['{'dd'}']['<'HH'>']['('mm')'] | {01} | <01> | (00) | |
| [dHms] | 1 | 1 | 1 | 
- Since:
- 2.1
- 
Field SummaryFieldsModifier and TypeFieldDescriptionstatic final StringPattern used withFastDateFormatandSimpleDateFormatfor the ISO 8601 period format used in durations.
- 
Constructor SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionstatic StringformatDuration(long durationMillis, String format) Formats the time gap as a string, using the specified format, and padding with zeros.static StringformatDuration(long durationMillis, String format, boolean padWithZeros) Formats the time gap as a string, using the specified format.static StringformatDurationHMS(long durationMillis) Formats the time gap as a string.static StringformatDurationISO(long durationMillis) Formats the time gap as a string.static StringformatDurationWords(long durationMillis, boolean suppressLeadingZeroElements, boolean suppressTrailingZeroElements) Formats an elapsed time into a pluralization correct string.static StringformatPeriod(long startMillis, long endMillis, String format) Formats the time gap as a string, using the specified format.static StringformatPeriod(long startMillis, long endMillis, String format, boolean padWithZeros, TimeZone timezone) Formats the time gap as a string, using the specified format.static StringformatPeriodISO(long startMillis, long endMillis) Formats the time gap as a string.
- 
Field Details- 
ISO_EXTENDED_FORMAT_PATTERNPattern used withFastDateFormatandSimpleDateFormatfor the ISO 8601 period format used in durations.
 
- 
- 
Constructor Details- 
DurationFormatUtilsDeprecated.TODO Make private in 4.0.DurationFormatUtils instances should NOT be constructed in standard programming.This constructor is public to permit tools that require a JavaBean instance to operate. 
 
- 
- 
Method Details- 
formatDurationFormats 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 format
- format- the way in which to format the duration, not null
- Returns:
- the formatted duration, not null
- Throws:
- IllegalArgumentException- if durationMillis is negative
 
- 
formatDurationFormats the time gap as a string, using the specified format. Padding the left-hand side 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 format
- format- the way in which to format the duration, not null
- padWithZeros- whether to pad the left-hand side side of numbers with 0's
- Returns:
- the formatted duration, not null
- Throws:
- IllegalArgumentException- if durationMillis is negative
 
- 
formatDurationHMSFormats 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:
- IllegalArgumentException- if durationMillis is negative
 
- 
formatDurationISOFormats 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:
- IllegalArgumentException- if durationMillis is negative
 
- 
formatDurationWordspublic static 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 milliseconds
- suppressLeadingZeroElements- suppresses leading 0 elements
- suppressTrailingZeroElements- suppresses trailing 0 elements
- Returns:
- the formatted text in days/hours/minutes/seconds, not null
- Throws:
- IllegalArgumentException- if durationMillis is negative
 
- 
formatPeriodFormats the time gap as a string, using the specified format. Padding the left-hand side side of numbers with zeroes is optional.- Parameters:
- startMillis- the start of the duration
- endMillis- the end of the duration
- format- the way in which to format the duration, not null
- Returns:
- the formatted duration, not null
- Throws:
- IllegalArgumentException- if startMillis is greater than endMillis
 
- 
formatPeriodpublic static String formatPeriod(long startMillis, long endMillis, String format, boolean padWithZeros, TimeZone timezone) Formats the time gap as a string, using the specified format. Padding the left-hand side 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 duration
- endMillis- the end of the duration
- format- the way in which to format the duration, not null
- padWithZeros- whether to pad the left-hand side side of numbers with 0's
- timezone- the millis are defined in
- Returns:
- the formatted duration, not null
- Throws:
- IllegalArgumentException- if startMillis is greater than endMillis
 
- 
formatPeriodISOFormats the time gap as a string.The format used is the ISO 8601 period format. - Parameters:
- startMillis- the start of the duration to format
- endMillis- the end of the duration to format
- Returns:
- the formatted duration, not null
- Throws:
- IllegalArgumentException- if startMillis is greater than endMillis
 
 
-