Infinity Engine v0.6.20
C++ API Documentation
Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Friends | List of all members
Infinity::Engine::DiscreteDistribution< IntType > Class Template Reference

Platform-independent discrete distribution with arbitrary probabilities. More...

#include <PRNGDistribution.hpp>

Classes

struct  param_type
 Parameter set for the distribution. More...
 

Public Types

using result_type = IntType
 The type of values produced by the distribution.
 

Public Member Functions

 DiscreteDistribution ()
 Default constructor. Creates uniform distribution over {0}.
 
template<typename InputIterator >
 DiscreteDistribution (InputIterator first, InputIterator last)
 Constructs from iterator range of weights.
 
 DiscreteDistribution (std::initializer_list< double > wl)
 Constructs from initializer list of weights.
 
template<typename UnaryOperation >
 DiscreteDistribution (size_t count, double xmin, double xmax, UnaryOperation fw)
 Constructs from function evaluated at intervals.
 
 DiscreteDistribution (const param_type &param)
 Constructs from a parameter set.
 
void reset ()
 Resets the distribution state.
 
std::vector< double > probabilities () const
 Returns the probability vector.
 
param_type param () const
 Gets the current parameter set.
 
void param (const param_type &param)
 Sets new parameters for the distribution.
 
result_type min () const
 Gets the minimum value that can be generated (0).
 
result_type max () const
 Gets the maximum value that can be generated.
 
template<typename Generator >
result_type operator() (Generator &g)
 Generates the next random value using stored parameters.
 
template<typename Generator >
result_type operator() (Generator &g, const param_type &param)
 Generates the next random value using provided parameters.
 

Friends

bool operator== (const DiscreteDistribution &lhs, const DiscreteDistribution &rhs)
 
bool operator!= (const DiscreteDistribution &lhs, const DiscreteDistribution &rhs)
 

Detailed Description

template<typename IntType = int>
class Infinity::Engine::DiscreteDistribution< IntType >

Platform-independent discrete distribution with arbitrary probabilities.

Produces random integers i where 0 <= i < n, distributed according to a discrete probability mass function specified by weights. Each integer has a probability proportional to its weight, making this ideal for weighted random selection.

This distribution is extremely versatile for procedural generation and game logic where different outcomes have different probabilities that don't fit standard distributions. Examples include loot tables, weighted random selection, probability tables, or any scenario requiring custom discrete probabilities.

Template Parameters
IntTypeInteger type for the result

Example usage:

PRNG rng(12345);
// Weighted die: outcomes 0-5 with custom probabilities
DiscreteDistribution<int> weighted_die({1.0, 1.0, 1.0, 2.0, 2.0, 3.0});
int outcome = weighted_die(rng); // 5 is 3x more likely than 0
// Item rarity system (common to legendary)
std::vector<double> rarities = {50.0, 30.0, 15.0, 4.0, 1.0};
DiscreteDistribution<int> item_rarity(rarities.begin(), rarities.end());
int rarity_tier = item_rarity(rng);
// Loot table with drop rates
DiscreteDistribution<int> loot({40.0, 30.0, 20.0, 8.0, 2.0}); // Gold, Potion, Weapon, Rare, Epic
int item_type = loot(rng);
// Probability function: higher indices more likely
auto weight_fn = [](double x) { return x * x; }; // Quadratic weights
DiscreteDistribution<int> custom(10, 0.0, 1.0, weight_fn);
int index = custom(rng);
Infinity::Engine::DiscreteDistribution
Platform-independent discrete distribution with arbitrary probabilities.
Definition PRNGDistribution.hpp:3542
Infinity::Engine::PRNG
Pseudo-random number generator for procedural generation.
Definition PRNG.hpp:48
Infinity::Engine::DiscreteDistribution< int >
template class INFINITY_API_PUBLIC DiscreteDistribution< int >
Definition PRNGDistribution.cpp:61
Note
Weights are automatically normalized to probabilities summing to 1.
Returns integers in [0, n) where n is the number of weights.
If all weights are zero, falls back to uniform distribution.
Uses binary search on cumulative probabilities for O(log n) generation.

Member Typedef Documentation

◆ result_type

template<typename IntType = int>
using Infinity::Engine::DiscreteDistribution< IntType >::result_type = IntType

The type of values produced by the distribution.

Constructor & Destructor Documentation

◆ DiscreteDistribution() [1/5]

