View Source Benchee.Conversion.Scale behaviour (Benchee v1.3.0)

Functions for scaling values to other units. Different domains handle this task differently, for example durations and counts.

See Benchee.Conversion.Count and Benchee.Conversion.Duration for examples

Summary

Types

any_unit()

scaled_number()

scaling_strategy()

unit()

unit_atom()

Callbacks

base_unit()

Returns the base_unit in which Benchee takes its measurements, which in general is the smallest supported unit.

best(list, keyword)

Finds the best fit unit for a list of numbers in a domain's base unit. "Best fit" is the most common unit, or (in case of tie) the largest of the most common units.

convert({}, any_unit)

Takes a tuple of a number and a unit and a unit to be converted to, returning the the number scaled to the new unit and the new unit.

scale(number)

Scales a number in a domain's base unit to an equivalent value in the best fit unit. Results are a {number, unit} tuple. See Benchee.Conversion.Count and Benchee.Conversion.Duration for examples.

scale(number, any_unit)

Scales a number in a domain's base unit to an equivalent value in the specified unit. See Benchee.Conversion.Count and Benchee.Conversion.Duration for examples.

unit_for(any_unit)

Given the atom representation of a unit (:hour) return the appropriate Benchee.Conversion.Unit struct.

units()

List of all the units supported by this type.

Functions

best_unit(measurements, module, options)

Given a list of number values and a module describing the domain of the values (e.g. Duration, Count), finds the "best fit" unit for the list as a whole.

convert(arg, desired_unit, module)

Used internally to implement scaling in the modules without duplication.

scale(value, unit)

Used internally for scaling but only supports scaling with actual units.

scale(value, unit, module)

Used internally by implemented units to handle their scaling with units and without.

unit_for(units, unit)

Lookup a unit by its atom presentation for the representation of supported units. Used by Benchee.Conversion.Duration and Benchee.Conversion.Count.

Types

any_unit()

@type any_unit() :: unit() | unit_atom()

scaled_number()

@type scaled_number() :: {number(), unit()}

scaling_strategy()

@type scaling_strategy() :: :best | :largest | :smallest | :none

unit()

@type unit() :: Benchee.Conversion.Unit.t()

unit_atom()

@type unit_atom() :: atom()

Callbacks

base_unit()

@callback base_unit() :: unit()

Returns the base_unit in which Benchee takes its measurements, which in general is the smallest supported unit.

best(list, keyword)

@callback best(
  list(),
  keyword()
) :: unit()

Finds the best fit unit for a list of numbers in a domain's base unit. "Best fit" is the most common unit, or (in case of tie) the largest of the most common units.

convert({}, any_unit)

@callback convert(
  {number(), any_unit()},
  any_unit()
) :: scaled_number()

Takes a tuple of a number and a unit and a unit to be converted to, returning the the number scaled to the new unit and the new unit.

scale(number)

@callback scale(number()) :: scaled_number()

scale(number, any_unit)

@callback scale(number(), any_unit()) :: number()

Scales a number in a domain's base unit to an equivalent value in the specified unit. See Benchee.Conversion.Count and Benchee.Conversion.Duration for examples.

unit_for(any_unit)

@callback unit_for(any_unit()) :: unit()

Given the atom representation of a unit (:hour) return the appropriate Benchee.Conversion.Unit struct.

units()

@callback units() :: [unit()]

List of all the units supported by this type.

Functions

best_unit(measurements, module, options)

Given a list of number values and a module describing the domain of the values (e.g. Duration, Count), finds the "best fit" unit for the list as a whole.

The best fit unit for a given value is the smallest unit in the domain for which the scaled value is at least 1. For example, the best fit unit for a count of 1_000_000 would be :million.

The best fit unit for the list as a whole depends on the :strategy passed in opts:

:best - the most frequent best fit unit. In case of tie, the largest of the most frequent units
:largest - the largest best fit unit
:smallest - the smallest best fit unit
:none - the domain's base (unscaled) unit

Examples

iex> list = [1, 101, 1_001, 10_001, 100_001, 1_000_001]
iex> best_unit(list, Benchee.Conversion.Count, strategy: :best).name
:thousand

iex> list = [1, 101, 1_001, 10_001, 100_001, 1_000_001]
iex> best_unit(list, Benchee.Conversion.Count, strategy: :smallest).name
:one

iex> list = [1, 101, 1_001, 10_001, 100_001, 1_000_001]
iex> best_unit(list, Benchee.Conversion.Count, strategy: :largest).name
:million

iex> list = []
iex> best_unit(list, Benchee.Conversion.Count, strategy: :best).name
:one

iex> list = [nil]
iex> best_unit(list, Benchee.Conversion.Count, strategy: :best).name
:one

iex> list = [nil, nil, nil, nil]
iex> best_unit(list, Benchee.Conversion.Count, strategy: :best).name
:one

iex> list = [nil, nil, nil, nil, 2_000]
iex> best_unit(list, Benchee.Conversion.Count, strategy: :best).name
:thousand

convert(arg, desired_unit, module)

Used internally to implement scaling in the modules without duplication.

scale(value, unit)

Used internally for scaling but only supports scaling with actual units.

Examples

iex> unit = %Benchee.Conversion.Unit{magnitude: 1000}
iex> scale 12345, unit
12.345

scale(value, unit, module)

Used internally by implemented units to handle their scaling with units and without.

Examples

iex> scale(12345, :thousand, Benchee.Conversion.Count)
12.345

unit_for(units, unit)

Lookup a unit by its atom presentation for the representation of supported units. Used by Benchee.Conversion.Duration and Benchee.Conversion.Count.