Class entropy_source

Synopsis

#include "breeze/random/entropy_source.hpp"

class entropy_source

Description

The system entropy source (random numbers).

This class represents the system entropy source, for generating non-deterministic (i.e. non-pseudo-random) random numbers.

It is similar to std::random_device but predates it and is more portable. Differently from the standard version, it is not implemented on systems which don't have a usable non-deterministic source (but, as of writing this, there's no such a system among those supported by Breeze).

Also differently from std::random_device, this class does not have an entropy() member, as that would be of dubious usefulness (see e.g. https://codingnest.com/generating-random-numbers-using-c-standard-library-the-problems/).

Note

This class is designed to satisfy the requirements of a uniform random number generator (C++11, [rand.req.urng]), except that, to be honest, I don't know what the complexity of the function call operator is. (These requirements are, by the way, why it has members named "min" and "max", which I generally avoid, given that many sources define homonym macros.)

Classes

exception

The type of exceptions thrown by the members of entropy_source.

Methods

	entropy_source overload	Deleted copy constructor.
	entropy_source overload	Acquires the resource(s) necessary to generate random numbers.
	~entropy_source	Calls release(), ignoring its return value, and destroys the object.
	max	Returns: The maximum random number that can be emitted (typically, 255).
	min	Returns: The minimum random number that can be emitted, i.e
	next	Returns: A new random value, evenly distributed in [min(), max()].
	operator() overload	The same as next().
	operator() overload	Returns: A new random value in the range [min(), maximum] .
	operator() overload	Returns: A new random value in the range [minimum, maximum] .
	operator=	Deleted copy assignment operator.
	release	Releases the system resource(s) associated with this object (usually a file or a handle).

Source

Lines 51-170 in breeze/random/entropy_source.hpp.

class entropy_source
{
public:
    //!     Deleted copy constructor.
    // -----------------------------------------------------------------------
                        entropy_source( entropy_source const & ) = delete ;

    //!     Deleted copy assignment operator.
    // -----------------------------------------------------------------------
    entropy_source &    operator =(     entropy_source const & ) = delete ;

    //!     The type of the random numbers returned (or, which is the
    //!     same, the return type of the \c next() function).
    //!
    //!     Guaranteed to be \e unsigned and different from \c char and
    //!     <code>unsigned char</code>.
    //!
    //!     Note that the system entropy source may work on a smaller
    //!     type (typically <code>unsigned char</code>); but we don't
    //!     use \c char or <code>unsigned char</code> on the interface
    //!     because we don't want things like
    //!
    //!     \code
    //!         std::cout << rnd.next() ;
    //!     \endcode
    //!
    //!     to output a character instead of a number.
    // -----------------------------------------------------------------------
    typedef unsigned int
                        result_type ;

    class               exception ;

    //!     Acquires the resource(s) necessary to generate random
    //!     numbers.
    //!
    //!     \par Exceptions
    //!         May throw an \c entropy_source::exception or a \c
    //!         std::bad_alloc.
    // -----------------------------------------------------------------------
                        entropy_source() ;

    //!     Calls \c release(), ignoring its return value, and destroys
    //!     the object.
    // -----------------------------------------------------------------------
                        ~entropy_source() noexcept ;

    //!     \return
    //!         A new random value, evenly distributed in <tt>[min(),
    //!         max()]</tt>.
    //!
    //!     \par Exceptions
    //!         An \c entropy_source::exception if the random number
    //!         cannot be generated.
    // -----------------------------------------------------------------------
    result_type         next() ;

    //!     \return
    //!         The minimum random number that can be emitted, i.e.
    //!         zero.
    // -----------------------------------------------------------------------
    static constexpr result_type
                        min BREEZE_PREVENT_MACRO_EXPANSION () noexcept ;

    //!     \return
    //!         The maximum random number that can be emitted
    //!         (typically, <tt>255</tt>).
    // -----------------------------------------------------------------------
    static constexpr result_type
                        max BREEZE_PREVENT_MACRO_EXPANSION () noexcept ;

    //!     The same as \c next().
    // -----------------------------------------------------------------------
    result_type         operator ()() ;

    //!     \return
    //!         A new random value in the range <code>[min(), maximum]
    //!         </code>.
    //!
    //!     \pre
    //!         maximum <= max()
    // -----------------------------------------------------------------------
    result_type         operator ()( result_type maximum ) ;

    //!     \return
    //!         A new random value in the range <code>[minimum, maximum]
    //!         </code>.
    //!
    //!     \pre
    //!         minimum <= maximum
    //!         maximum - minimum <= max()
    // -----------------------------------------------------------------------
    result_type         operator ()( result_type minimum,
                                     result_type maximum ) ;

    //!     Releases the system resource(s) associated with this object
    //!     (usually a file or a handle).
    //!
    //!     This function is called by the destructor, but calling it
    //!     manually allows checking for errors.
    //!
    //!     \return
    //!         \c true if and only if the resource(s) were successfully
    //!         released.
    //!
    //!     \par Exceptions
    //!         none (reports via its return value)
    //!
    //!     \note
    //!         This function may be called multiple times. After
    //!         calling \c release(), the only functions that can be
    //!         called on the object are \c release() and the
    //!         destructor.
    // -----------------------------------------------------------------------
    bool                release() noexcept ;

private:
    class               impl ;
    impl * const        m_impl ;
} ;