Class 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
    characterduration element
    yyears
    Mmonths
    ddays
    Hhours
    mminutes
    sseconds
    Smilliseconds
    '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
    • 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  
      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  
      (package private) static java.lang.String s  
      (package private) static java.lang.String S  
      (package private) static java.lang.String y  
    • Constructor Summary

      Constructors 
      Constructor Description
      DurationFormatUtils()
      DurationFormatUtils instances should NOT be constructed in standard programming.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      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
    • 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 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
      • 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 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:
        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
      • 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
      • 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, 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 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:
        java.lang.IllegalArgumentException - if startMillis is greater than endMillis
      • 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
      • 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
      • 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[]