/* $Id: weightedrandom.hpp,v 1.4 2005/06/28 13:55:26 chfreund Exp $ */

#ifndef  _WEIGHTEDRANDOM_HPP_
#define  _WEIGHTEDRANDOM_HPP_

#include  "random.hpp"

/**********************************************************/

//! extention of class Random, thats supports weighted randomness

/*! This class supports the specification of probability weights for
 *  the occurence of a random number in an interval [1,n-1]. These
 *  weights must be provided as odds relations. For example the weights
 *  1:5:6 would cause a probability 1/12,5/12,1/2, or generally: If
 *  \f$ w_i \f$ is the weight [i], the random number i will have the
 *  probability \f$ \frac{w_i}{\sum_{k=0}^n w_i} \f$. These weights
 *  are inserted into the class by the function setWeights.
 */
class WeightedRandom : public Random
{
	public:

		//! constructor: the seed is piped to the base class
		WeightedRandom( const unsigned int seed = 0 );
		//! destructor
		virtual ~WeightedRandom();

		//! sets the random weights and fixes the range of the PRN

		/*! This function sets range of the random numbers, that are
		 *  returned by getWeightedUint32(), and their probability.
		 *  There are three possible modes:
		 *   - nWeights == 0: eventually present weights will be
		 *     removed and getWeightedUint32 will return an arbitrary
		 *     random number >= 0 from now on, just like
		 *     Random::getUint32().
		 *   - nWeights > 0 and Weights == NULL: eventually present
		 *     weights will be removed, and getWeightedUint32() will
		 *     return a uniformly distributed number in the range
		 *     [0,nWeights-1].
		 *   - nWeights > 0 and Weights != NULL: the number of weights
		 *     at Weights must be greater than or equal to nWeights.
		 *     From now on getWeightedUint32() will return a random
		 *     number in range [0,nWeights-1] with the passed weighted
		 *     probability.
		 *     \param nWeights fixes the range of the random numbers
		 *            returned by getWeightedUint32() to [0,nWeights-1]
		 *     \param Weights (optional) must contain nWeights odds.
		 *            The buffer, that will contain the weights used
		 *            by the class furtheron is created internally (i.e.
		 *            the weights are copied). Therefore the memory at
		 *            Wheights can be deleted after this call.
		 *     \return true, if the demanded setting could be fixed,
		 *             otherwise false.
		 */
		bool setWeights( const int        nWeights,
		                 const int *const  Weights = NULL );

		//! returns a random number (for details see function setWeights)

		/*! Implementation details: If valid interval boundaries are
		 *  present, the function getWeightedUint32() so far selects the
		 *  interval i (0 <= i <= m_NumIntervals), in which a random
		 *  number r (0 <= r <= m_Intervals[m_NumIntervals-1]) lies,
		 *  using a linear search. For large values of m_Intervals a
		 *  binary search will get faster, but for the usage in WoP the
		 *  linear search does not show any disadvantages.
		 */
		Uint32 getWeightedUint32();

		//! \name (de)serialization
		//@{
		virtual Uint32 getSerializeBufferSize() const;
		virtual void serialize( Uint8*& bufferPointer ) const;
		virtual void deserialize( Uint8*& bufferPointer );
		//@}

	protected:

		Uint32  m_NumIntervals, //!< the number of interval boundaries at m_Intervals
		       *m_Intervals;    //!< the interval boundaries
};

/**********************************************************/

#endif // _WEIGHTEDRANDOM_HPP_