Package org.apache.commons.lang3.time

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

Note: It's not currently possible to include a single-quote in a format.
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)

Example Output

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 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
private static int	HOURS_PER_DAY
static java.lang.String	ISO_EXTENDED_FORMAT_PATTERN	Pattern used with FastDateFormat and SimpleDateFormat for the ISO 8601 period format used in durations.
(package private) static java.lang.String	m
(package private) static java.lang.String	M
private static int	MINUTES_PER_HOUR
(package private) static java.lang.String	s
(package private) static java.lang.String	S
private static int	SECONDS_PER_MINUTES
(package private) static java.lang.String	y

Constructor Summary

Constructors

Constructor	Description
DurationFormatUtils()	Deprecated. TODO Make private in 4.0.

Method Summary

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 Tokens
private static java.lang.String	paddedValue(long value, boolean padWithZeros, int count)	Converts a long to a String with optional zero padding.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MINUTES_PER_HOUR

private static final int MINUTES_PER_HOUR

See Also:

Constant Field Values

SECONDS_PER_MINUTES

private static final int SECONDS_PER_MINUTES

See Also:

Constant Field Values

HOURS_PER_DAY

private static final int HOURS_PER_DAY

See Also:

Constant Field Values

ISO_EXTENDED_FORMAT_PATTERN

public static final java.lang.String ISO_EXTENDED_FORMAT_PATTERN

Pattern used with FastDateFormat and SimpleDateFormat 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

Constructor Detail

DurationFormatUtils

@Deprecated
public 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 Detail

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 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 millis

padWithZeros - whether to pad

Returns:

the formatted string

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 format

format - 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 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:

java.lang.IllegalArgumentException - if durationMillis is negative

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

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 milliseconds

suppressLeadingZeroElements - suppresses leading 0 elements

suppressTrailingZeroElements - suppresses trailing 0 elements

Returns:

the formatted text in days/hours/minutes/seconds, not null

Throws:

java.lang.IllegalArgumentException - if durationMillis is negative

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 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:

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 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:

java.lang.IllegalArgumentException - if startMillis is greater than endMillis

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 format

endMillis - the end of the duration to format

Returns:

the formatted duration, not null

Throws:

java.lang.IllegalArgumentException - if startMillis is greater than endMillis

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[]

paddedValue

private static java.lang.String paddedValue(long value,
                                            boolean padWithZeros,
                                            int count)

Converts a long to a String with optional zero padding.

Parameters:

value - the value to convert

padWithZeros - whether to pad with zeroes

count - the size to pad to (ignored if padWithZeros is false)

Returns:

the string result