Inheritance diagram for xtd::random:

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 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>

auto main() -> int {

auto bytes1 = array<byte>(100);

auto bytes2 = array<byte>(100);

auto rnd1 = xtd::random {};

auto rnd2 = xtd::random {};

rnd1.next_bytes(bytes1);

rnd2.next_bytes(bytes2);

console::write_line("First Series:");

for (auto i = 0ul; i < bytes1.length(); i++) {

console::write("{, 5}", bytes1[i]);

if ((i + 1) % 10 == 0)

console::write_line();

}

console::write_line();

console::write_line("Second Series:");

for (auto i = 0ul; i < bytes2.length(); i++) {

console::write("{, 5}", bytes2[i]);

if ((i + 1) % 10 == 0)

console::write_line();

}

}

// This code can produce 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

xtd::array
Provides methods for creating, manipulating, searching, and sorting arrays, thereby serving as the ba...
Definition array.hpp:64

xtd::random
Represents a pseudo-random number generator, a device that produces a sequence of numbers that meet c...
Definition random.hpp:42

xtd::random::next_bytes
virtual auto next_bytes(xtd::span< xtd::byte > &buffer) const -> void
Fills the elements of a specified array of bytes with random numbers.

xtd::console_key::i
@ i
The I key.
Definition console_key.hpp:104; 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, int32), 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, typenamees 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>

auto main() -> int {

// Instantiate random number generator using system-supplied value as seed.

auto rand = xtd::random {};

// Generate and display 5 random byte (integer) values.

auto bytes = array<byte>(5);

rand.next_bytes(bytes);

console::write_line("Five random byte values:");

for (auto byte_value : bytes)

console::write("{,5}", byte_value);

console::write_line();

// Generate and display 5 random integers.

console::write_line("Five random integer values:");

for (auto ctr = 0; ctr <= 4; ctr++)

console::write("{,15:N0}", rand.next());

console::write_line();

// Generate and display 5 random integers between 0 and 100.//

console::write_line("Five random integers between 0 and 100:");

for (auto ctr = 0; ctr <= 4; ctr++)

console::write("{,8:N0}", rand.next(101));

console::write_line();

// Generate and display 5 random integers from 50 to 100.

console::write_line("Five random integers between 50 and 100:");

for (auto ctr = 0; ctr <= 4; ctr++)

console::write("{,8:N0}", rand.next(50, 101));

console::write_line();

// Generate and display 5 random floating point values from 0 to 1.

console::write_line("Five Doubles:");

for (auto ctr = 0; ctr <= 4; ctr++)

console::write("{,8:N3}", rand.next_double());

console::write_line();

// Generate and display 5 random floating point values from 0 to 5.

console::write_line("Five Doubles between 0 and 5:");

for (auto ctr = 0; ctr <= 4; ctr++)

console::write("{,8:N3}", rand.next_double() * 5);

console::write_line();

}

// This code can produce the following output :

//

// Five random byte values:

// 56 13 183 186 9

// Five random integer values:

// 393336251 1630901725 159175947 1510060072 592602585

// Five random integers between 0 and 100:

// 26 50 32 9 50

// Five random integers between 50 and 100:

// 84 63 52 69 68

// Five Doubles:

// 0.186 0.070 0.021 0.892 0.313

// Five Doubles between 0 and 5:

// 2.938 0.848 0.060 3.667 0.042

xtd::console::write
static auto write(arg_t &&value) -> void
Writes the text representation of the specified value to the standard output stream.
Definition console.hpp:480

xtd::console::write_line
static auto write_line() -> void
Writes the current line terminator to the standard output stream using the specified format informati...

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>

