Class DurationFormatUtils
| character | duration element |
|---|---|
| y | years |
| M | months |
| d | days |
| H | hours |
| m | minutes |
| s | seconds |
| S | milliseconds |
| 'text' | arbitrary text content |
| '' | literal single quote (apostrophe) |
'').
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 the following examples.
| 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 |
Note: Optional blocks cannot be nested.
- Since:
- 2.1
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static final classElement that is parsed from the format pattern. -
Field Summary
FieldsModifier and TypeFieldDescription(package private) static final String(package private) static final Stringprivate static final intstatic final StringPattern used withFastDateFormatandSimpleDateFormatfor the ISO 8601 period format used in durations.(package private) static final String(package private) static final Stringprivate static final int(package private) static final String(package private) static final Stringprivate static final int(package private) static final String -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription(package private) static Stringformat(DurationFormatUtils.Token[] tokens, long years, long months, long days, long hours, long minutes, long seconds, long milliseconds, boolean padWithZeros) The internal method to do the formatting.static 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.(package private) static DurationFormatUtils.Token[]Parses a classic date format string into Tokensprivate static longlocalEpochDay(Calendar calendar) Computes the local epoch day without overflowing at either end of the millisecond range.private static StringpaddedValue(long value, boolean padWithZeros, int count) Converts alongto aStringwith optional zero padding.
-
Field Details
-
MINUTES_PER_HOUR
private static final int MINUTES_PER_HOUR- See Also:
-
SECONDS_PER_MINUTES
private static final int SECONDS_PER_MINUTES- See Also:
-
HOURS_PER_DAY
private static final int HOURS_PER_DAY- See Also:
-
ISO_EXTENDED_FORMAT_PATTERN
Pattern used withFastDateFormatandSimpleDateFormatfor the ISO 8601 period format used in durations. -
y
- See Also:
-
M
- See Also:
-
d
- See Also:
-
H
- See Also:
-
m
- See Also:
-
s
- See Also:
-
S
- See Also:
-
-
Constructor Details
-
DurationFormatUtils
Deprecated.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
-
format
static String format(DurationFormatUtils.Token[] tokens, long years, long months, long days, long hours, long minutes, long seconds, long milliseconds, boolean padWithZeros) The internal method to do the formatting.- Parameters:
tokens- The tokens.years- The number of years.months- The number of months.days- The number of days.hours- The number of hours.minutes- The number of minutes.seconds- The number of seconds.milliseconds- The number of milliseconds.padWithZeros- whether to pad.- Returns:
- The formatted string.
-
formatDuration
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 format.format- The way in which to format the duration, not null.- Returns:
- The formatted duration, not null.
- Throws:
IllegalArgumentException- Thrown if durationMillis is negative.
-
formatDuration
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 format.format- The way in which to format the duration, not null.padWithZeros- whether to pad the left-hand side of numbers with 0's.- Returns:
- The formatted duration, not null.
- Throws:
IllegalArgumentException- Thrown if durationMillis is negative.
-
formatDurationHMS
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:
IllegalArgumentException- Thrown if durationMillis is negative.
-
formatDurationISO
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:
IllegalArgumentException- Thrown if durationMillis is negative.
-
formatDurationWords
public 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- Thrown if durationMillis is negative.
-
formatPeriod
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 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- Thrown if startMillis is greater than endMillis.
-
formatPeriod
public 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 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, borrowing the length of the month in which the period starts when the number of days would otherwise be negative. So when working out the number of months and days between January 15th and March 10th, it chooses 1 month and 26 days gained by choosing March -> February = 1 month and then calculating days backwards, and not the 1 month and 23 days gained by choosing January->February = 1 month and then calculating days forwards, as computed by
Period.between(java.time.LocalDate, java.time.LocalDate).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 of numbers with 0's.timezone- The millis are defined in.- Returns:
- The formatted duration, not null.
- Throws:
IllegalArgumentException- Thrown if startMillis is greater than endMillis.
-
formatPeriodISO
Formats 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- Thrown if startMillis is greater than endMillis.
-
lexx
Parses a classic date format string into Tokens- Parameters:
format- The format to parse, not null.- Returns:
- array of Token[].
-
localEpochDay
Computes the local epoch day without overflowing at either end of the millisecond range.- Parameters:
calendar- the calendar to convert.- Returns:
- the local epoch day.
-
paddedValue
Converts alongto aStringwith optional zero padding.- Parameters:
value- The value to convert.padWithZeros- whether to pad with zeroes.count- The size to pad to (ignored ifpadWithZerosis false).- Returns:
- The string result.
-