Package org.kiwiproject.time

Class KiwiDurationFormatters

java.lang.Object
org.kiwiproject.time.KiwiDurationFormatters
public final class KiwiDurationFormatters extends Object
Utilities for formatting durations of various types.

See Apache Commons DurationFormatUtils for even more formatter methods.

Implementation Note:
dropwizard-util must be a dependency or code using this class won't compile; this requirement will be necessary until the deprecated methods are removed.

  • Method Details

    • formatDurationWords

      @Deprecated(since="4.6.0", forRemoval=true) @KiwiDeprecated(replacedBy="formatJavaDurationWords(java.time.Duration duration)", usageSeverity=SEVERE, removeAt="5.0.0") public static String formatDurationWords(Duration duration)
      Deprecated, for removal: This API element is subject to removal in a future version.
      for removal; replaced by formatJavaDurationWords(java.time.Duration)
      Formats a Java Duration using English words. Converts the duration to millis and then calls formatDurationWords(long).
      Parameters:
      duration - the Java duration to format
      Returns:
      the duration in words (e.g., 2 hours 5 minutes)

    • formatJavaDurationWords

      public static String formatJavaDurationWords(Duration duration)
      Formats a Java Duration using English words. Converts the duration to nanos and then calls formatNanosecondDurationWords(long).

      If the duration is null, the literal string "null" is returned. If the duration is zero, "0 seconds" is returned.

      Parameters:
      duration - the Java duration to format
      Returns:
      the duration in words (e.g., 2 hours 5 minutes)
      Throws:
      IllegalArgumentException - if the duration is negative
      See Also:

    • formatDurationWords

      @Deprecated(since="4.6.0", forRemoval=true) @KiwiDeprecated(replacedBy="formatDropwizardDurationWords(io.dropwizard.util.Duration duration)", usageSeverity=SEVERE, removeAt="5.0.0") public static String formatDurationWords(io.dropwizard.util.Duration duration)
      Deprecated, for removal: This API element is subject to removal in a future version.
      for removal; replaced by formatDropwizardDurationWords(Duration)
      Formats a Dropwizard io.dropwizard.util.Duration using English words. Converts the duration to millis and then calls formatDurationWords(long).
      Parameters:
      duration - the Dropwizard duration to format
      Returns:
      the duration in words (e.g., 1 minute 45 seconds)
      Implementation Note:
      You will need the Dropwizard Duration class available at runtime to call this method!

    • formatDropwizardDurationWords

      public static String formatDropwizardDurationWords(io.dropwizard.util.Duration duration)
      Formats a Dropwizard Duration using English words. Converts the duration to nanos and then calls formatNanosecondDurationWords(long).

      If the duration is null, the literal string "null" is returned. If the duration is zero, "0 seconds" is returned.

      Parameters:
      duration - the Dropwizard duration to format
      Returns:
      the duration in words (e.g., 1 minute 45 seconds)
      Throws:
      IllegalArgumentException - if the duration is negative
      See Also:
      Implementation Note:
      You will need the Dropwizard Duration class available at runtime to call this method!

    • formatDurationWords

      @Deprecated(since="4.6.0", forRemoval=true) @KiwiDeprecated(replacedBy="formatMillisecondDurationWords(long durationMillis)", usageSeverity=SEVERE, removeAt="5.0.0") public static String formatDurationWords(long durationMillis)
      Deprecated, for removal: This API element is subject to removal in a future version.
      for removal; replaced by formatMillisecondDurationWords(long)
      A thin wrapper around DurationFormatUtils.formatDurationWords(long, boolean, boolean) that always suppresses leading and trailing "zero elements" because why would you want to see "0 days 7 hours 25 minutes 0 seconds" instead of just "7 hours 25 minutes"? (We cannot think of a good reason...)
      Parameters:
      durationMillis - the duration in milliseconds to format
      Returns:
      the duration in words (e.g., 10 minutes)
      See Also:
      • DurationFormatUtils.formatDurationWords(long, boolean, boolean)
      Implementation Note:
      The only real reason for this method to exist is, so we don't constantly have to pass the two boolean arguments. Plus, boolean arguments are evil because what exactly does "true, false" tell you without requiring you to look at the parameter documentation?

    • formatMillisecondDurationWords

      public static String formatMillisecondDurationWords(long durationMillis)
      A thin wrapper around DurationFormatUtils.formatDurationWords(long, boolean, boolean) that always suppresses leading and trailing "zero elements" because why would you want to see "0 days 7 hours 25 minutes 0 seconds" instead of just "7 hours 25 minutes"? (We cannot think of a good reason...).

      Unlike DurationFormatUtils, it also handles durations less than one second down to 1 nanosecond.

      If the duration is zero, "0 milliseconds" is returned.

      If you need to handle durations less than a millisecond, use formatNanosecondDurationWords(long)

      Parameters:
      durationMillis - the duration in milliseconds to format
      Returns:
      the duration in words (e.g., 10 minutes)
      Throws:
      IllegalArgumentException - if the duration is negative
      See Also:
      Implementation Note:
      The main reasons for this method to exist are so that we don't constantly have to pass the two boolean arguments to DurationFormatUtils and so that we can handle durations less than one second. Plus, boolean arguments are evil because what exactly does "true, false" tell you without requiring you to look at the parameter documentation?

    • formatNanosecondDurationWords

      public static String formatNanosecondDurationWords(long durationNanos)
      A thin wrapper around DurationFormatUtils.formatDurationWords(long, boolean, boolean) that always suppresses leading and trailing "zero elements" because why would you want to see "0 days 7 hours 25 minutes 0 seconds" instead of just "7 hours 25 minutes"? (We cannot think of a good reason...)

      If the duration is zero, "0 nanosecond" is returned.

      Unlike DurationFormatUtils, it also handles durations less than one second down to 1 nanosecond.

      Parameters:
      durationNanos - the duration in nanoseconds to format
      Returns:
      the duration in words (e.g., 10 minutes, 50 milliseconds)
      Throws:
      IllegalArgumentException - if the duration is negative
      See Also:
      • DurationFormatUtils.formatDurationWords(long, boolean, boolean)
      Implementation Note:
      The main reasons for this method to exist are so that we don't constantly have to pass the two boolean arguments to DurationFormatUtils and so that we can handle durations less than one second. Plus, boolean arguments are evil because what exactly does "true, false" tell you without requiring you to look at the parameter documentation?