auto main() -> int {

auto rnd = xtd::random {};

auto male_pet_names = array {"Rufus", "Bear", "Dakota", "Fido", "Vanya", "Samuel", "Koani", "Volodya", "Prince", "Yiska"};

auto female_pet_names = array {"Maggie", "Penny", "Saya", "Princess", "Abby", "Laila", "Sadie", "Olivia", "Starlight", "Talla"};

// Generate random indexes for pet names.

auto male_index = rnd.next(male_pet_names.length());

auto female_index = rnd.next(female_pet_names.length());

// 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 produce the following output :

//

// Suggested pet name of the day:

// For a male: Prince

// For a female: Talla

Examples: as.cpp, change_color.cpp, console_firework.cpp, draw_point.cpp, interlocked.cpp, lock.cpp, lock_guard.cpp, lock_guard_keyword.cpp, minesweeper.cpp, monitor.cpp, random1.cpp, random2.cpp, random3.cpp, and wait_handle.cpp.

Protected Member Functions
virtual auto	sample () const -> double
	Returns a random number between 0.0 and 1.0.

Public Constructors
	random ()
	Initializes a new instance of the random class, using a default generated seed value.
	random (xtd::uint32 seed)
	Initializes a new instance of the random class, using a specified seed value.
	random (std::random_device &random_device)
	Initializes a new instance of the random class, using a specified random device value.

Public Properties
auto	generator () const noexcept -> const std::default_random_engine &
	Gets the underlying generator.
auto	generator () noexcept -> std::default_random_engine &
	Gets the underlying generator.

Public Methods
template<typename value_t>
auto	get_items (const xtd::read_only_span< value_t > &choices, xtd::usize length) -> xtd::array< value_t >
	Creates an array populated with items chosen at random from the provided set of choices.
template<typename value_t>
auto	get_items (const xtd::array< value_t > &choices, xtd::usize length) -> xtd::array< value_t >
	Creates an array populated with items chosen at random from the provided set of choices.
template<typename value_t>
auto	get_items (const xtd::read_only_span< value_t > &choices, xtd::span< value_t > &destination) -> void
	Fills the elements of a specified span with items chosen at random from the provided set of choices.
virtual auto	next () const -> xtd::int32
	Returns a nonnegative random number.
template<typename value_t>
auto	next () const -> value_t
	Returns a nonnegative random number.
virtual auto	next (xtd::int32 max_value) const -> xtd::int32
	Returns a nonnegative random number less than the specified maximum.
template<typename value_t>
auto	next (value_t max_value) const -> value_t
	Returns a nonnegative random number less than the specified maximum.
virtual auto	next (xtd::int32 min_value, xtd::int32 max_value) const -> xtd::int32
	Returns a random number within a specified range.
template<typename value_t>
auto	next (value_t min_value, value_t max_value) const -> value_t
	Returns a random number within a specified range.
virtual auto	next_byte () const -> xtd::byte
	Returns a nonnegative random number.
virtual auto	next_byte (xtd::byte max_value) const -> xtd::byte
	Returns a nonnegative random number less than the specified maximum.
virtual auto	next_byte (xtd::byte min_value, xtd::byte max_value) const -> xtd::byte
	Returns a random number within a specified range.
virtual auto	next_bytes (xtd::span< xtd::byte > &buffer) const -> void
	Fills the elements of a specified array of bytes with random numbers.
virtual auto	next_bytes (xtd::array< xtd::byte > &buffer) const -> void
	Fills the elements of a specified array of bytes with random numbers.
virtual auto	next_double () const -> double
	Returns a random number between 0.0 and 1.0.
template<typename value_t>
auto	next_values (xtd::span< value_t > &buffer) const -> void
	Fills the elements of a specified xtd::span of bytes with random numbers.
template<typename value_t>
auto	next_values (xtd::array< value_t > &buffer) const -> void
	Fills the elements of a specified array of bytes with random numbers.
virtual auto	next_int64 () const -> xtd::int64
	Returns a nonnegative random number.
virtual auto	next_int64 (int64 max_value) const -> xtd::int64
	Returns a nonnegative random number less than the specified maximum.
virtual auto	next_int64 (int64 min_value, int64 max_value) const -> xtd::int64
	Returns a random number within a specified range.
virtual auto	next_single () const -> xtd::single
	Returns a random number between 0.0 and 1.0.
template<typename value_t>
auto	shuffle (xtd::span< value_t > &values) const -> xtd::span< value_t > &
	Performs an in-place shuffle of a span.
template<typename collection_t>
auto	shuffle (collection_t &values) const -> collection_t &
	Performs an in-place shuffle of an array.
template<typename collection_t>
auto	shuffle (const collection_t &values) const -> collection_t
	Performs an in-place shuffle of an array.

Additional Inherited Members
	object ()=default
	Create a new instance of the ultimate base class object.
virtual auto	equals (const object &obj) const noexcept -> bool
	Determines whether the specified object is equal to the current object.
virtual auto	get_hash_code () const noexcept -> xtd::usize
	Serves as a hash function for a particular type.
virtual auto	get_type () const noexcept -> type_object
	Gets the type of the current instance.
template<typename object_t>
auto	memberwise_clone () const -> xtd::unique_ptr_object< object_t >
	Creates a shallow copy of the current object.
virtual auto	to_string () const -> xtd::string
	Returns a xtd::string that represents the current object.
template<typename object_a_t, typename object_b_t>
static auto	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	Determines whether the specified object instances are considered equal.
template<typename object_a_t, typename object_b_t>
static auto	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	Determines whether the specified object instances are the same instance.

Constructor & Destructor Documentation

◆ random() [1/3]

xtd::random::random ( )

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

◆ random() [2/3]

xtd::random::random ( xtd::uint32 seed )

explicit

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 )

