Random_source< RESULT_TYPE > Class Template Reference

Detailed Description

template<typename RESULT_TYPE>
class ge211::Random_source< RESULT_TYPE >

A generic class for generating pseudorandom numbers in uniform distribution over a specified range.

For example, a Random_source<float> generates floats, and a Random_source<int> generates ints. To specify a range, pass the bounds to either of the two constructors, Random_source(result_type, result_type) or Random_source(result_type). Then call Random_source::next() on your Random_source to generate a random number.

There are also two constructors available only for particular result types:

• Random_source(result_type limit) is defined only when result_type is an integral type. It constructs a source that generates numbers from 0 up to, but excluding, limit.
• Random_source(double p_true) is defined only when result_type is bool. It takes a probability and generates true with that probability and false otherwise.

Testing

You can stub your Random_source in order to predetermine the sequence of values that it will return. For details, see Random_source::stub_with(std::initializer_list<result_type>) and Random_source::stub_with(std::vector<result_type>).

Definition at line 215 of file ge211_random.hxx.

Public Types
using	result_type = RESULT_TYPE
	The type of value generated by this Random_source.

Public Member Functions
	Random_source (result_type lo, result_type hi)
	Constructs a random source that generates values between lo and hi, inclusive. More...
	Random_source (result_type limit)
	Constructs, for integral result_types only, a random source that generates values between 0 and limit - 1. More...
	Random_source (double p_true)
	Constructs a random source that generates bools, producing true with probability p_true. More...
	Random_source (unbounded_type)
	Constructs a Random_source with no predetermined bounds. More...
result_type	next ()
	Returns the next random value from this source. More...
result_type	operator() ()
	Returns the next random value from this source. More...
result_type	next_between (result_type lo, result_type hi)
	Returns a random value between lo and hi. More...
result_type	operator() (result_type lo, result_type hi)
	Returns a random value between lo and hi. More...
void	stub_with (std::initializer_list< result_type > values)
	Configures this Random_source to return a predetermined sequence of values. More...
void	stub_with (std::vector< result_type > values)
	Stubs this Random_source using a std::vector. More...
void	stub_with (result_type value)
	Stubs this Random_source to always return the given value. More...
	Random_source (Random_source &&other)=delete
	Random_sources cannot be move-constructed because they cannot be moved or copied.
Random_source &	operator= (Random_source &&other)=delete
	Random_sources cannot be move-assigned because they cannot be moved or copied.

Static Public Member Functions
static result_type	bound_between (result_type value, result_type lo, result_type hi)
	Given a randomly-generated result_type value, bounds it between lo and hi (inclusive) by adjusting values less than lo to lo and values greater than hi to hi.

Constructor & Destructor Documentation

Random_source() [1/4]

Random_source	(	result_type	lo,
		result_type	hi
	)

Constructs a random source that generates values between lo and hi, inclusive.

Not defined when result_type is bool. See Random_source<bool>::Random_source(double) instead.

Example

// Initialize the source to produce `int`s from 1 to 6:
ge211::Random_source<int> six_sided_die(1, 6);
 
// Generate a random roll:
int roll_value = six_sided_die.next();
 
while (roll_value != 6) {
    std::cout << "You rolled " << roll_value << "; try again.\n";
    roll_value = six_sided_die.next();
}
 
std::cout << "Finally rolled a 6!\n";

Definition at line 561 of file ge211_random.hxx.

Random_source() [2/4]

Random_source ( result_type  limit )

explicit

Constructs, for integral result_types only, a random source that generates values between 0 and limit - 1.

Thus, Random_source(limit) is equivalent to Random_source(0, limit - 1).

Not defined when result_type is bool or any non-integral type.

Definition at line 567 of file ge211_random.hxx.

Random_source() [3/4]

Random_source ( double  p_true )

explicit

Constructs a random source that generates bools, producing true with probability p_true.

Only defined when result_type is bool.

Example

ge211::Random_source<bool> fair_coin(0.5);
 
bool flip_1 = fair_coin.next();
bool flip_2 = fair_coin.next();
bool flip_3 = fair_coin.next();
 
if (flip_1 && flip_2 && flip_3) {
    std::cout << "All three flips were heads!\n";
} else if (!(flip_1 || flip_2 || flip_3)) {
    std::cout << "All three flips were tails!\n";
}

Errors

• Throws ge211::Client_logic_error if p_true is less than 0.0 or greater than 1.0.

Definition at line 573 of file ge211_random.hxx.

Random_source() [4/4]

Random_source ( unbounded_type  )

explicit

Constructs a Random_source with no predetermined bounds.

