Values with weights, picked with probability proportional to the weight. More...

#include <weighted_table.hpp>

Classes
struct	entry
	A value and its base weight. More...

Public Member Functions
	weighted_table ()=default
	An empty table.

	weighted_table (std::initializer_list< entry > entries)
	A table from entries.

weighted_table &	add (T value, double weight)
	Append an entry.

std::size_t	size () const noexcept
	Number of entries.

bool	empty () const noexcept
	Whether there are no entries.

std::span< const entry >	entries () const noexcept
	The entries, in order.

double	total_weight () const noexcept
	Sum of the base weights.

std::size_t	pick_index (rng &r) const
	Pick an index by base weight. Consumes one engine value.

const T &	pick (rng &r) const
	Pick a value by base weight. Consumes one engine value.

template<std::invocable< const T &, double > F>
std::optional< std::size_t >	try_pick_index (rng &r, const F &adjust) const
	Pick an index with adjusted weights, or nothing when every adjusted weight is 0. Always consumes one engine value.

template<std::invocable< const T &, double > F>
const T *	try_pick (rng &r, const F &adjust) const
	Pick a value with adjusted weights, or nothing when every adjusted weight is 0. Always consumes one engine value.

template<std::invocable< const T &, double > F>
const T &	pick (rng &r, const F &adjust) const
	Pick a value with adjusted weights. Consumes one engine value.

template<std::invocable< const T &, double > F>
std::vector< std::size_t >	pick_distinct_indices (rng &r, std::size_t k, const F &adjust) const
	Pick up to `k` distinct indices, each draw by adjusted weight among the entries not yet chosen.

std::vector< std::size_t >	pick_distinct_indices (rng &r, std::size_t k) const
	Pick up to `k` distinct indices by base weight.

Detailed Description

template<typename T>
class dasmig::core::weighted_table< T >

Values with weights, picked with probability proportional to the weight.

A pick uses the same algorithm as discrete (cumulative sums in entry order, one engine value), so entry order is part of the output.

Weights can be adjusted per call by a function of the entry and its base weight, which is how context conditions a choice: return the base weight to keep it, a multiple to favour it, or 0 to exclude it.

dasmig::core::weighted_table<std::string> jobs{{"farmer", 3.0}, {"nurse", 2.0}, {"pilot", 0.2}};
const auto& job = jobs.pick(r);
const auto& adult_job = jobs.pick(r, [&](const std::string& j, double w) {
    return (j == "pilot" && age < 21) ? 0.0 : w;
});

Template Parameters

T	Value type.

Definition at line 50 of file weighted_table.hpp.

Constructor & Destructor Documentation

◆ weighted_table()

template<typename T >

dasmig::core::weighted_table< T >::weighted_table ( std::initializer_list< entry > entries )

inline

A table from entries.

Parameters

entries Values and weights.

Exceptions

std::invalid_argument If a weight is negative or not finite.

Definition at line 66 of file weighted_table.hpp.

Member Function Documentation

◆ add()

template<typename T >

weighted_table & dasmig::core::weighted_table< T >::add	(	T	value,
		double	weight
	)

inline

Append an entry.

Parameters

value	The value.
weight	Base weight, finite and >= 0.

Returns: *this.

Exceptions

std::invalid_argument If weight is negative or not finite, or the total weight overflows.

Definition at line 77 of file weighted_table.hpp.

◆ empty()

template<typename T >

bool dasmig::core::weighted_table< T >::empty ( ) const

inlinenoexcept

Whether there are no entries.

Returns: True when empty.

Definition at line 97 of file weighted_table.hpp.

◆ entries()

template<typename T >

std::span< const entry > dasmig::core::weighted_table< T >::entries ( ) const

inlinenoexcept

The entries, in order.

Returns: The entries.

Definition at line 101 of file weighted_table.hpp.

◆ pick() [1/2]

template<typename T >

const T & dasmig::core::weighted_table< T >::pick ( rng & r ) const

inline

Pick a value by base weight. Consumes one engine value.

Parameters

r Engine.

Returns: The chosen value.

Exceptions

std::invalid_argument If no entry has a positive weight.

Definition at line 127 of file weighted_table.hpp.

◆ pick() [2/2]

template<typename T >

template<std::invocable< const T &, double > F>