explicit

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

Parameters

random_device A random device value.

Member Function Documentation

◆ generator() [1/2]

auto xtd::random::generator ( ) const -> const std::default_random_engine &

nodiscardnoexcept

Gets the underlying generator.

Returns: The underlying generator.

◆ generator() [2/2]

auto xtd::random::generator ( ) -> std::default_random_engine &

nodiscardnoexcept

Gets the underlying generator.

Returns: The underlying generator.

◆ get_items() [1/3]

template<typename value_t>

auto xtd::random::get_items	(	const xtd::read_only_span< value_t > &	choices,
		xtd::usize	length ) -> xtd::array< value_t >

inlinenodiscard

Creates an array populated with items chosen at random from the provided set of choices.

Parameters

choices	Set of choices.
length	The length of the populated array.

◆ get_items() [2/3]

template<typename value_t>

auto xtd::random::get_items	(	const xtd::array< value_t > &	choices,
		xtd::usize	length ) -> xtd::array< value_t >

inlinenodiscard

Creates an array populated with items chosen at random from the provided set of choices.

Parameters

choices	Set of choices.
length	The length of the populated array.

◆ get_items() [3/3]

template<typename value_t>

auto xtd::random::get_items	(	const xtd::read_only_span< value_t > &	choices,
		xtd::span< value_t > &	destination ) -> void

inline

Fills the elements of a specified span with items chosen at random from the provided set of choices.

Parameters

choices	Set of choices.
destination	The elements to fill.

◆ next() [1/6]

virtual auto xtd::random::next ( ) const -> xtd::int32

nodiscardvirtual

Returns a nonnegative random number.

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

Examples: minesweeper.cpp, and random3.cpp.

◆ next() [2/6]

template<typename value_t>

auto xtd::random::next ( ) const -> value_t

inlinenodiscard

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 auto xtd::random::next ( xtd::int32 max_value ) const -> xtd::int32

nodiscardvirtual

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) 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>

auto xtd::random::next ( value_t max_value ) const -> value_t

inlinenodiscard

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 auto xtd::random::next	(	xtd::int32	min_value,
		xtd::int32	max_value ) const -> xtd::int32

nodiscardvirtual

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, int32) 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>

auto xtd::random::next	(	value_t	min_value,
		value_t	max_value ) const -> value_t

inlinenodiscard

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_byte() [1/3]

virtual auto xtd::random::next_byte ( ) const -> xtd::byte

nodiscardvirtual

Returns a nonnegative random number.

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

◆ next_byte() [2/3]

virtual auto xtd::random::next_byte ( xtd::byte max_value ) const -> xtd::byte

