kdecore/util/krandomsequence.h

   1 /* This file is part of the KDE libraries
   2    Copyright (c) 1999 Sean Harmer <sh@astro.keele.ac.uk>
   3
   4    This library is free software; you can redistribute it and/or
   5    modify it under the terms of the GNU Library General Public
   6    License version 2 as published by the Free Software Foundation.
   7
   8    This library is distributed in the hope that it will be useful,
   9    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11    Library General Public License for more details.
  12
  13    You should have received a copy of the GNU Library General Public License
  14    along with this library; see the file COPYING.LIB.  If not, write to
  15    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16    Boston, MA 02110-1301, USA.
  17 */
  18 #ifndef K_RANDOM_SEQUENCE_H
  19 #define K_RANDOM_SEQUENCE_H
  20
  21 #include <kdecore_export.h>
  22 #include <QtCore/QList>
  23
  24 /**
  25  * \class KRandomSequence krandomsequence.h <KRandomSequence>
  26  *
  27  * A class to create a pseudo-random sequence
  28  *
  29  * Given a seed number, this class will produce a sequence of
  30  * pseudo-random numbers.  This would typically be used in
  31  * applications like games.
  32  *
  33  * In general, you should instantiate a KRandomSequence object and
  34  * pass along your seed number in the constructor.  From then on,
  35  * simply call getDouble or getLong to obtain the next
  36  * number in the sequence.
  37  *
  38  * @author Sean Harmer <sh@astro.keele.ac.uk>
  39  */
  40 class KDECORE_EXPORT KRandomSequence
  41 {
  42 public:
  43   /**
  44    * Creates a pseudo-random sequence based on the seed lngSeed.
  45    *
  46    * A Pseudo-random sequence is different for each seed but can be
  47    * reproduced by starting the sequence with the same seed.
  48    *
  49    * If you need a single value which needs to be unpredictable,
  50    * you need to use KRandom::random() instead.
  51    *
  52    * @param lngSeed Seed to initialize the sequence with.
  53    * If lngSeed is 0, the sequence is initialized with a value from
  54    * KRandom::random().
  55    */
  56   explicit KRandomSequence( long lngSeed = 0 );
  57
  58   /**
  59    * Standard destructor
  60    */
  61   virtual ~KRandomSequence();
  62
  63   /**
  64    * Copy constructor
  65    */
  66   KRandomSequence(const KRandomSequence &a);
  67
  68   /**
  69    * Assignment
  70    */
  71   KRandomSequence &operator=(const KRandomSequence &a);
  72
  73   /**
  74    * Restart the sequence based on lngSeed.
  75    * @param lngSeed Seed to initialize the sequence with.
  76    * If lngSeed is 0, the sequence is initialized with a value from
  77    * KRandom::random().
  78    */
  79   void setSeed( long lngSeed = 0 );
  80
  81   /**
  82    * Get the next number from the pseudo-random sequence.
  83    *
  84    * @return a pseudo-random double value between [0,1)
  85    */
  86   double getDouble();
  87
  88   /**
  89    * Get the next number from the pseudo-random sequence.
  90    *
  91    * @return a pseudo-random integer value between [0, max)
  92    * with 0 <= max < 1.000.000
  93    */
  94   unsigned long getLong(unsigned long max);
  95
  96   /**
  97    * Get a boolean from the pseudo-random sequence.
  98    *
  99    * @return a boolean which is either true or false
 100    */
 101   bool getBool();
 102
 103   /**
 104    * Put a list in random order.
 105    *
 106    * @param list the list whose order will be modified
 107    * @note modifies the list in place
 108    */
 109   template<typename T> void randomize(QList<T>& list) {
 110         QList<T> l;
 111
 112         l.append(list.takeFirst());
 113         while (list.count())
 114                 l.insert(int(getLong(l.count()+1)), list.takeFirst());
 115         list = l;
 116   }
 117
 118
 119   /**
 120    * Modulate the random sequence.
 121    *
 122    * If S(i) is the sequence of numbers that will follow
 123    * given the current state after calling modulate(i),
 124    * then S(i) != S(j) for i != j and
 125    *      S(i) == S(j) for i == j.
 126    *
 127    * This can be useful in game situation where "undo" restores
 128    * the state of the random sequence. If the game modulates the
 129    * random sequence with the move chosen by the player, the
 130    * random sequence will be identical whenever the player "redo"-s
 131    * his or hers original move, but different when the player
 132    * chooses another move.
 133    *
 134    * With this scenario "undo" can no longer be used to repeat a
 135    * certain move over and over again until the computer reacts
 136    * with a favorable response or to predict the response for a
 137    * certain move based on the response to another move.
 138    * @param i the sequence identified
 139    */
 140   void modulate(int i);
 141
 142 private:
 143   class Private;
 144   Private *const d;
 145 };
 146
 147 #endif