Package com.norconex.commons.lang.time

# Class DurationFormatter

java.lang.Object
com.norconex.commons.lang.time.DurationFormatter

public final class DurationFormatter extends Object
Formats a duration to a string. This class is thread-safe and immutable.

Since:
  2.0.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final DurationFormatter`
  `COMPACT`
  Example: 5D18h1m23s
  `static final DurationFormatter`
  `FULL`
  Example: 5 days 18 hours 1 minute 23 seconds

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DurationFormatter()`
  Creates a duration with the default locale and full words for duration units.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object o)`
  `String`
  `format(long duration)`
  Formats the given duration (in milliseconds) to a string.
  `String`
  `format(Duration duration)`
  Formats the given duration to a string.
  `DurationUnit`
  `getHighestUnit()`
  `String`
  `getInnerSeparator()`
  `Locale`
  `getLocale()`
  `DurationUnit`
  `getLowestUnit()`
  `NumberFormat`
  `getNumberFormat()`
  `String`
  `getOuterLastSeparator()`
  `String`
  `getOuterSeparator()`
  `DurationUnitFormatter`
  `getUnitFormatter()`
  `int`
  `getUnitPrecision()`
  `int`
  `hashCode()`
  `String`
  `toString()`
  `DurationFormatter`
  `withHighestUnit(DurationUnit highestUnit)`
  Creates a copy if this formatter with the given highest unit.
  `DurationFormatter`
  `withInnerSeparator(String innerSeparator)`
  Creates a copy if this formatter with the specified separator text to be inserted between the numeric and textual values.
  `DurationFormatter`
  `withLocale(Locale locale)`
  Creates a copy if this formatter with the given locale.
  `DurationFormatter`
  `withLowestUnit(DurationUnit lowestUnit)`
  Creates a copy if this formatter with the given lowest unit.
  `DurationFormatter`
  `withNumberFormat(NumberFormat numberFormat)`
  Creates a copy if this formatter with the given number format.
  `DurationFormatter`
  `withOuterLastSeparator(String outerLastSeparator)`
  Creates a copy if this formatter with the specified separator text to be inserted between the second to last and last formatter units (number and text pairs).
  `DurationFormatter`
  `withOuterSeparator(String outerSeparator)`
  Creates a copy if this formatter with the specified separator text to be inserted between each formatter units (number and text pairs).
  `DurationFormatter`
  `withUnitFormatter(DurationUnitFormatter unitFormatter)`
  Creates a copy if this formatter with the given unit formatter.
  `DurationFormatter`
  `withUnitPrecision(int unitPrecision)`
  Creates a copy if this formatter with the given unit precision.

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

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### COMPACT

    public static final DurationFormatter COMPACT
    Example: 5D18h1m23s

  - ### FULL

    public static final DurationFormatter FULL
    Example: 5 days 18 hours 1 minute 23 seconds

- ## Constructor Details

  - ### DurationFormatter

    public DurationFormatter()
    Creates a duration with the default locale and full words for duration units.

- ## Method Details

  - ### withLocale

    public DurationFormatter withLocale(Locale locale)
    Creates a copy if this formatter with the given locale. Default locale is English.
    Parameters:
      `locale` - locale
    Returns:
      duration formatter copy

  - ### getLocale

    public Locale getLocale()

  - ### withUnitPrecision

    public DurationFormatter withUnitPrecision(int unitPrecision)
    Creates a copy if this formatter with the given unit precision.
    Parameters:
      `unitPrecision` - unit precision
    Returns:
      duration formatter copy

  - ### getUnitPrecision

    public int getUnitPrecision()

  - ### withNumberFormat

    public DurationFormatter withNumberFormat(NumberFormat numberFormat)
    Creates a copy if this formatter with the given number format. Default number format is `RbDurationUnitFormatter.FULL`.
    Parameters:
      `numberFormat` - number format
    Returns:
      duration formatter copy

  - ### getNumberFormat

    public NumberFormat getNumberFormat()

  - ### withHighestUnit

    public DurationFormatter withHighestUnit(DurationUnit highestUnit)
    Creates a copy if this formatter with the given highest unit.
    Parameters:
      `highestUnit` - highest unit
    Returns:
      duration formatter copy

  - ### getHighestUnit

    public DurationUnit getHighestUnit()

  - ### withLowestUnit

    public DurationFormatter withLowestUnit(DurationUnit lowestUnit)
    Creates a copy if this formatter with the given lowest unit.
    Parameters:
      `lowestUnit` - lowest unit
    Returns:
      duration formatter copy

  - ### getLowestUnit

    public DurationUnit getLowestUnit()

  - ### withUnitFormatter

    public DurationFormatter withUnitFormatter(DurationUnitFormatter unitFormatter)
    Creates a copy if this formatter with the given unit formatter.
    Parameters:
      `unitFormatter` - unit formatter
    Returns:
      duration formatter copy

  - ### getUnitFormatter

    public DurationUnitFormatter getUnitFormatter()

  - ### withInnerSeparator

    public DurationFormatter withInnerSeparator(String innerSeparator)
    Creates a copy if this formatter with the specified separator text to be inserted between the numeric and textual values. For instance, specifying an hyphen ('-') for a ten seconds duration would result in: `10-seconds`. Default is a single space character.
    Parameters:
      `innerSeparator` - inner separator
    Returns:
      duration formatter copy

  - ### getInnerSeparator

    public String getInnerSeparator()

  - ### withOuterSeparator

    public DurationFormatter withOuterSeparator(String outerSeparator)
    Creates a copy if this formatter with the specified separator text to be inserted between each formatter units (number and text pairs). For instance, specifying ", " for two minutes and ten seconds duration would result in: `2 minutes, 10 seconds`. Default is a single space character.
    Parameters:
      `outerSeparator` - outer separator
    Returns:
      duration formatter copy

  - ### getOuterSeparator

    public String getOuterSeparator()

  - ### withOuterLastSeparator

    public DurationFormatter withOuterLastSeparator(String outerLastSeparator)
    Creates a copy if this formatter with the specified separator text to be inserted between the second to last and last formatter units (number and text pairs). For instance, specifying " and " for 1 hour, two minutes and ten seconds duration would result in: `1 hour 2 minutes and 10 seconds`. Default is `null` (fallsback to using `getOuterSeparator()`).
    Parameters:
      `outerLastSeparator` - last outer separator
    Returns:
      duration formatter copy

  - ### getOuterLastSeparator

    public String getOuterLastSeparator()

  - ### format

    public String format(Duration duration)
    Formats the given duration to a string.
    Parameters:
      `duration` - the duration to format
    Returns:
      formatted duration

  - ### format

    public String format(long duration)
    Formats the given duration (in milliseconds) to a string.
    Parameters:
      `duration` - the duration to format
    Returns:
      formatted duration

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### equals

    public boolean equals(Object o)
    Overrides:
      `equals` in class `Object`

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`