nodiscardvirtual

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 64-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) overload returns random integers that range from 0 to max_value – 1. However, if max_value is 0, the method returns 0.

◆ next_byte() [3/3]

virtual auto xtd::random::next_byte	(	xtd::byte	min_value,
		xtd::byte	max_value ) const -> xtd::byte

nodiscardvirtual

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 8-bit unsigned 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, int32) 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 auto xtd::random::next_bytes ( xtd::span< xtd::byte > & buffer ) const -> void

virtual

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<xtd::byte>::max().

Examples: random1.cpp.

◆ next_bytes() [2/2]

virtual auto xtd::random::next_bytes ( xtd::array< xtd::byte > & buffer ) const -> void

virtual

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<xtd::byte>::max().

◆ next_double()

virtual auto xtd::random::next_double ( ) const -> double

nodiscardvirtual

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>

auto xtd::random::next_values ( xtd::span< value_t > & buffer ) const -> void

inline

Fills the elements of a specified xtd::span of bytes with random numbers.

Parameters

buffer An xtd::span 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>

auto xtd::random::next_values ( xtd::array< value_t > & buffer ) const -> void

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_int64() [1/3]

virtual auto xtd::random::next_int64 ( ) const -> xtd::int64

nodiscardvirtual

Returns a nonnegative random number.

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

◆ next_int64() [2/3]

virtual auto xtd::random::next_int64 ( int64 max_value ) const -> xtd::int64

nodiscardvirtual

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 64-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) overload returns random integers that range from 0 to max_value – 1. However, if max_value is 0, the method returns 0.

◆ next_int64() [3/3]

virtual auto xtd::random::next_int64	(	int64	min_value,
		int64	max_value ) const -> xtd::int64

nodiscardvirtual

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 64-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, int32) 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_single()

virtual auto xtd::random::next_single ( ) const -> xtd::single

nodiscardvirtual

Returns a random number between 0.0 and 1.0.

Returns: A single-precision floating point number greater than or equal to 0.0, and less than 1.0.

◆ shuffle() [1/3]

template<typename value_t>

auto xtd::random::shuffle ( xtd::span< value_t > & values ) const -> xtd::span< value_t > &

inline

Performs an in-place shuffle of a span.

Parameters

values The span to shuffle.

◆ shuffle() [2/3]

template<typename collection_t>

auto xtd::random::shuffle ( collection_t & values ) const -> collection_t &

inline

Performs an in-place shuffle of an array.

Parameters

values The array to shuffle.

◆ shuffle() [3/3]

template<typename collection_t>

auto xtd::random::shuffle ( const collection_t & values ) const -> collection_t

inline

Performs an in-place shuffle of an array.

Parameters

values The array to shuffle.

◆ sample()

virtual auto xtd::random::sample ( ) const -> double

nodiscardprotectedvirtual

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:

xtd.core/include/xtd/random.hpp

Definition

Protected Member Functions

Public Constructors

Public Properties

Public Methods

Additional Inherited Members

Constructor & Destructor Documentation

◆ random() [1/3]

◆ random() [2/3]

◆ random() [3/3]

Member Function Documentation

◆ generator() [1/2]

◆ generator() [2/2]

◆ get_items() [1/3]

◆ get_items() [2/3]

◆ get_items() [3/3]

◆ next() [1/6]

◆ next() [2/6]

◆ next() [3/6]

◆ next() [4/6]

◆ next() [5/6]

◆ next() [6/6]

◆ next_byte() [1/3]

◆ next_byte() [2/3]

◆ next_byte() [3/3]

◆ next_bytes() [1/2]

◆ next_bytes() [2/2]

◆ next_double()

◆ next_values() [1/2]

◆ next_values() [2/2]

◆ next_int64() [1/3]

◆ next_int64() [2/3]

◆ next_int64() [3/3]

◆ next_single()

◆ shuffle() [1/3]

◆ shuffle() [2/3]

◆ shuffle() [3/3]

◆ sample()