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

Unit scaling for counts, such that 1000000 can be converted to 1 Million.

Only Benchee plugins should use this code.

# `unit_atoms`

```elixir
@type unit_atoms() :: :one | :thousand | :million | :billion
```

# `units`

```elixir
@type units() :: unit_atoms() | Benchee.Conversion.Unit.t()
```

# `base_unit`

The raw count, unscaled.

## Examples

    iex> base_unit().name
    :one

# `best`

Finds the best unit for a list of counts. 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
    :thousand

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

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

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

# `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({2500, :thousand}, :million)
  ...> value
  2.5
  iex> unit.name
  :million

# `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, :million}`

## Examples

    iex> format(45_678.9)
    "45.68 K"

    iex> format(45.6789)
    "45.68"

    iex> format({45.6789, :thousand})
    "45.68 K"

    iex> format(
    ...>   {45.6789, %Benchee.Conversion.Unit{long: "Thousand", magnitude: "1_000", label: "K"}}
    ...> )
    "45.68 K"

# `format_human`

Formats in a more "human" way separating by units.

## Examples

    iex> format_human(45_678.9)
    "45 K 678.90"

    iex> format_human(1_000_000)
    "1 M"

    iex> format_human(1_001_000)
    "1 M 1 K"

# `scale`

Scales a value representing a count in ones into a larger unit if appropriate

## Examples

    iex> {value, unit} = scale(4_321.09)
    ...> value
    4.32109
    iex> unit.name
    :thousand

    iex> {value, unit} = scale(0.0045)
    ...> value
    0.0045
    iex> unit.name
    :one

# `scale`

Scales a value representing a count in ones into a specified unit

## Examples

    iex> scale(12345, :one)
    12345.0

    iex> scale(12345, :thousand)
    12.345

    iex> scale(12345, :billion)
    1.2345e-5

    iex> scale(12345, :million)
    0.012345

# `unit_for`

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

## Examples

    iex> unit_for(:thousand)
    %Benchee.Conversion.Unit{
      name: :thousand,
      magnitude: 1_000,
      label: "K",
      long: "Thousand"
    }

    iex> unit_for(%Benchee.Conversion.Unit{
    ...>   name: :thousand,
    ...>   magnitude: 1_000,
    ...>   label: "K",
    ...>   long: "Thousand"
    ...> })
    %Benchee.Conversion.Unit{
      name: :thousand,
      magnitude: 1_000,
      label: "K",
      long: "Thousand"
    }

# `units`