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
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static class
DurationFormatUtils.Token
Element that is parsed from the format pattern.
-
Field Summary
Fields Modifier and Type Field Description (package private) static java.lang.String
d
(package private) static java.lang.String
H
static java.lang.String
ISO_EXTENDED_FORMAT_PATTERN
Pattern used withFastDateFormat
andSimpleDateFormat
for the ISO 8601 period format used in durations.(package private) static java.lang.String
m
(package private) static java.lang.String
M
(package private) static java.lang.String
s
(package private) static java.lang.String
S
(package private) static java.lang.String
y
-
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 (package private) static java.lang.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.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.(package private) static DurationFormatUtils.Token[]
lexx(java.lang.String format)
Parses a classic date format string into Tokensprivate static java.lang.String
paddedValue(long value, boolean padWithZeros, int count)
Converts along
to aString
with optional zero padding.
-
-
-
Field Detail
-
ISO_EXTENDED_FORMAT_PATTERN
public static final java.lang.String ISO_EXTENDED_FORMAT_PATTERN
Pattern used with
FastDateFormat
andSimpleDateFormat
for the ISO 8601 period format used in durations.- See Also:
FastDateFormat
,SimpleDateFormat
, Constant Field Values
-
y
static final java.lang.String y
- See Also:
- Constant Field Values
-
M
static final java.lang.String M
- See Also:
- Constant Field Values
-
d
static final java.lang.String d
- See Also:
- Constant Field Values
-
H
static final java.lang.String H
- See Also:
- Constant Field Values
-
m
static final java.lang.String m
- See Also:
- Constant Field Values
-
s
static final java.lang.String s
- See Also:
- Constant Field Values
-
S
static final java.lang.String S
- See Also:
- 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
-
format
static java.lang.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 tokensyears
- the number of yearsmonths
- the number of monthsdays
- the number of dayshours
- the number of hoursminutes
- the number of minutesseconds
- the number of secondsmilliseconds
- the number of millispadWithZeros
- whether to pad- Returns:
- the formatted string
-
paddedValue
private static java.lang.String paddedValue(long value, boolean padWithZeros, int count)
Converts a
long
to aString
with optional zero padding.- Parameters:
value
- the value to convertpadWithZeros
- whether to pad with zeroescount
- the size to pad to (ignored ifpadWithZeros
is false)- Returns:
- the string result
-
lexx
static DurationFormatUtils.Token[] lexx(java.lang.String format)
Parses a classic date format string into Tokens- Parameters:
format
- the format to parse, not null- Returns:
- array of Token[]
-
-