@spec preprocess(
  WeightedRandom.Utils.Types.outcomes(),
  [WeightedRandom.Utils.Types.weight_spec()],
  WeightedRandom.Utils.Types.opts()
) :: WeightedRandom.Backend.t()

Given a non-empty list (or range) of possible outcomes, and a list of weight maps, build a struct that can later be passed into WeightedRandom.take/2 for very fast random sampling.

Examples

iex> r = WeightedRandom.preprocesses(0..10, [%{target: 2, amount: 1000}])
iex> li = WeightedRandom.take(r, 5)
[2, 2, 2, 2, 2]

Supported options:

• :backend (atom/0) - Required. Any module which implements the @behaviour: WeightedRandom.Backend. This is the core algorithm providing the randomness functionality.

• :precision (pos_integer/0) - The number of decimal places to use when rounding. Leave nil for no rounding.

• :outcome_type - When you take a random sample, will it return the index of an outcome, or the value?

  • index: pick random indices from the list of outcomes. For example if your outcomes are 125..130 then the results will be between 0 and 5.
  • value: pick random values from the list of outcomes. For example if your outcomes are 125..130 then the results will be between 125 and 130.

  The default value is :index.

@spec preprocess_p(
  WeightedRandom.Utils.Types.probabilities(),
  WeightedRandom.Utils.Types.opts()
) ::
  WeightedRandom.Backend.t()

Given a non-empty list of percentages (floats from 0.0 - 1.0), build the struct.

Next, pass the resulting struct into WeightedRandom.take/2 to get rand

Examples

iex> r = WeightedRandom.preprocess_p([0.01, 0.01, 0.98])
iex> li = WeightedRandom.take(r, 5)
[2, 2, 2, 2, 2]

Supported options:

• :backend (atom/0) - Required. Any module which implements the @behaviour: WeightedRandom.Backend. This is the core algorithm providing the randomness functionality.

• :precision (pos_integer/0) - The number of decimal places to use when rounding. Leave nil for no rounding.

@spec rand(
  outcomes :: WeightedRandom.Utils.Types.outcomes(),
  weights :: [WeightedRandom.Utils.Types.weight_spec()],
  WeightedRandom.Utils.Types.opts()
) :: any()

Returns a random value based on the weights given. If you need a lot of random numbers over time, this is suboptimal and you should use preprocess + take instead.

Supported options:

• :precision (pos_integer/0) - The number of decimal places to use when rounding. Leave nil for no rounding.

• :outcome_type - When you take a random sample, will it return the index of an outcome, or the value?

  • index: pick random indices from the list of outcomes. For example if your outcomes are 125..130 then the results will be between 0 and 5.
  • value: pick random values from the list of outcomes. For example if your outcomes are 125..130 then the results will be between 125 and 130.

  The default value is :index.

• :take (pos_integer/0) - If used, then instead of returning one random value, will return a list (size == :take) of random values

• :backend (atom/0) - Any module which implements the @behaviour: WeightedRandom.Backend. This is the core algorithm providing the randomness functionality.

@spec rand_p(
  WeightedRandom.Utils.Types.probabilities(),
  WeightedRandom.Utils.Types.opts()
) :: any()

similar to rand/3 but instead of a list of outcomes, and a list of weights, rand_p/3 accepts a list of probability floats. If you need a lot of random numbers over time, this is suboptimal and you should use preprocess + take instead.

Supported options:

• :backend (atom/0) - Any module which implements the @behaviour: WeightedRandom.Backend. This is the core algorithm providing the randomness functionality.

• :precision (pos_integer/0) - The number of decimal places to use when rounding. Leave nil for no rounding.

• :take (pos_integer/0) - If used, then instead of returning one random value, will return a list (size == :take) of random values

@spec take(WeightedRandom.Backend.t()) :: any()

Given a WeightedRandom struct, return a single random value.

Examples

iex> r = WeightedRandom.preprocesses(0..10, [%{target: 2, amount: 1000}])
iex> li = WeightedRandom.take(r)
2

@spec take(WeightedRandom.Backend.t(), count :: integer()) :: list()

Given a WeightedRandom struct, return a list of random values

Examples

iex> # Make the item at index 2 1000x more likely than any other single index.
iex> r = WeightedRandom.preprocesses(0..10, [%{target: 2, amount: 1000}])
iex> li = WeightedRandom.take(r, 3)
[2, 2, 2]