xtd::random Class Reference

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/console>
#include <xtd/random>
 
using namespace 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.size(); 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.size(); 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

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, 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/console>
#include <xtd/random>
 
using namespace 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

Examples

The following example generates a random integer that it uses as an index to retrieve a string value from an array.

#include <xtd/console>
#include <xtd/random>
 
using namespace 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.size());
  auto 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 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, graph_control.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 double	sample () const
	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 (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
const std::default_random_engine &	generator () const noexcept
	Gets the underlying generator.
std::default_random_engine &	generator () noexcept
	Gets the underlying generator.

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

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual xtd::size	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t >
xtd::uptr< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const noexcept
	Returns a xtd::string that represents the current object.
Static Public Member Functions inherited from xtd::object
template<class object_a_t , class object_b_t >
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<class object_a_t , class object_b_t >
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	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 ( 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]

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

noexcept

Gets the underlying generator.

Returns

The underlying generator.

generator() [2/2]

std::default_random_engine & xtd::random::generator ( )

noexcept

Gets the underlying generator.

Returns

The underlying generator.

get_items() [1/3]

template<class value_t >

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

inline

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

xtd::array< value_t > xtd::random::get_items ( const xtd::array< value_t > &  choices, xtd::size  length  )

inline

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

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

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

virtual

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

draw_point.cpp, lock.cpp, lock_guard_keyword.cpp, and minesweeper.cpp.

next() [2/6]

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

virtual

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

virtual

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<class 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 ( xtd::span< xtd::byte > &  buffer ) const

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 void xtd::random::next_bytes ( xtd::array< xtd::byte > &  buffer ) const

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 double xtd::random::next_double ( ) const

virtual

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

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

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

void xtd::random::next_values ( xtd::array< 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_int64() [1/3]

virtual int64 xtd::random::next_int64 ( ) const

virtual

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 int64 xtd::random::next_int64 ( int64  max_value ) const

virtual

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 int64 xtd::random::next_int64 ( int64  min_value, int64  max_value  ) const

virtual

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 single xtd::random::next_single ( ) const

virtual

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/2]

template<class value_t >

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

inline

Performs an in-place shuffle of a span.

Parameters

values

The span to shuffle.

shuffle() [2/2]

template<class collection_t >

void xtd::random::shuffle ( collection_t &  values ) const

inline

Performs an in-place shuffle of an array.

Parameters

values

The array to shuffle.

sample()

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

protectedvirtual

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