DurationFormatUtils (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3.time, class: DurationFormatUtils

Package org.apache.commons.lang3.time

# Class DurationFormatUtils

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

public class DurationFormatUtils extends 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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ISO_EXTENDED_FORMAT_PATTERN`
  Pattern used with `FastDateFormat` and `SimpleDateFormat` for the ISO 8601 period format used in durations.

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `formatDuration(long durationMillis, String format)`
  Formats the time gap as a string, using the specified format, and padding with zeros.
  `static String`
  `formatDuration(long durationMillis, String format, boolean padWithZeros)`
  Formats the time gap as a string, using the specified format.
  `static String`
  `formatDurationHMS(long durationMillis)`
  Formats the time gap as a string.
  `static String`
  `formatDurationISO(long durationMillis)`
  Formats the time gap as a string.
  `static String`
  `formatDurationWords(long durationMillis, boolean suppressLeadingZeroElements, boolean suppressTrailingZeroElements)`
  Formats an elapsed time into a pluralization correct string.
  `static String`
  `formatPeriod(long startMillis, long endMillis, String format)`
  Formats the time gap as a string, using the specified format.
  `static String`
  `formatPeriod(long startMillis, long endMillis, String format, boolean padWithZeros, TimeZone timezone)`
  Formats the time gap as a string, using the specified format.
  `static String`
  `formatPeriodISO(long startMillis, long endMillis)`
  Formats the time gap as a string.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### ISO_EXTENDED_FORMAT_PATTERN

    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:
      - `FastDateFormat`
      - `SimpleDateFormat`
      - Constant Field Values

- ## Constructor Details

  - ### 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 Details

  - ### formatDuration

    public static String formatDuration(long durationMillis, 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:
      `IllegalArgumentException` - if durationMillis is negative

  - ### formatDuration

    public static String formatDuration(long durationMillis, 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:
      `IllegalArgumentException` - if durationMillis is negative

  - ### formatDurationHMS

    public static 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:
      `IllegalArgumentException` - if durationMillis is negative

  - ### formatDurationISO

    public static 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:
      `IllegalArgumentException` - 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` - if durationMillis is negative

  - ### formatPeriod

    public static String formatPeriod(long startMillis, long endMillis, 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:
      `IllegalArgumentException` - 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 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

  - ### formatPeriodISO

    public static 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:
      `IllegalArgumentException` - if startMillis is greater than endMillis