dlib C++ Library - rand_kernel_abstract.h

    // Copyright (C) 2003  Davis E. King (davis@dlib.net)
    // License: Boost Software License   See LICENSE.txt for the full license.
    #undef DLIB_RAND_KERNEl_ABSTRACT_
    #ifdef DLIB_RAND_KERNEl_ABSTRACT_

    #include <string>
    #include <complex>
    #include "../uintn.h"

    namespace dlib
    {

        class rand
        {

            /*!
                INITIAL VALUE
                    get_seed() == ""

                WHAT THIS OBJECT REPRESENTS
                    This object represents a pseudorandom number generator.
            !*/

            public:

                rand(
                );
                /*!
                    ensures
                        - #*this is properly initialized
                    throws
                        - std::bad_alloc
                !*/

                rand (
                    time_t seed_value
                );
                /*!
                    ensures
                        - #*this is properly initialized
                        - #get_seed() == cast_to_string(seed_value)
                        - This version of the constructor is equivalent to using
                          the default constructor and then calling set_seed(cast_to_string(seed_value))
                    throws
                        - std::bad_alloc
                !*/

                rand (
                    const std::string& seed_value
                );
                /*!
                    ensures
                        - #*this is properly initialized
                        - #get_seed() == seed_value
                        - This version of the constructor is equivalent to using
                          the default constructor and then calling set_seed(seed_value)
                    throws
                        - std::bad_alloc
                !*/

                virtual ~rand(
                );
                /*!
                    ensures
                        - all memory associated with *this has been released
                !*/

                void clear(
                );
                /*!
                    ensures
                        - #*this has its initial value
                    throws
                        - std::bad_alloc
                            if this exception is thrown then *this is unusable
                            until clear() is called and succeeds
                !*/

                const std::string& get_seed (
                );
                /*!
                    ensures
                        - returns the string currently being used as the random seed.
                !*/

                void set_seed (
                    const std::string& value
                );
                /*!
                    ensures
                        - #get_seed() == value
                !*/

                unsigned char get_random_8bit_number (
                );
                /*!
                    ensures
                        - returns a pseudorandom number in the range 0 to 255
                !*/

                uint16 get_random_16bit_number (
                );
                /*!
                    ensures
                        - returns a pseudorandom number in the range 0 to 2^16-1
                !*/

                uint32 get_random_32bit_number (
                );
                /*!
                    ensures
                        - returns a pseudorandom number in the range 0 to 2^32-1
                !*/

                uint64 get_random_64bit_number (
                );
                /*!
                    ensures
                        - returns a pseudorandom number in the range 0 to 2^64-1
                !*/

                float get_random_float (
                );
                /*!
                    ensures
                        - returns a random float number N where:  0.0 <= N < 1.0.
                !*/

                double get_random_double (
                );
                /*!
                    ensures
                        - returns a random double number N where:  0.0 <= N < 1.0.
                !*/

                double get_double_in_range (
                    double begin,
                    double end
                );
                /*!
                    requires
                        - begin <= end
                    ensures
                        - if (begin < end) then
                            - returns a random double number N where:  begin <= N < end.
                        - else
                            - returns begin
                !*/

                long long get_integer_in_range(
                    long long begin,
                    long long end
                );
                /*!
                    requires
                        - begin <= end
                    ensures
                        - returns a random integer N selected from the range: begin <= N < end
                          The integer is selected uniformly at random.  If begin==end then
                          begin is returned.
                !*/

                long long get_integer(
                    long long end
                );
                /*!
                    requires
                        - 0 <= end
                    ensures
                        - returns get_integer_in_range(0,end)
                !*/

                double get_random_gaussian (
                );
                /*!
                    ensures
                        - returns a random number sampled from a Gaussian distribution
                          with mean 0 and standard deviation 1.
                !*/

                std::complex<double> get_random_complex_gaussian (
                );
                /*!
                    ensures
                        - returns a random complex number sampled from a Gaussian distribution
                          with mean 0 and standard deviation 1.
                !*/

                double get_random_exponential (
                    double lambda
                );
                /*!
                    ensures
                        - returns a random number sampled from an exponential distribution
                          with rate parameter lambda
                !*/

                double get_random_weibull (
                    double lambda,
                    double k,
                    double gamma
                );
                /*!
                    ensures
                        - returns a random number sampled from a Weibull distribution
                          with shape parameter k, scale parameter lambda and
                          threshold parameter gamma.
                !*/

                double get_random_beta (
                    double alpha,
                    double beta,
                )
                /*!
                    requires
                        - alpha > 0
                        - beta > 0
                    ensures
                        - returns a random number sampled from a Beta distribution
                          with shape parameters alpha and beta.
                !*/

                void swap (
                    rand& item
                );
                /*!
                    ensures
                        - swaps *this and item
                !*/

        };

        inline void swap (
            rand& a,
            rand& b
        ) { a.swap(b); }
        /*!
            provides a global swap function
        !*/

        void serialize (
            const rand& item,
            std::ostream& out
        );
        /*!
            provides serialization support
        !*/

        void deserialize (
            rand& item,
            std::istream& in
        );
        /*!
            provides deserialization support
        !*/
    }

    #endif // DLIB_RAND_KERNEl_ABSTRACT_