const T & dasmig::core::weighted_table< T >::pick	(	rng &	r,
		const F &	adjust
	)		const

inline

Pick a value with adjusted weights. Consumes one engine value.

Template Parameters

F	As try_pick_index().

Parameters

r	Engine.
adjust	Returns the weight to use (0 excludes the entry).

Returns: The chosen value.

Exceptions

std::invalid_argument If every adjusted weight is 0, or as try_pick_index().

Definition at line 194 of file weighted_table.hpp.

◆ pick_distinct_indices() [1/2]

template<typename T >

std::vector< std::size_t > dasmig::core::weighted_table< T >::pick_distinct_indices	(	rng &	r,
		std::size_t	k
	)		const

inline

Pick up to k distinct indices by base weight.

Parameters

r	Engine.
k	Number of entries wanted.

Returns: The chosen indices, in the order drawn.

Definition at line 241 of file weighted_table.hpp.

◆ pick_distinct_indices() [2/2]

template<typename T >

template<std::invocable< const T &, double > F>

std::vector< std::size_t > dasmig::core::weighted_table< T >::pick_distinct_indices	(	rng &	r,
		std::size_t	k,
		const F &	adjust
	)		const

inline

Pick up to k distinct indices, each draw by adjusted weight among the entries not yet chosen.

A draw where no remaining entry has a positive weight chooses nothing, so the result can be shorter than k. Consumes exactly k engine values either way.

Template Parameters

F	As try_pick_index().

Parameters

r	Engine.
k	Number of entries wanted.
adjust	Returns the weight to use (0 excludes the entry).

Returns: The chosen indices, in the order drawn.

Exceptions

std::invalid_argument As try_pick_index().

Definition at line 218 of file weighted_table.hpp.

◆ pick_index()

template<typename T >

std::size_t dasmig::core::weighted_table< T >::pick_index ( rng & r ) const

inline

Pick an index by base weight. Consumes one engine value.

Parameters

r Engine.

Returns: The index of the chosen entry.

Exceptions

std::invalid_argument If no entry has a positive weight.

Definition at line 114 of file weighted_table.hpp.

◆ size()

template<typename T >

std::size_t dasmig::core::weighted_table< T >::size ( ) const

inlinenoexcept

Number of entries.

Returns: The size.

Definition at line 93 of file weighted_table.hpp.

◆ total_weight()

template<typename T >

double dasmig::core::weighted_table< T >::total_weight ( ) const

inlinenoexcept

Sum of the base weights.

Returns: The total.

Definition at line 105 of file weighted_table.hpp.

◆ try_pick()

template<typename T >

template<std::invocable< const T &, double > F>

const T * dasmig::core::weighted_table< T >::try_pick	(	rng &	r,
		const F &	adjust
	)		const

inline

Pick a value with adjusted weights, or nothing when every adjusted weight is 0. Always consumes one engine value.

Template Parameters

F	As try_pick_index().

Parameters

r	Engine.
adjust	Returns the weight to use (0 excludes the entry).

Returns: A pointer to the chosen value, or nullptr.

Exceptions

std::invalid_argument As try_pick_index().

Definition at line 180 of file weighted_table.hpp.

◆ try_pick_index()

template<typename T >

template<std::invocable< const T &, double > F>

std::optional< std::size_t > dasmig::core::weighted_table< T >::try_pick_index	(	rng &	r,
		const F &	adjust
	)		const

inline

Pick an index with adjusted weights, or nothing when every adjusted weight is 0. Always consumes one engine value.

Template Parameters

F	Callable `double(const T& value, double base_weight)`.

Parameters

r	Engine.
adjust	Returns the weight to use (0 excludes the entry).

Returns: The index, or empty.

Exceptions

std::invalid_argument If adjust returns a negative or non-finite weight, or the adjusted total overflows.

Definition at line 138 of file weighted_table.hpp.

The documentation for this class was generated from the following file:

dasmig/core/weighted_table.hpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ weighted_table()

Member Function Documentation

◆ add()

◆ empty()

◆ entries()

◆ pick() [1/2]

◆ pick() [2/2]

◆ pick_distinct_indices() [1/2]

◆ pick_distinct_indices() [2/2]

◆ pick_index()

◆ size()

◆ total_weight()

◆ try_pick()

◆ try_pick_index()