DurationFormatUtils (Lang 2.6)
Date: 2019-01-01

org.apache.commons.lang.time

## Class DurationFormatUtils

- java.lang.Object
- - org.apache.commons.lang.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.

  character | duration element
  --- | ---
  y | years
  M | months
  d | days
  H | hours
  m | minutes
  s | seconds
  S | milliseconds

  Since:
    2.1
  Version:
    $Id: DurationFormatUtils.java 1057072 2011-01-10 01:55:57Z niallp $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `ISO_EXTENDED_FORMAT_PATTERN` Pattern used with `FastDateFormat` and `SimpleDateFormat` for the ISO8601 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 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 and using the default timezone.
    `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 plurialization 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.

    - ### 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 java.lang.String ISO_EXTENDED_FORMAT_PATTERN

      Pattern used with `FastDateFormat` and `SimpleDateFormat` for the ISO8601 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 java.lang.String formatDurationHMS(long durationMillis)

      Formats the time gap as a string.

      The format used is ISO8601-like: H:m:s.S.

      Parameters:
        `durationMillis` - the duration to format
      Returns:
        the time as a String

    - #### formatDurationISO

          public static java.lang.String formatDurationISO(long durationMillis)

      Formats the time gap as a string.

      The format used is the ISO8601 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 time as a 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 and using the default timezone.

      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
      Returns:
        the time as a String

    - #### 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 and the timezone may be specified.

      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
        `padWithZeros` - whether to pad the left hand side of numbers with 0's
      Returns:
        the time as a String

    - #### formatDurationWords

          public static java.lang.String formatDurationWords(long durationMillis,
                                                             boolean suppressLeadingZeroElements,
                                                             boolean suppressTrailingZeroElements)

      Formats an elapsed time into a plurialization 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

    - #### formatPeriodISO

          public static java.lang.String formatPeriodISO(long startMillis,
                                                         long endMillis)

      Formats the time gap as a string.

      The format used is the ISO8601 period format.

      Parameters:
        `startMillis` - the start of the duration to format
        `endMillis` - the end of the duration to format
      Returns:
        the time as a String

    - #### 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 duration
        `endMillis` - the end of the duration
        `format` - the way in which to format the duration
      Returns:
        the time as a String

    - #### 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 timezone 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
        `padWithZeros` - whether to pad the left hand side of numbers with 0's
        `timezone` - the millis are defined in
      Returns:
        the time as a String

Copyright © 2001-2019 - Apache Software Foundation