# `Benchee.Conversion.Duration`
[🔗](https://github.com/bencheeorg/benchee/blob/1.5.1/lib/benchee/conversion/duration.ex#L1)

Unit scaling for duration converting from microseconds to minutes and others.

Only Benchee plugins should use this code.

# `base_unit`

The most basic unit in which measurements occur.

## Examples

    iex> base_unit().name
    :nanosecond

# `best`

Finds the best unit for a list of durations. By default, chooses the most common
unit. In case of tie, chooses the largest of the most common units.

Pass `[strategy: :smallest]` to always return the smallest unit in the list.
Pass `[strategy: :largest]` to always return the largest unit in the list.

## Examples

    iex> best([23, 23_000, 34_000, 2_340_000]).name
    :microsecond

    iex> best([23, 23_000, 34_000_000, 2_340_000_000, 3_450_000_000]).name
    :second

    iex> best([23, 23_000, 34_000, 2_340_000], strategy: :smallest).name
    :nanosecond

    iex> best([23, 23_000, 34_000, 2_340_000_000], strategy: :largest).name
    :second

# `convert`

Converts a value for a specified %Unit or unit atom and converts it to the equivalent of another unit of measure.

## Examples

  iex> {value, unit} = convert({90, :minute}, :hour)
  ...> value
  1.5
  iex> unit.name
  :hour

# `convert_value`

Converts a value of the given unit into the desired unit, returning only the value not the unit.

## Examples

    iex> convert_value({1.234, :second}, :microsecond)
    1_234_000.0

    iex> convert_value({1.234, :minute}, :microsecond)
    7.404e7

    iex> microseconds = convert_value({1.234, :minute}, :microsecond)
    ...> {value, _} = convert({microseconds, :microsecond}, :minute)
    ...> value
    1.234

# `format`

Formats a number as a string, with a unit label. To specify the unit, pass
a tuple of `{value, unit_atom}` like `{1_234, :second}`.

## Examples

    iex> format(45_678.9)
    "45.68 μs"

    iex> format(45.6789)
    "45.68 ns"

    iex> format({45.6789, :millisecond})
    "45.68 ms"

    iex> format(
    ...>   {45.6789,
    ...>    %Benchee.Conversion.Unit{
    ...>      long: "Milliseconds",
    ...>      magnitude: 1000,
    ...>      label: "ms"
    ...>    }}
    ...> )
    "45.68 ms"

# `format_human`

Formats in a more "human" way - 1h 30min instead of 1.5h.

## Examples

    iex> format_human(5_400_000_000_000)
    "1 h 30 min"

    iex> format_human(12.5)
    "12.50 ns"

    iex> format_human(1000.555)
    "1 μs 0.55 ns"

    iex> format_human(3_660_001_001_000)
    "1 h 1 min 1 ms 1 μs"

    iex> format_human(0)
    "0 ns"

    iex> format_human(2 * 1000 * 1000 * 1000)
    "2 s"

# `scale`

Scales a duration value in nanoseconds into a larger unit if appropriate

## Examples

    iex> {value, unit} = scale(1)
    ...> value
    1.0
    iex> unit.name
    :nanosecond

    iex> {value, unit} = scale(1_234)
    ...> value
    1.234
    iex> unit.name
    :microsecond

    iex> {value, unit} = scale(11_234_567_890_123)
    ...> value
    3.1207133028119443
    iex> unit.name
    :hour

# `scale`

Scales a duration value in nanoseconds into a value in the specified unit

## Examples

    iex> scale(12345, :nanosecond)
    12345.0

    iex> scale(12345, :microsecond)
    12.345

    iex> scale(12345, :minute)
    2.0575e-7

# `unit_for`

Get a unit by its atom representation. If handed already a %Unit{} struct it
just returns it.

## Examples

    iex> unit_for(:hour)
    %Benchee.Conversion.Unit{
      name: :hour,
      magnitude: 3_600_000_000_000,
      label: "h",
      long: "Hours"
    }

    iex> unit_for(%Benchee.Conversion.Unit{
    ...>   name: :hour,
    ...>   magnitude: 3_600_000_000_000,
    ...>   label: "h",
    ...>   long: "Hours"
    ...> })
    %Benchee.Conversion.Unit{
      name: :hour,
      magnitude: 3_600_000_000_000,
      label: "h",
      long: "Hours"
    }

# `units`