The most basic unit in which memory occur, byte.

Examples

iex> base_unit().name
:bytecopy

Finds the best unit for a list of memory units. 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. Pass [strategy: :best] to always return the most frequent unit in the list. Pass [strategy: :none] to always return :byte.

Examples

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

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

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

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

@spec convert(
  {number(), any_unit()},
  any_unit()
) :: Benchee.Conversion.Scale.scaled_number()

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({1024, :kilobyte}, :megabyte) ...> value 1.0 iex> unit.name :megabyte

iex> current_unit = unit_for(:kilobyte) ...> {value, unit} = convert({1024, current_unit}, :megabyte) ...> value 1.0 iex> unit.name :megabyte

Formats a memory as a string, with a unit label.

To specify the unit, pass a tuple of {value, unit_atom} like {1_234, :kilobyte}.

Examples

iex> format(45_678.9)
"44.61 KB"

iex> format(45.6789)
"45.68 B"

iex> format({45.6789, :kilobyte})
"45.68 KB"

iex> format(
...>   {45.6789,
...>    %Benchee.Conversion.Unit{
...>      long: "Kilobytes",
...>      magnitude: 1024,
...>      label: "KB"
...>    }}
...> )
"45.68 KB"copy

Formats in a more human way, where multiple units are used.

Examples

iex> format_human(45_678.9)
"44 KB 622.90 B"

iex> format_human(1024 * 1024 * 1024)
"1 GB"copy

Scales a memory value in bytes into a larger unit if appropriate

Examples

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

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

iex> {value, unit} = scale(11_234_567_890.123) ...> value 10.463006692121736 iex> unit.name :gigabyte

iex> {value, unit} = scale(1_111_234_567_890.123) ...> value 1.0106619519229962 iex> unit.name :terabyte

Scales a memory value in bytes into a value in the specified unit

Examples

iex> scale(12345, :kilobyte)
12.0556640625

iex> scale(12345, :megabyte)
0.011773109436035156

iex> scale(123_456_789, :gigabyte)
0.11497809458523989copy

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

Examples

iex> unit_for(:gigabyte)
%Benchee.Conversion.Unit{
  name: :gigabyte,
  magnitude: 1_073_741_824,
  label: "GB",
  long: "Gigabytes"
}

iex> unit_for(%Benchee.Conversion.Unit{
...>   name: :gigabyte,
...>   magnitude: 1_073_741_824,
...>   label: "GB",
...>   long: "Gigabytes"
...> })
%Benchee.Conversion.Unit{
  name: :gigabyte,
  magnitude: 1_073_741_824,
  label: "GB",
  long: "Gigabytes"
}copy

Callback implementation for Benchee.Conversion.Scale.units/0.