Pattern Tokens
character	duration element
y	years
M	months
d	days
H	hours
m	minutes
s	seconds
S	milliseconds
'text'	arbitrary text content

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

Modifier and Type	Class and Description
pack-priv static class	DurationFormatUtils.Token Element that is parsed from the format pattern.

Modifier and Type	Field and Description
pack-priv static final String	d
pack-priv static final String	H
private static final int	HOURS_PER_DAY
public static final String	ISO_EXTENDED_FORMAT_PATTERN Pattern used with `FastDateFormat` and `SimpleDateFormat` for the ISO 8601 period format used in durations.
pack-priv static final String	M
pack-priv static final String	m
private static final int	MINUTES_PER_HOUR
pack-priv static final String	s
pack-priv static final String	S
private static final int	SECONDS_PER_MINUTES
pack-priv static final String	y

Access	Constructor and Description
public	DurationFormatUtils() Deprecated TODO Make private in 4.0. DurationFormatUtils instances should NOT be constructed in standard programming.

Method Summary

Modifier and Type	Method and Description
pack-priv static String	Returns: the formatted string format(final DurationFormatUtils.Token[] the tokens tokens, final long the number of years years, final long the number of months months, final long the number of days days, final long the number of hours hours, final long the number of minutes minutes, final long the number of seconds seconds, final long the number of millis milliseconds, final boolean whether to pad padWithZeros) The internal method to do the formatting.
public static String	Returns: the formatted duration, not null formatDuration(final long the duration to format durationMillis, final String the way in which to format the duration, not null format) Formats the time gap as a string, using the specified format, and padding with zeros.
public static String	Returns: the formatted duration, not null formatDuration(final long the duration to format durationMillis, final String the way in which to format the duration, not null format, final boolean whether to pad the left-hand side side of numbers with 0's padWithZeros) Formats the time gap as a string, using the specified format.
public static String	Returns: the formatted duration, not null formatDurationHMS(final long the duration to format durationMillis) Formats the time gap as a string.
public static String	Returns: the formatted duration, not null formatDurationISO(final long the duration to format durationMillis) Formats the time gap as a string.
public static String	Returns: the formatted text in days/hours/minutes/seconds, not null formatDurationWords(final long the elapsed time to report in milliseconds durationMillis, final boolean suppresses leading 0 elements suppressLeadingZeroElements, final boolean suppresses trailing 0 elements suppressTrailingZeroElements) Formats an elapsed time into a pluralization correct string.
public static String	Returns: the formatted duration, not null formatPeriod(final long the start of the duration startMillis, final long the end of the duration endMillis, final String the way in which to format the duration, not null format) Formats the time gap as a string, using the specified format.
public static String	Returns: the formatted duration, not null formatPeriod(final long the start of the duration startMillis, final long the end of the duration endMillis, final String the way in which to format the duration, not null format, final boolean whether to pad the left-hand side side of numbers with 0's padWithZeros, final TimeZone the millis are defined in timezone) Formats the time gap as a string, using the specified format.
public static String	Returns: the formatted duration, not null formatPeriodISO(final long the start of the duration to format startMillis, final long the end of the duration to format endMillis) Formats the time gap as a string.
pack-priv static DurationFormatUtils.Token[]	Returns: array of Token[] lexx(final String the format to parse, not null format) Parses a classic date format string into Tokens
private static String	Returns: the string result paddedValue(final long the value to convert value, final boolean whether to pad with zeroes padWithZeros, final int the size to pad to (ignored if `padWithZeros` is false) count) Converts a `long` to a `String` with optional zero padding.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

d	back to summary
pack-priv static final String d

H	back to summary
pack-priv static final String H

HOURS_PER_DAY	back to summary
private static final int HOURS_PER_DAY

ISO_EXTENDED_FORMAT_PATTERN back to summary

ISO_EXTENDED_FORMAT_PATTERN	back to summary
public static final String ISO_EXTENDED_FORMAT_PATTERN Pattern used with `FastDateFormat` and `SimpleDateFormat` for the ISO 8601 period format used in durations. See Also `org.apache.commons.lang3.time.FastDateFormat`, `java.text.SimpleDateFormat`

public static final String ISO_EXTENDED_FORMAT_PATTERN

Pattern used with FastDateFormat and SimpleDateFormat for the ISO 8601 period format used in durations.

See Also: org.apache.commons.lang3.time.FastDateFormat, java.text.SimpleDateFormat

M	back to summary
pack-priv static final String M

m	back to summary
pack-priv static final String m

MINUTES_PER_HOUR	back to summary
private static final int MINUTES_PER_HOUR

s	back to summary
pack-priv static final String s

S	back to summary
pack-priv static final String S

SECONDS_PER_MINUTES	back to summary
private static final int SECONDS_PER_MINUTES

y	back to summary
pack-priv static final String y

Constructor Detail

DurationFormatUtils	back to summary
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. Annotations @Deprecated

DurationFormatUtils

back to summary

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.

Annotations

@Deprecated

Method Detail

format	back to summary
pack-priv static String format(final DurationFormatUtils.Token[] tokens, final long years, final long months, final long days, final long hours, final long minutes, final long seconds, final long milliseconds, final boolean padWithZeros) The internal method to do the formatting. Parameters tokens:DurationFormatUtils.Token[] the tokens years:long the number of years months:long the number of months days:long the number of days hours:long the number of hours minutes:long the number of minutes seconds:long the number of seconds milliseconds:long the number of millis padWithZeros:boolean whether to pad Returns:String the formatted string

format

back to summary

pack-priv static String format(final DurationFormatUtils.Token[] tokens, final long years, final long months, final long days, final long hours, final long minutes, final long seconds, final long milliseconds, final boolean padWithZeros)

The internal method to do the formatting.

Parameters

tokens:DurationFormatUtils.Token[]: the tokens
years:long: the number of years
months:long: the number of months
days:long: the number of days
hours:long: the number of hours
minutes:long: the number of minutes
seconds:long: the number of seconds
milliseconds:long: the number of millis
padWithZeros:boolean: whether to pad

Returns:String

the formatted string

formatDuration	back to summary
public static String formatDuration(final long durationMillis, final 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:long the duration to format format:String the way in which to format the duration, not null Returns:String the formatted duration, not null Exceptions IllegalArgumentException: if durationMillis is negative

formatDuration

back to summary

public static String formatDuration(final long durationMillis, final 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:long: the duration to format
format:String: the way in which to format the duration, not null

Returns:String

the formatted duration, not null

Exceptions

IllegalArgumentException:: if durationMillis is negative

formatDuration	back to summary
public static String formatDuration(final long durationMillis, final String format, final 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:long the duration to format format:String the way in which to format the duration, not null padWithZeros:boolean whether to pad the left-hand side side of numbers with 0's Returns:String the formatted duration, not null Exceptions IllegalArgumentException: if durationMillis is negative

formatDuration

back to summary

public static String formatDuration(final long durationMillis, final String format, final 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:long: the duration to format
format:String: the way in which to format the duration, not null
padWithZeros:boolean: whether to pad the left-hand side side of numbers with 0's

Returns:String

the formatted duration, not null

Exceptions

IllegalArgumentException:: if durationMillis is negative

formatDurationHMS back to summary

formatDurationHMS	back to summary
public static String formatDurationHMS(final long durationMillis) Formats the time gap as a string. The format used is ISO 8601-like: `HH:mm:ss.SSS`. Parameters durationMillis:long the duration to format Returns:String the formatted duration, not null Exceptions IllegalArgumentException: if durationMillis is negative

public static String formatDurationHMS(final long durationMillis)

Formats the time gap as a string.

The format used is ISO 8601-like: HH:mm:ss.SSS.

Parameters

durationMillis:long: the duration to format

Returns:String

the formatted duration, not null

Exceptions

IllegalArgumentException:: if durationMillis is negative

formatDurationISO	back to summary
public static String formatDurationISO(final 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:long the duration to format Returns:String the formatted duration, not null Exceptions IllegalArgumentException: if durationMillis is negative

formatDurationISO

back to summary

public static String formatDurationISO(final 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:long: the duration to format

Returns:String

the formatted duration, not null

Exceptions

IllegalArgumentException:: if durationMillis is negative

formatDurationWords	back to summary
public static String formatDurationWords(final long durationMillis, final boolean suppressLeadingZeroElements, final 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:long the elapsed time to report in milliseconds suppressLeadingZeroElements:boolean suppresses leading 0 elements suppressTrailingZeroElements:boolean suppresses trailing 0 elements Returns:String the formatted text in days/hours/minutes/seconds, not null Exceptions IllegalArgumentException: if durationMillis is negative

formatDurationWords

back to summary

public static String formatDurationWords(final long durationMillis, final boolean suppressLeadingZeroElements, final 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:long: the elapsed time to report in milliseconds
suppressLeadingZeroElements:boolean: suppresses leading 0 elements
suppressTrailingZeroElements:boolean: suppresses trailing 0 elements

Returns:String

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

Exceptions

IllegalArgumentException:: if durationMillis is negative

formatPeriod	back to summary
public static String formatPeriod(final long startMillis, final long endMillis, final 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:long the start of the duration endMillis:long the end of the duration format:String the way in which to format the duration, not null Returns:String the formatted duration, not null Exceptions IllegalArgumentException: if startMillis is greater than endMillis

formatPeriod

back to summary

public static String formatPeriod(final long startMillis, final long endMillis, final 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:long: the start of the duration
endMillis:long: the end of the duration
format:String: the way in which to format the duration, not null

Returns:String

the formatted duration, not null

Exceptions

IllegalArgumentException:: if startMillis is greater than endMillis

formatPeriod	back to summary
public static String formatPeriod(final long startMillis, final long endMillis, final String format, final boolean padWithZeros, final 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:long the start of the duration endMillis:long the end of the duration format:String the way in which to format the duration, not null padWithZeros:boolean whether to pad the left-hand side side of numbers with 0's timezone:TimeZone the millis are defined in Returns:String the formatted duration, not null Exceptions IllegalArgumentException: if startMillis is greater than endMillis

formatPeriod

back to summary

public static String formatPeriod(final long startMillis, final long endMillis, final String format, final boolean padWithZeros, final 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:long: the start of the duration
endMillis:long: the end of the duration
format:String: the way in which to format the duration, not null
padWithZeros:boolean: whether to pad the left-hand side side of numbers with 0's
timezone:TimeZone: the millis are defined in

Returns:String

the formatted duration, not null

Exceptions

IllegalArgumentException:: if startMillis is greater than endMillis

formatPeriodISO	back to summary
public static String formatPeriodISO(final long startMillis, final long endMillis) Formats the time gap as a string. The format used is the ISO 8601 period format. Parameters startMillis:long the start of the duration to format endMillis:long the end of the duration to format Returns:String the formatted duration, not null Exceptions IllegalArgumentException: if startMillis is greater than endMillis

formatPeriodISO

back to summary

public static String formatPeriodISO(final long startMillis, final long endMillis)

Formats the time gap as a string.

The format used is the ISO 8601 period format.

Parameters

startMillis:long: the start of the duration to format
endMillis:long: the end of the duration to format

Returns:String

the formatted duration, not null

Exceptions

IllegalArgumentException:: if startMillis is greater than endMillis

lexx	back to summary
pack-priv static DurationFormatUtils.Token[] lexx(final String format) Parses a classic date format string into Tokens Parameters format:String the format to parse, not null Returns:DurationFormatUtils.Token[] array of Token[]

lexx

back to summary

pack-priv static DurationFormatUtils.Token[] lexx(final String format)

Parses a classic date format string into Tokens

Parameters

format:String: the format to parse, not null

Returns:DurationFormatUtils.Token[]

array of Token[]

paddedValue back to summary

paddedValue	back to summary
private static String paddedValue(final long value, final boolean padWithZeros, final int count) Converts a `long` to a `String` with optional zero padding. Parameters value:long the value to convert padWithZeros:boolean whether to pad with zeroes count:int the size to pad to (ignored if `padWithZeros` is false) Returns:String the string result

private static String paddedValue(final long value, final boolean padWithZeros, final int count)

Converts a long to a String with optional zero padding.

Parameters

value:long: the value to convert
padWithZeros:boolean: whether to pad with zeroes
count:int: the size to pad to (ignored if padWithZeros is false)

Returns:String

the string result

org.apache.commons.lang3.time back to summary

pack-priv final Class DurationFormatUtils.Token

Class Inheritance

extends Object

java.lang.Object
org.apache.commons.lang3.time.DurationFormatUtils.Token

Element that is parsed from the format pattern.

Field Summary

Modifier and Type	Field and Description
private int	count
private static final DurationFormatUtils.Token[]	EMPTY_ARRAY Empty array.
private int	optionalIndex
private final CharSequence	value

Constructor Summary

Access	Constructor and Description
pack-priv	Token(final CharSequence value to wrap, non-null. value, final boolean whether the token is optional optional, final int the index of the optional token within the pattern optionalIndex) Wraps a token around a value.

Method Summary

Modifier and Type	Method and Description
pack-priv static boolean	Returns: boolean `true` if contained containsTokenWithValue(final DurationFormatUtils.Token[] set to look in tokens, final Object to look for value) Helper method to determine if a set of tokens contain a value
public boolean	Returns: boolean `true` if equal equals(final Object Object to consider equality of obj2) Overrides java.lang.Object.equals. Supports equality of this Token to another Token.
pack-priv int	Returns: int number of values represented getCount() Gets the current number of values represented
pack-priv Object	Returns: Object value, non-null. getValue() Gets the particular value this token represents.
public int	Returns: The hash code for the token hashCode() Overrides java.lang.Object.hashCode. Returns a hash code for the token equal to the hash code for the token's value.
pack-priv void	increment() Adds another one of the value
public String	Returns: String representation of the token toString() Overrides java.lang.Object.toString. Represents this token as a String.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll wait wait wait

Field Detail

count	back to summary
private int count

EMPTY_ARRAY	back to summary
private static final DurationFormatUtils.Token[] EMPTY_ARRAY Empty array.

optionalIndex	back to summary
private int optionalIndex

value	back to summary
private final CharSequence value

Constructor Detail

Token	back to summary
pack-priv Token(final CharSequence value, final boolean optional, final int optionalIndex) Wraps a token around a value. A value would be something like a 'Y'. Parameters value:CharSequence value to wrap, non-null. optional:boolean whether the token is optional optionalIndex:int the index of the optional token within the pattern

Token

back to summary

pack-priv Token(final CharSequence value, final boolean optional, final int optionalIndex)

Wraps a token around a value. A value would be something like a 'Y'.

Parameters

value:CharSequence: value to wrap, non-null.
optional:boolean: whether the token is optional
optionalIndex:int: the index of the optional token within the pattern

Method Detail

containsTokenWithValue back to summary

containsTokenWithValue	back to summary
pack-priv static boolean containsTokenWithValue(final DurationFormatUtils.Token[] tokens, final Object value) Helper method to determine if a set of tokens contain a value Parameters tokens:DurationFormatUtils.Token[] set to look in value:Object to look for Returns:boolean boolean `true` if contained

pack-priv static boolean containsTokenWithValue(final DurationFormatUtils.Token[] tokens, final Object value)

Helper method to determine if a set of tokens contain a value

Parameters

tokens:DurationFormatUtils.Token[]: set to look in
value:Object: to look for

Returns:boolean

boolean true if contained

equals back to summary

equals	back to summary
public boolean equals(final Object obj2) Overrides java.lang.Object.equals. Supports equality of this Token to another Token. Parameters obj2:Object Object to consider equality of Returns:boolean boolean `true` if equal Annotations @Override

public boolean equals(final Object obj2)

Overrides java.lang.Object.equals.

Supports equality of this Token to another Token.

Parameters

obj2:Object: Object to consider equality of

Returns:boolean

boolean true if equal

Annotations

@Override

getCount	back to summary
pack-priv int getCount() Gets the current number of values represented Returns:int int number of values represented

getCount

back to summary

pack-priv int getCount()

Gets the current number of values represented

Returns:int: int number of values represented

getValue	back to summary
pack-priv Object getValue() Gets the particular value this token represents. Returns:Object Object value, non-null.

getValue

back to summary

pack-priv Object getValue()

Gets the particular value this token represents.

Returns:Object: Object value, non-null.

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. Returns a hash code for the token equal to the hash code for the token's value. Thus 'TT' and 'TTTT' will have the same hash code. Returns:int The hash code for the token Annotations @Override

hashCode

back to summary

public int hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code for the token equal to the hash code for the token's value. Thus 'TT' and 'TTTT' will have the same hash code.

Returns:int

The hash code for the token

Annotations

@Override

increment	back to summary
pack-priv void increment() Adds another one of the value

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Represents this token as a String. Returns:String String representation of the token Annotations @Override

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Represents this token as a String.

Returns:String

String representation of the token

Annotations

@Override

public Class DurationFormatUtils

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv final Class DurationFormatUtils.Token

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail