 xtd - Reference Guide 0.2.0
xtd::random Class Reference

#include <random.h>

## Definition

Represents a pseudo-random number generator, a device that produces a sequence of numbers that meet certain statistical requirements for randomness.

Namespace
xtd
Library
xtd.core
Remarks
Pseudo-random numbers are chosen with equal probability from a finite set of numbers. The chosen numbers are not completely random because a definite mathematical algorithm is used to select them, but they are sufficiently random for practical purposes. The current implementation of the random class is based on Donald E. Knuth's subtractive random number generator algorithm. For more information, see D. E. Knuth. "The Art of Computer Programming, volume 2: Seminumerical Algorithms". Addison-Wesley, Reading, MA, second edition, 1981.
The random number generation starts from a seed value. If the same seed is used repeatedly, the same series of numbers is generated. One way to produce different sequences is to make the seed value time-dependent, thereby producing a different series with each new instance of random. By default, the parameterless constructor of the random class uses the system clock to generate its seed value, while its parameterized constructor can take an int32_t value based on the number of ticks in the current time. However, because the clock has finite resolution, using the parameterless constructor to create different random objects in close succession creates random number generators that produce identical sequences of random numbers. The following example illustrates that two random objects that are instantiated in close succession generate an identical series of random numbers.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
int main() {
vector<uint8_t> bytes1(100);
vector<uint8_t> bytes2(100);
rnd1.next_bytes(bytes1);
rnd2.next_bytes(bytes2);
console::write_line("First Series:");
for (size_t i = 0; i < bytes1.size(); i++) {
console::write("{, 5}", bytes1[i]);
if ((i + 1) % 10 == 0)
}
console::write_line("Second Series:");
for (size_t i = 0; i < bytes2.size(); i++) {
console::write("{, 5}", bytes2[i]);
if ((i + 1) % 10 == 0)
}
}
// This code can produces the following output:
//
// First Series:
// 104 222 250 126 113 23 137 65 199 68
// 72 242 71 179 29 70 1 160 135 214
// 129 158 46 16 137 48 66 28 81 190
// 157 155 212 222 3 211 14 137 1 30
// 50 217 229 181 252 55 241 74 230 148
// 153 59 16 152 54 226 11 64 133 236
// 90 255 30 52 45 116 203 193 27 167
// 187 190 68 218 37 16 229 116 150 161
// 183 130 219 90 192 254 24 232 174 116
// 46 191 226 53 118 198 148 29 76 106
//
// Second Series:
// 104 222 250 126 113 23 137 65 199 68
// 72 242 71 179 29 70 1 160 135 214
// 129 158 46 16 137 48 66 28 81 190
// 157 155 212 222 3 211 14 137 1 30
// 50 217 229 181 252 55 241 74 230 148
// 153 59 16 152 54 226 11 64 133 236
// 90 255 30 52 45 116 203 193 27 167
// 187 190 68 218 37 16 229 116 150 161
// 183 130 219 90 192 254 24 232 174 116
// 46 191 226 53 118 198 148 29 76 106
This problem can be avoided by creating a single random object rather than multiple ones.
To improve performance, create one random object to generate many random numbers over time, instead of repeatedly creating a new random objects to generate one random number.
Notes to Callers
The implementation of the random number generator in the random class is not guaranteed to remain the same across major versions of the xtd. As a result, your application code should not assume that the same seed will result in the same pseudo-random sequence in different versions of the xtd.
Notes to Inheritors
In xtd, the behavior of the random::next(), random::next(int32_t, int32_t), and next_bytes methods have changed so that these methods do not necessarily call the derived class implementation of the sample method. As a result, classes derived from Random that target the xtd should also virtual these three methods.
Examples
The following example creates a single random number generator and calls its next_bytes, next, and next_double methods to generate sequences of random numbers within different ranges.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
int main() {
// Instantiate random number generator using system-supplied value as seed.
// Generate and display 5 random uint8_t (integer) values.
vector<uint8_t> bytes(5);
rand.next_bytes(bytes);
console::write_line("Five random uint8_t values:");
for (uint8_t byte_value : bytes)
console::write("{, 5}", byte_value);
// Generate and display 5 random integers.
console::write_line("Five random integer values:");
for (int ctr = 0; ctr <= 4; ctr++)
console::write("{, 15}", rand.next());
// Generate and display 5 random integers between 0 and 100.//
console::write_line("Five random integers between 0 and 100:");
for (int ctr = 0; ctr <= 4; ctr++)
console::write("{, 10}", rand.next(101));
// Generate and display 5 random integers from 50 to 100.
console::write_line("Five random integers between 50 and 100:");
for (int ctr = 0; ctr <= 4; ctr++)
console::write("{, 10}", rand.next(50, 101));
// Generate and display 5 random floating point values from 0 to 1.
console::write_line("Five Doubles:");
for (int ctr = 0; ctr <= 4; ctr++)
console::write("{, 10}", rand.next_double());
// Generate and display 5 random floating point values from 0 to 5.
console::write_line("Five Doubles between 0 and 5:");
for (int ctr = 0; ctr <= 4; ctr++)
console::write("{, 10}", rand.next_double() * 5);
}
// This code can produces the following output:
//
// Five random uint8_t values:
// 150 243 92 141 0
// Five random integer values:
// 4.14343E+08 2.14086E+09 1.73486E+09 1.88133E+09 1.69685E+09
// Five random integers between 0 and 100:
// 35 86 86 68 10
// Five random integers between 50 and 100:
// 76 57 66 97 56
// Five Doubles:
// 0.211096 0.172007 0.507414 0.48576 0.754658
// Five Doubles between 0 and 5:
// 1.40691 2.7078 3.87732 1.0691 0.478343
Examples
The following example generates a random integer that it uses as an index to retrieve a string value from an array.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
int main() {
vector<ustring> male_pet_names = {"Rufus", "Bear", "Dakota", "Fido", "Vanya", "Samuel", "Koani", "Volodya", "Prince", "Yiska"};
vector<ustring> female_pet_names = {"Maggie", "Penny", "Saya", "Princess", "Abby", "Laila", "Sadie", "Olivia", "Starlight", "Talla"};
// Generate random indexes for pet names.
size_t male_index = rnd.next(male_pet_names.size());
size_t female_index = rnd.next(female_pet_names.size());
// Display the result.
console::write_line("Suggested pet name of the day: ");
console::write_line(" For a male: {0}", male_pet_names[male_index]);
console::write_line(" For a female: {0}", female_pet_names[female_index]);
}
// This code can produces the following output:
//
// Suggested pet name of the day:
// For a male: Prince
// For a female: Talla