Use this with Random_source::operator()(result_type, result_type) or Random_source::next_between(result_type, result_type) to specify the range each time you generate a new number.

Not defined when result_type is bool.

Example

In this example, we generate one random uppercase letter, one random lowercase letter, and one random digit:

ge211::Random_source<char> source(ge211::unbounded);
char upper = source('A', 'Z');
char lower = source('a', 'z');
char digit = source('0', '9');

Definition at line 579 of file ge211_random.hxx.

Member Function Documentation

next()

result_type next ( )

inline

Returns the next random value from this source.

Example

ge211::Random_source<int> one_to_ten(1, 10);
 
int choice = one_to_ten.next();
std::cout << "The random number is " << choice << "\n";

Definition at line 327 of file ge211_random.hxx.

next_between()

result_type next_between ( result_type  lo, result_type  hi  )

inline

Returns a random value between lo and hi.

When using this member function, it is not necessary to initialize your Random_source with bounds, so you should usually construct it using Random_source::Random_source(unbounded_type).

For an example, see Random_source::Random_source(unbounded_type).

Testing

If this Random_source is stubbed (e.g., via Random_source::stub_with(std::initializer_list<result_type>)), the result is computed using the static function Random_source::bound_between():

result_type value = next();  // the next stubbed value
return bound_between(value, lo, hi);

Not defined when result_type is bool.

Definition at line 384 of file ge211_random.hxx.

operator()() [1/2]

result_type operator() ( )

inline

Returns the next random value from this source.

(This is an alias for Random_source::next().)

Example

void try_it(std::size_t n_trials)
{
    ge211::Random_source<bool> fair_coin(0.5);
    std::size_t heads_count = 0;
 
    for (std::size_t i = 0; i < n_trials; ++i) {
        if (fair_coin()) {
            ++heads_count;
        }
    }
 
    double heads_frequency = heads_count / (double) n_trials;
 
    if (heads_frequency < 0.25 || heads_frequency > 0.75) {
        std::cerr << "Doesn't seem so fair!\n";
    }
}

Definition at line 357 of file ge211_random.hxx.

operator()() [2/2]

result_type operator() ( result_type  lo, result_type  hi  )

inline

Returns a random value between lo and hi.

(This is an alias for Random_source::next_between().)

For an example, see Random_source::Random_source(unbounded_type).

Not defined when result_type is bool.

Definition at line 397 of file ge211_random.hxx.

stub_with() [1/3]

void stub_with

(

result_type

value

)

Stubs this Random_source to always return the given value.

If you want to stub multiple values in sequence, see stub_with(std::initializer_list<result_type>) and stub_with(std::vector<result_type>).

Definition at line 599 of file ge211_random.hxx.

stub_with() [2/3]

void stub_with

(

std::initializer_list< result_type >

values

)

Configures this Random_source to return a predetermined sequence of values.

After passing in a list of values, the Random_source will return those values in order, and then cycle through them repeatedly if necessary.

This is intended for testing, in order to make the values chosen by some component predicable.

Example

struct Two_dice
{
    // Source of random die rolls from 1 to 6:
    ge211::Random_source<int> die_source(1, 6);
 
    // Rolls both dice and returns their sum.
    int roll();
};
 
int Two_dice::roll()
{
    int first = die_source.next();
    int second = die_source.next();
    return first + second;
}
 
TEST_CASE("demonstrate random source stubbing"
{
    Model m;
 
    // Perform a random roll and check that the result is in the
    // expected range:
    int sum = m.roll();
    CHECK( 2 <= sum && sum <= 12 );
 
    // Stub the source to return the given sequence, repeatedly:
    m.die_source.stub_with({1, 2, 3, 4, 5});
 
    // Now we can predict the rolls:
    CHECK( m.roll() == 3 );  // rolls 1 and 2
    CHECK( m.roll() == 7 );  // rolls 3 and 4
    CHECK( m.roll() == 6 );  // rolls 5 and 1
    CHECK( m.roll() == 5 );  // rolls 2 and 3
    CHECK( m.roll() == 9 );  // rolls 4 and 5
    CHECK( m.roll() == 3 );  // rolls 1 and 2
    CHECK( m.roll() == 7 );  // rolls 3 and 4
}

Definition at line 592 of file ge211_random.hxx.

stub_with() [3/3]

void stub_with

(

std::vector< result_type >

values

)

Stubs this Random_source using a std::vector.

After passing in a vector of values, the Random_source will return those values in order, and then cycle through them repeatedly if necessary. This works the same as stub_with(std::initializer_list<result_type>), so you should see that function for an example.

Definition at line 585 of file ge211_random.hxx.

---

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

• /Users/tov/school/cs211/dev/ge211/include/ge211_random.hxx