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.
  Since:
    2.1

- - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DurationFormatUtils()` DurationFormatUtils instances should NOT be constructed in standard programming.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and 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 Detail

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

    - #### DurationFormatUtils

          public DurationFormatUtils()

      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

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

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

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

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

Copyright © 2001–2023 The Apache Software Foundation. All rights reserved.