## Protected Member Functions

virtual double sample () const
Returns a random number between 0.0 and 1.0. More...

## Constructors

random ()
Initializes a new instance of the random class, using a default generated seed value. More...

random (uint32_t seed)
Initializes a new instance of the random class, using a specified seed value. More...

random (std::random_device &random_device)
Initializes a new instance of the random class, using a specified random device value. More...

## Properties

std::default_random_engine generator () const
Gets the underlying generator. More...

## Methods

virtual int32_t next () const
Returns a nonnegative random number. More...

template<typename value_t >
value_t next () const
Returns a nonnegative random number. More...

virtual int32_t next (int32_t max_value) const
Returns a nonnegative random number less than the specified maximum. More...

template<typename value_t >
value_t next (value_t max_value) const
Returns a nonnegative random number less than the specified maximum. More...

virtual int32_t next (int32_t min_value, int32_t max_value) const
Returns a random number within a specified range. More...

template<typename value_t >
value_t next (value_t min_value, value_t max_value) const
Returns a random number within a specified range. More...

virtual void next_bytes (std::vector< uint8_t > &buffer) const
Fills the elements of a specified array of bytes with random numbers. More...

virtual void next_bytes (uint8_t *buffer, size_t buffer_size) const
Fills the elements of a specified array of bytes with random numbers. More...

template<typename value_t >
void next_values (std::vector< value_t > &buffer) const
Fills the elements of a specified array of bytes with random numbers. More...

template<typename value_t >
void next_values (value_t *buffer, size_t buffer_size) const
Fills the elements of a specified array of bytes with random numbers. More...

virtual double next_double () const
Returns a random number between 0.0 and 1.0. More... Public Member Functions inherited from xtd::object
object ()=default
Create a new instance of the ultimate base class object. More...

virtual bool equals (const object &obj) const noexcept
Determines whether the specified object is equal to the current object. More...

virtual size_t get_hash_code () const noexcept
Serves as a hash function for a particular type. More...

template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const
Gets the type of the current instance. More...

virtual xtd::ustring to_string () const noexcept
Returns a sxd::ustring that represents the current object. More... Static Public Member Functions inherited from xtd::object
static bool equals (const object &object_a, const object &object_b) noexcept
Determines whether the specified object instances are considered equal. More...

static bool reference_equals (const object &object_a, const object &object_b) noexcept
Determines whether the specified object instances are the same instance. More...

## ◆ random() [1/3]

 xtd::random::random ( )
inline

Initializes a new instance of the random class, using a default generated seed value.

## ◆ random() [2/3]

 xtd::random::random ( uint32_t seed )
inlineexplicit

Initializes a new instance of the random class, using a specified seed value.

Parameters
 seed A number used to calculate a starting value for the pseudo-random number sequence.

## ◆ random() [3/3]

 xtd::random::random ( std::random_device & random_device )
inlineexplicit

Initializes a new instance of the random class, using a specified random device value.

Parameters
 random_device A random device value.

## ◆ generator()

 std::default_random_engine xtd::random::generator ( ) const
inline

Gets the underlying generator.

Returns
The underlying generator.

## ◆ next() [1/6]

 virtual int32_t xtd::random::next ( ) const
inlinevirtual

Returns a nonnegative random number.

Returns
A 32-bit signed integer greater than or equal to zero and less than std::numeric_limits<int32_t>::max())

## ◆ next() [2/6]

template<typename value_t >
 value_t xtd::random::next ( ) const
