boost/random/bernoulli_distribution.hpp

0001 /* boost random/bernoulli_distribution.hpp header file
0002  *
0003  * Copyright Jens Maurer 2000-2001
0004  * Copyright Steven Watanabe 2011
0005  * Distributed under the Boost Software License, Version 1.0. (See
0006  * accompanying file LICENSE_1_0.txt or copy at
0007  * http://www.boost.org/LICENSE_1_0.txt)
0008  *
0009  * See http://www.boost.org for most recent version including documentation.
0010  *
0011  * $Id$
0012  *
0013  * Revision history
0014  *  2001-02-18  moved to individual header files
0015  */
0016
0017 #ifndef BOOST_RANDOM_BERNOULLI_DISTRIBUTION_HPP
0018 #define BOOST_RANDOM_BERNOULLI_DISTRIBUTION_HPP
0019
0020 #include <iosfwd>
0021 #include <boost/assert.hpp>
0022 #include <boost/random/detail/config.hpp>
0023 #include <boost/random/detail/operators.hpp>
0024
0025 namespace boost {
0026 namespace random {
0027
0028 /**
0029  * Instantiations of class template \bernoulli_distribution model a
0030  * \random_distribution. Such a random distribution produces bool values
0031  * distributed with probabilities P(true) = p and P(false) = 1-p. p is
0032  * the parameter of the distribution.
0033  */
0034 template<class RealType = double>
0035 class bernoulli_distribution
0036 {
0037 public:
0038     // In principle, this could work with both integer and floating-point
0039     // types.  Generating floating-point random numbers in the first
0040     // place is probably more expensive, so use integer as input.
0041     typedef int input_type;
0042     typedef bool result_type;
0043
0044     class param_type
0045     {
0046     public:
0047
0048         typedef bernoulli_distribution distribution_type;
0049
0050         /**
0051          * Constructs the parameters of the distribution.
0052          *
0053          * Requires: 0 <= p <= 1
0054          */
0055         explicit param_type(RealType p_arg = RealType(0.5))
0056           : _p(p_arg)
0057         {
0058             BOOST_ASSERT(_p >= 0);
0059             BOOST_ASSERT(_p <= 1);
0060         }
0061
0062         /** Returns the p parameter of the distribution. */
0063         RealType p() const { return _p; }
0064
0065         /** Writes the parameters to a std::ostream. */
0066         BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, param_type, parm)
0067         {
0068             os << parm._p;
0069             return os;
0070         }
0071
0072         /** Reads the parameters from a std::istream. */
0073         BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, param_type, parm)
0074         {
0075             is >> parm._p;
0076             return is;
0077         }
0078
0079         /** Returns true if the two sets of parameters are equal. */
0080         BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(param_type, lhs, rhs)
0081         { return lhs._p == rhs._p; }
0082
0083         /** Returns true if the two sets of parameters are different. */
0084         BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(param_type)
0085
0086     private:
0087         RealType _p;
0088     };
0089
0090     /**
0091      * Constructs a \bernoulli_distribution object.
0092      * p is the parameter of the distribution.
0093      *
0094      * Requires: 0 <= p <= 1
0095      */
0096     explicit bernoulli_distribution(const RealType& p_arg = RealType(0.5))
0097       : _p(p_arg)
0098     {
0099         BOOST_ASSERT(_p >= 0);
0100         BOOST_ASSERT(_p <= 1);
0101     }
0102     /**
0103      * Constructs \bernoulli_distribution from its parameters
0104      */
0105     explicit bernoulli_distribution(const param_type& parm)
0106       : _p(parm.p()) {}
0107
0108     // compiler-generated copy ctor and assignment operator are fine
0109
0110     /**
0111      * Returns: The "p" parameter of the distribution.
0112      */
0113     RealType p() const { return _p; }
0114
0115     /** Returns the smallest value that the distribution can produce. */
0116     bool min BOOST_PREVENT_MACRO_SUBSTITUTION () const
0117     { return false; }
0118     /** Returns the largest value that the distribution can produce. */
0119     bool max BOOST_PREVENT_MACRO_SUBSTITUTION () const
0120     { return true; }
0121
0122     /** Returns the parameters of the distribution. */
0123     param_type param() const { return param_type(_p); }
0124     /** Sets the parameters of the distribution. */
0125     void param(const param_type& parm) { _p = parm.p(); }
0126
0127     /**
0128      * Effects: Subsequent uses of the distribution do not depend
0129      * on values produced by any engine prior to invoking reset.
0130      */
0131     void reset() { }
0132
0133     /**
0134      * Returns: a random variate distributed according to the
0135      * \bernoulli_distribution.
0136      */
0137     template<class Engine>
0138     bool operator()(Engine& eng) const
0139     {
0140         if(_p == RealType(0))
0141             return false;
0142         else
0143             return RealType(eng() - (eng.min)()) <= _p * RealType((eng.max)()-(eng.min)());
0144     }
0145
0146     /**
0147      * Returns: a random variate distributed according to the
0148      * \bernoulli_distribution with parameters specified by param.
0149      */
0150     template<class Engine>
0151     bool operator()(Engine& eng, const param_type& parm) const
0152     {
0153         return bernoulli_distribution(parm)(eng);
0154     }
0155
0156     /**
0157      * Writes the parameters of the distribution to a @c std::ostream.
0158      */
0159     BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, bernoulli_distribution, bd)
0160     {
0161         os << bd._p;
0162         return os;
0163     }
0164
0165     /**
0166      * Reads the parameters of the distribution from a @c std::istream.
0167      */
0168     BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, bernoulli_distribution, bd)
0169     {
0170         is >> bd._p;
0171         return is;
0172     }
0173
0174     /**
0175      * Returns true iff the two distributions will produce identical
0176      * sequences of values given equal generators.
0177      */
0178     BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(bernoulli_distribution, lhs, rhs)
0179     { return lhs._p == rhs._p; }
0180
0181     /**
0182      * Returns true iff the two distributions will produce different
0183      * sequences of values given equal generators.
0184      */
0185     BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(bernoulli_distribution)
0186
0187 private:
0188     RealType _p;
0189 };
0190
0191 } // namespace random
0192
0193 using random::bernoulli_distribution;
0194
0195 } // namespace boost
0196
0197 #endif // BOOST_RANDOM_BERNOULLI_DISTRIBUTION_HPP