template<typename IntType = int>
Infinity::Engine::DiscreteDistribution< IntType >::DiscreteDistribution ( )
inline

Default constructor. Creates uniform distribution over {0}.

◆ DiscreteDistribution() [2/5]

template<typename IntType = int>
template<typename InputIterator >
Infinity::Engine::DiscreteDistribution< IntType >::DiscreteDistribution ( InputIterator  first,
InputIterator  last 
)
inline

Constructs from iterator range of weights.

Template Parameters
InputIteratorIterator type for weights
Parameters
firstIterator to first weight
lastIterator past last weight

◆ DiscreteDistribution() [3/5]

template<typename IntType = int>
Infinity::Engine::DiscreteDistribution< IntType >::DiscreteDistribution ( std::initializer_list< double >  wl)
inline

Constructs from initializer list of weights.

Parameters
wlInitializer list of weights

◆ DiscreteDistribution() [4/5]

template<typename IntType = int>
template<typename UnaryOperation >
Infinity::Engine::DiscreteDistribution< IntType >::DiscreteDistribution ( size_t  count,
double  xmin,
double  xmax,
UnaryOperation  fw 
)
inline

Constructs from function evaluated at intervals.

Template Parameters
UnaryOperationFunction type
Parameters
countNumber of discrete outcomes
xminMinimum x value for function evaluation
xmaxMaximum x value for function evaluation
fwWeight function to evaluate

◆ DiscreteDistribution() [5/5]

template<typename IntType = int>
Infinity::Engine::DiscreteDistribution< IntType >::DiscreteDistribution ( const param_type &  param)
inlineexplicit

Constructs from a parameter set.

Parameters
paramThe distribution parameters

Member Function Documentation

◆ max()

template<typename IntType = int>
result_type Infinity::Engine::DiscreteDistribution< IntType >::max ( ) const
inline

Gets the maximum value that can be generated.

Returns
n-1 where n is the number of outcomes

◆ min()

template<typename IntType = int>
result_type Infinity::Engine::DiscreteDistribution< IntType >::min ( ) const
inline

Gets the minimum value that can be generated (0).

◆ operator()() [1/2]

template<typename IntType = int>
template<typename Generator >
result_type Infinity::Engine::DiscreteDistribution< IntType >::operator() ( Generator &  g)
inline

Generates the next random value using stored parameters.

Template Parameters
GeneratorThe random number generator type (e.g., PRNG)
Parameters
gThe random number generator
Returns
A random integer in [0, n) according to the probability mass function

◆ operator()() [2/2]

template<typename IntType = int>
template<typename Generator >
result_type Infinity::Engine::DiscreteDistribution< IntType >::operator() ( Generator &  g,
const param_type &  param 
)
inline

Generates the next random value using provided parameters.

Uses inverse transform sampling with binary search:

  1. Generate U ~ Uniform(0, 1)
  2. Find smallest i such that cumulative_prob[i] >= U
  3. Return i

Binary search provides O(log n) performance even for large probability tables.

Template Parameters
GeneratorThe random number generator type (e.g., PRNG)
Parameters
gThe random number generator
paramThe distribution parameters to use for this generation
Returns
A random integer according to the discrete probability distribution

◆ param() [1/2]

template<typename IntType = int>
param_type Infinity::Engine::DiscreteDistribution< IntType >::param ( ) const
inline

Gets the current parameter set.

◆ param() [2/2]

template<typename IntType = int>
void Infinity::Engine::DiscreteDistribution< IntType >::param ( const param_type &  param)
inline

Sets new parameters for the distribution.

◆ probabilities()

template<typename IntType = int>
std::vector< double > Infinity::Engine::DiscreteDistribution< IntType >::probabilities ( ) const
inline

Returns the probability vector.

Returns
Vector of probabilities for each outcome

◆ reset()

template<typename IntType = int>
void Infinity::Engine::DiscreteDistribution< IntType >::reset ( )
inline

Resets the distribution state.

No-op for discrete distribution as it maintains no internal state.

Friends And Related Symbol Documentation

◆ operator!=

template<typename IntType = int>
bool operator!= ( const DiscreteDistribution< IntType > &  lhs,
const DiscreteDistribution< IntType > &  rhs 
)
friend

◆ operator==

template<typename IntType = int>
bool operator== ( const DiscreteDistribution< IntType > &  lhs,
const DiscreteDistribution< IntType > &  rhs 
)
friend