inline

Returns a nonnegative random number.

Returns
A value_t greater than or equal to zero and less than std::numeric_limits<value_t>::max()

## ◆ next() [3/6]

 virtual int32_t xtd::random::next ( int32_t max_value ) const
inlinevirtual

Returns a nonnegative random number less than the specified maximum.

Parameters
 max_value The exclusive upper bound of the random number to be generated. max_value must be greater than or equal to zero.
Returns
A 32-bit signed integer greater than or equal to zero and less than max_value
Exceptions
 argument_out_of_range_exception max_value is less than zero.
Remarks
The next(int32_t) overload returns random integers that range from 0 to max_value – 1. However, if max_value is 0, the method returns 0.

## ◆ next() [4/6]

template<typename value_t >
 value_t xtd::random::next ( value_t max_value ) const
inline

Returns a nonnegative random number less than the specified maximum.

Parameters
 max_value The exclusive upper bound of the random number to be generated. max_value must be greater than or equal to zero.
Returns
A value_t greater than or equal to zero and less than max_value
Exceptions
 argument_out_of_range_exception max_value is less than zero.
Remarks
The next(value_t) overload returns random integers that range from 0 to max_value – 1. However, if max_value is 0, the method returns 0.

## ◆ next() [5/6]

 virtual int32_t xtd::random::next ( int32_t min_value, int32_t max_value ) const
inlinevirtual

Returns a random number within a specified range.

Parameters
 min_value The inclusive lower bound of the random number returned max_value The exclusive upper bound of the random number returned. max_value must be greater than or equal to min_value.
Returns
A 32-bit signed integer greater than or equal to min_value and less than max_value
Exceptions
 argument_out_of_range_exception min_value is greater than max_value.
Remarks
The next(int32_t, int32_t) overload returns random integers that range from min_value to max_value – 1. However, if max_value equals min_value, the method returns min_value.
Unlike the other overloads of the next method, which return only non-negative values, this method can return a negative random integer.

## ◆ next() [6/6]

template<typename value_t >
 value_t xtd::random::next ( value_t min_value, value_t max_value ) const
inline

Returns a random number within a specified range.

Parameters
 min_value The inclusive lower bound of the random number returned max_value The exclusive upper bound of the random number returned. max_value must be greater than or equal to min_value.
Returns
A value_t greater than or equal to min_value and less than max_value
Exceptions
 argument_out_of_range_exception min_value is greater than max_value.
Remarks
The next(value_t, value_t) overload returns random integers that range from min_value to max_value – 1. However, if max_value equals min_value, the method returns min_value.
Unlike the other overloads of the next method, which return only non-negative values, this method can return a negative random integer.

## ◆ next_bytes() [1/2]

 virtual void xtd::random::next_bytes ( std::vector< uint8_t > & buffer ) const
inlinevirtual

Fills the elements of a specified array of bytes with random numbers.

Parameters
 buffer An array of bytes to contain random numbers.
Remarks
Each element of the array of bytes is set to a random number greater than or equal to zero, and less than or equal to std::numeric_limits<uint8_t>::max().

## ◆ next_bytes() [2/2]

 virtual void xtd::random::next_bytes ( uint8_t * buffer, size_t buffer_size ) const
inlinevirtual

Fills the elements of a specified array of bytes with random numbers.

Parameters
 buffer An array of bytes to contain random numbers.
Exceptions
 argument_null_exception buffer is null.
Remarks
Each element of the array of bytes is set to a random number greater than or equal to zero, and less than or equal to std::numeric_limits<uint8_t>::max().

## ◆ next_double()

 virtual double xtd::random::next_double ( ) const
inlinevirtual

Returns a random number between 0.0 and 1.0.

Returns
A double-precision floating point number greater than or equal to 0.0, and less than 1.0.
Remarks
This method is the public version of the protected method, sample

## ◆ next_values() [1/2]

template<typename value_t >
 void xtd::random::next_values ( std::vector< value_t > & buffer ) const
inline

Fills the elements of a specified array of bytes with random numbers.

Parameters
 buffer An array of bytes to contain random numbers.
Remarks
Each element of the array of bytes is set to a random number greater than or equal to zero, and less than or equal to std::numeric_limits<value_t>::max().

## ◆ next_values() [2/2]

template<typename value_t >
 void xtd::random::next_values ( value_t * buffer, size_t buffer_size ) const
inline

Fills the elements of a specified array of bytes with random numbers.

Parameters
 buffer An array of value_t to contain random numbers.
Exceptions
 argument_null_exception buffer is null.
Remarks
Each element of the array of values is set to a random number greater than or equal to zero, and less than or equal to std::numeric_limits<value_t>::max().

## ◆ sample()

 virtual double xtd::random::sample ( ) const
inlineprotectedvirtual

Returns a random number between 0.0 and 1.0.

Returns
A double-precision floating point number greater than or equal to 0.0, and less than 1.0.
Remarks
To produce a different random distribution or a different random number generator principle, derive a class from the random class and virtual the sample method.

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