Benchee v0.99.0 Benchee.Conversion.Scale behaviour View Source

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

Link to this section Summary

Functions

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

Used internally to implement scaling in the modules without duplication

Used internally for scaling but only supports scaling with actual units

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

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

Callbacks

Returns the base_unit in which Benchee takes its measurements, which in general is the smallest supported 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

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

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

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

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

Link to this section Types

Link to this type

any_unit() View Source
any_unit() :: unit() | unit_atom()

Link to this type

scaled_number() View Source
scaled_number() :: {number(), unit()}

Link to this type

scaling_strategy() View Source
scaling_strategy() :: :best | :largest | :smallest | :none

Link to this type

unit_atom() View Source
unit_atom() :: atom()

Link to this section Functions

Link to this function

best_unit(measurements, module, options) View Source

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> Benchee.Conversion.Scale.best_unit(list, Benchee.Conversion.Count, strategy: :best).name
:thousand

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

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

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

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

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

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

convert(arg, desired_unit, module) View Source

Used internally to implement scaling in the modules without duplication.

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

Examples

iex> unit = %Benchee.Conversion.Unit{magnitude: 1000}
iex> Benchee.Conversion.Scale.scale 12345, unit
12.345
Link to this function

scale(value, unit, module) View Source

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

Examples

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

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

Link to this section Callbacks

Link to this callback

base_unit() View Source
base_unit() :: unit()

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

Link to this callback

best(list, keyword) View Source
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.

Link to this callback

convert({}, any_unit) View Source
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.

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

Link to this callback

scale(number, any_unit) View Source
scale(number(), any_unit()) :: number()

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

Link to this callback

unit_for(any_unit) View Source
unit_for(any_unit()) :: unit()

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