1 /* $Id: weightedrandom.hpp,v 1.4 2005/06/28 13:55:26 chfreund Exp $ */ 2 3 #ifndef _WEIGHTEDRANDOM_HPP_ 4 #define _WEIGHTEDRANDOM_HPP_ 5 6 #include "random.hpp" 7 8 /**********************************************************/ 9 10 //! extention of class Random, thats supports weighted randomness 11 12 /*! This class supports the specification of probability weights for 13 * the occurence of a random number in an interval [1,n-1]. These 14 * weights must be provided as odds relations. For example the weights 15 * 1:5:6 would cause a probability 1/12,5/12,1/2, or generally: If 16 * \f$ w_i \f$ is the weight [i], the random number i will have the 17 * probability \f$ \frac{w_i}{\sum_{k=0}^n w_i} \f$. These weights 18 * are inserted into the class by the function setWeights. 19 */ 20 class WeightedRandom : public Random 21 { 22 public: 23 24 //! constructor: the seed is piped to the base class 25 WeightedRandom( const unsigned int seed = 0 ); 26 //! destructor 27 virtual ~WeightedRandom(); 28 29 //! sets the random weights and fixes the range of the PRN 30 31 /*! This function sets range of the random numbers, that are 32 * returned by getWeightedUint32(), and their probability. 33 * There are three possible modes: 34 * - nWeights == 0: eventually present weights will be 35 * removed and getWeightedUint32 will return an arbitrary 36 * random number >= 0 from now on, just like 37 * Random::getUint32(). 38 * - nWeights > 0 and Weights == NULL: eventually present 39 * weights will be removed, and getWeightedUint32() will 40 * return a uniformly distributed number in the range 41 * [0,nWeights-1]. 42 * - nWeights > 0 and Weights != NULL: the number of weights 43 * at Weights must be greater than or equal to nWeights. 44 * From now on getWeightedUint32() will return a random 45 * number in range [0,nWeights-1] with the passed weighted 46 * probability. 47 * \param nWeights fixes the range of the random numbers 48 * returned by getWeightedUint32() to [0,nWeights-1] 49 * \param Weights (optional) must contain nWeights odds. 50 * The buffer, that will contain the weights used 51 * by the class furtheron is created internally (i.e. 52 * the weights are copied). Therefore the memory at 53 * Wheights can be deleted after this call. 54 * \return true, if the demanded setting could be fixed, 55 * otherwise false. 56 */ 57 bool setWeights( const int nWeights, 58 const int *const Weights = NULL ); 59 60 //! returns a random number (for details see function setWeights) 61 62 /*! Implementation details: If valid interval boundaries are 63 * present, the function getWeightedUint32() so far selects the 64 * interval i (0 <= i <= m_NumIntervals), in which a random 65 * number r (0 <= r <= m_Intervals[m_NumIntervals-1]) lies, 66 * using a linear search. For large values of m_Intervals a 67 * binary search will get faster, but for the usage in WoP the 68 * linear search does not show any disadvantages. 69 */ 70 Uint32 getWeightedUint32(); 71 72 //! \name (de)serialization 73 //@{ 74 virtual Uint32 getSerializeBufferSize() const; 75 virtual void serialize( Uint8*& bufferPointer ) const; 76 virtual void deserialize( Uint8*& bufferPointer ); 77 //@} 78 79 protected: 80 81 Uint32 m_NumIntervals, //!< the number of interval boundaries at m_Intervals 82 *m_Intervals; //!< the interval boundaries 83 }; 84 85 /**********************************************************/ 86 87 #endif // _WEIGHTEDRANDOM_HPP_ 88