Package com.complexible.common.base

# Class Durations

java.lang.Object
com.complexible.common.base.Durations

public final class Durations extends Object

Since:
  2.0
Version:
  2.0
Author:
  Evren Sirin

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static long`
  `parse(String theDuration)`
  Parses the given readable representation of the duration into a milliseconds duration.
  `static long`
  `parse(String theDuration, TimeUnit theOutputUnit)`
  Parses the given readable representation of the duration into a duration value expressed in the requested time unit.
  `static String`
  `readable(long theMilliseconds)`
  Returns a readable representation of the given milliseconds duration.
  `static String`
  `readable(long theDuration, TimeUnit theUnit)`
  Returns a readable representation of the given duration.

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

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

- ## Method Details

  - ### readable

    public static String readable(long theMilliseconds)
    Returns a readable representation of the given milliseconds duration. This function is equivalent to `readable(theMilliseconds, TimeUnit.MILLISECONDS)`.
    See Also:
      - `readable(long, TimeUnit)`

  - ### readable

    public static String readable(long theDuration, TimeUnit theUnit)
    Returns a readable representation of the given duration. The readable duration is a positive integer followed by either letter 'h' (for hours), letter 'm' (for minutes), letter 's' (for seconds), or letters 'ms' (for milliseconds). The function chooses the most appropriate unit to use in the output without losing precision. It is the case that for every integer `N` and `TimeUnit` `T`, we will have `parse(readable(N, T)) == T.toMillis(N)`.

    Examples:

    - `readable(1, TimeUnit.SECONDS)` returns `"1s"`
    - `readable(60, TimeUnit.SECONDS)` returns `"1m"`
    - `readable(80, TimeUnit.SECONDS)` returns `"80s"`
    - `readable(12000, TimeUnit.SECONDS)` returns `"12m"`
    Parameters:
      `theDuration` - duration value
      `theUnit` - time unit for the input duration value
    Returns:
      readable representation of the given duration

  - ### parse

    public static long parse(String theDuration) throws IllegalArgumentException
    Parses the given readable representation of the duration into a milliseconds duration. This function is equivalent to `parse(theDuration, TimeUnit.MILLISECONDS)`.
    Throws:
      `IllegalArgumentException` - if the string representation is not a valid duration

  - ### parse

    public static long parse(String theDuration, TimeUnit theOutputUnit)
    Parses the given readable representation of the duration into a duration value expressed in the requested time unit. The valid string representations are the ones that are generated by the `readable(long, TimeUnit)` function. If the requested time unit is coarser than the duration represented by the string the result will lose precisions. For example, `parse("50s", TimeUnit.MINUTES)` would return `0`.
    Parameters:
      `theDuration` - readable representation of a duration value
      `theOutputUnit` - the unit of the output value
    Returns:
      a duration value expressed in the requested time unit that is represented
    Throws:
      `IllegalArgumentException` - if the string representation is not a valid duration