A class to sample integers [0,m). More...

#include <exrandom/i_rand.hpp>

Public Member Functions
	i_rand (digit_gen &D)

template<typename Generator >
i_rand &	init (Generator &g, int m)

template<typename Generator >
int	operator() (Generator &g)

int	min () const

int	max () const

int	entropy () const

void	negate ()

void	add (int c)

template<typename Generator >
bool	less_than (Generator &g, long long m, long long n=1)

template<typename Generator >
bool	less_than_equal (Generator &g, long long m, long long n=1)

template<typename Generator >
bool	greater_than (Generator &g, long long m, long long n=1)

template<typename Generator >
bool	greater_than_equal (Generator &g, long long m, long long n=1)

std::string	print () const

template<typename Generator >
void	refine (Generator &g)

Friends
std::ostream &	operator<< (std::ostream &os, const i_rand &h)

Detailed Description

template<typename digit_gen>
class exrandom::i_rand< digit_gen >

A class to sample integers [0,m).

The basic method for sampling is taken from J. Lumbroso (2013), arxiv:1304.1916 generalized to accept random digits in an arbitrary base, b. However, an important additional feature is that only sufficient random digits are drawn to narrow the allowed range to a power of b. Thus, for b = 2, after initializing with m = 9 the i_rand represents

range prob [0,8) 32/63 [0,2) 2/21 [2,6) 4/21 [6,8) 2/21 [8,9) 1/9

min() and max() give the current extent of the closed range. The number of additional random digits needed to fix the value is given by entropy(). The comparison operations may require additional digits to be drawn and so the range might be narrowed down, e.g., to [4,8). If you need a definite value then use operator()().

Template Parameters

digit_gen the type of digit generator.

Examples: discrete_count_bits.cpp, and sample_discrete_normal.cpp.

Definition at line 44 of file i_rand.hpp.

Constructor & Destructor Documentation

◆ i_rand()

template<typename digit_gen>

exrandom::i_rand< digit_gen >::i_rand ( digit_gen & D )

inlineexplicit

The constructor.

Parameters

D	A reference to the digit generator to be used.

Initializes to a random integer in [0,1), i.e., to 0.

Definition at line 54 of file i_rand.hpp.

Member Function Documentation

◆ init()

template<typename digit_gen>

template<typename Generator >

i_rand& exrandom::i_rand< digit_gen >::init	(	Generator &	g,
		int	m
	)

inline

Initialize.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine.
m	this must be greater than 0.

Returns: *this representing a integer uniform distributed in [0,m).

If m is less than 1, it is treated as 1.

Definition at line 67 of file i_rand.hpp.

◆ operator()()

template<typename digit_gen>

template<typename Generator >

int exrandom::i_rand< digit_gen >::operator() ( Generator & g )

inline

Sample enough digits to narrow the range to an integer.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine.

Returns: value of the random integer.

Definition at line 97 of file i_rand.hpp.

◆ min()

template<typename digit_gen>

int exrandom::i_rand< digit_gen >::min ( ) const

inline

Returns: the current lower end of the range.

Definition at line 102 of file i_rand.hpp.

◆ max()

template<typename digit_gen>

int exrandom::i_rand< digit_gen >::max ( ) const

inline

Returns: the current upper end of the range.

Definition at line 106 of file i_rand.hpp.

◆ entropy()

template<typename digit_gen>

int exrandom::i_rand< digit_gen >::entropy ( ) const

inline

Returns: the number of digits needs to complete the sampling.

Definition at line 110 of file i_rand.hpp.

◆ negate()

template<typename digit_gen>

void exrandom::i_rand< digit_gen >::negate ( )

inline

Negate the range.

Definition at line 114 of file i_rand.hpp.

◆ add()

template<typename digit_gen>

void exrandom::i_rand< digit_gen >::add ( int c )

inline

Add a constant to the range.

Parameters

c	the constant to be added.

Definition at line 120 of file i_rand.hpp.

◆ less_than()

template<typename digit_gen>

template<typename Generator >

bool exrandom::i_rand< digit_gen >::less_than	(	Generator &	g,
		long long	m,
		long long	n = `1`
	)

inline

Test *this < m/n.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine.
m	the numerator of the fraction.
n	the denominate of the fraction (default value 1).

Returns: *this < m/n.

Requires that n > 0.

Definition at line 133 of file i_rand.hpp.

◆ less_than_equal()

template<typename digit_gen>

template<typename Generator >

bool exrandom::i_rand< digit_gen >::less_than_equal	(	Generator &	g,
		long long	m,
		long long	n = `1`
	)

inline

Test *this ≤ m/n.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine.
m	the numerator of the fraction.
n	the denominator of the fraction (default value 1).

Returns: *this ≤ m/n.

Requires that n > 0.

Definition at line 152 of file i_rand.hpp.

◆ greater_than()

template<typename digit_gen>

template<typename Generator >

bool exrandom::i_rand< digit_gen >::greater_than	(	Generator &	g,
		long long	m,
		long long	n = `1`
	)

inline

Test *this > m/n.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine.
m	the numerator of the fraction.
n	the denominator of the fraction (default value 1).

Returns: *this > m/n.

Requires that n > 0.

Definition at line 166 of file i_rand.hpp.

◆ greater_than_equal()

template<typename digit_gen>

template<typename Generator >

bool exrandom::i_rand< digit_gen >::greater_than_equal	(	Generator &	g,
		long long	m,
		long long	n = `1`
	)

inline

Test *this ≥ m/n.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine.
m	the numerator of the fraction.
n	the denominator of the fraction (default value 1).

Returns: *this ≥ m/n.

Requires that n > 0.

Definition at line 180 of file i_rand.hpp.

◆ print()

template<typename digit_gen>

std::string exrandom::i_rand< digit_gen >::print ( ) const

inline

Returns: a string representing the range.

If the entropy is zero, the number is printed. Otherwise the range is represented by min()+[0,max()-min()+1). (Note that max()-min()+1 is a power of the base.)

Definition at line 189 of file i_rand.hpp.

◆ refine()

template<typename digit_gen>

template<typename Generator >

void exrandom::i_rand< digit_gen >::refine ( Generator & g )

inline

Refine the range by sampling an extra digit.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine.

Definition at line 204 of file i_rand.hpp.

Friends And Related Function Documentation

◆ operator<<

template<typename digit_gen>

std::ostream& operator<<	(	std::ostream &	os,
		const i_rand< digit_gen > &	h
	)

friend

Print an i_rand. Format is min+[0,max-min+1) unless the entropy is zero, in which case it's val.

Parameters

os	an output stream.
h	an i_rand.

Returns: os.

Definition at line 216 of file i_rand.hpp.

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

i_rand.hpp

Public Member Functions

Friends

Detailed Description

template<typename digit_gen> class exrandom::i_rand< digit_gen >

Constructor & Destructor Documentation

◆ i_rand()

Member Function Documentation

◆ init()

◆ operator()()

◆ min()

◆ max()

◆ entropy()

◆ negate()

◆ add()

◆ less_than()

◆ less_than_equal()

◆ greater_than()

◆ greater_than_equal()

◆ print()

◆ refine()

Friends And Related Function Documentation

◆ operator<<

template<typename digit_gen>
class exrandom::i_rand< digit_gen >