KCoreAddons

krandomsequence.h
1 /*
2  This file is part of the KDE libraries
3 
4  SPDX-FileCopyrightText: 1999 Sean Harmer <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-only
7 */
8 
9 #ifndef K_RANDOM_SEQUENCE_H
10 #define K_RANDOM_SEQUENCE_H
11 
12 #include <kcoreaddons_export.h>
13 
14 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 75)
15 
16 #include <QList>
17 #include <QSharedDataPointer>
18 
19 /**
20  * \class KRandomSequence krandomsequence.h <KRandomSequence>
21  *
22  * A class to create a pseudo-random sequence
23  *
24  * Given a seed number, this class will produce a sequence of
25  * pseudo-random numbers. This would typically be used in
26  * applications like games.
27  *
28  * In general, you should instantiate a KRandomSequence object and
29  * pass along your seed number in the constructor. From then on,
30  * simply call getDouble or getLong to obtain the next
31  * number in the sequence.
32  *
33  * @author Sean Harmer <[email protected]>
34  *
35  * @deprecated Since 5.75, use QRandomGenerator or KRandom::shuffle
36  */
37 class KCOREADDONS_EXPORT KRandomSequence
38 {
39 public:
40  /**
41  * Creates a pseudo-random sequence based on the seed lngSeed.
42  *
43  * A Pseudo-random sequence is different for each seed but can be
44  * reproduced by starting the sequence with the same seed.
45  *
46  * If you need a single value which needs to be unpredictable,
47  * you need to use QRandomGenerator::global()->generate() instead.
48  *
49  * @param intSeed Seed to initialize the sequence with.
50  * If lngSeed is 0, the sequence is initialized with a value from
51  * [0, RAND_MAX)
52  *
53  * Do not use methods working with long type because on 64-bit
54  * their size is different.
55  */
56  KCOREADDONS_DEPRECATED_VERSION(5, 75, "Use QRandomGenerator")
57  explicit KRandomSequence(int intSeed = 0);
58  KCOREADDONS_DEPRECATED_VERSION(5, 75, "Use QRandomGenerator")
59  explicit KRandomSequence(long lngSeed);
60 
61  /**
62  * Standard destructor
63  */
64  virtual ~KRandomSequence();
65 
66  /**
67  * Copy constructor
68  */
70 
71  /**
72  * Assignment
73  */
74  KRandomSequence &operator=(const KRandomSequence &a);
75 
76  /**
77  * Restart the sequence based on lngSeed.
78  * @param intSeed Seed to initialize the sequence with.
79  * If lngSeed is 0, the sequence is initialized with a value from
80  * [0, RAND_MAX).
81  */
82  void setSeed(int intSeed = 0);
83  void setSeed(long lngSeed = 0);
84 
85  /**
86  * Get the next number from the pseudo-random sequence.
87  *
88  * @return a pseudo-random double value between [0,1)
89  */
90  double getDouble();
91 
92  /**
93  * Get the next number from the pseudo-random sequence.
94  *
95  * @return a pseudo-random integer value between [0, max)
96  * with 0 <= max < 1.000.000
97  */
98  unsigned int getInt(unsigned int max);
99  unsigned long getLong(unsigned long max);
100 
101  /**
102  * Get a boolean from the pseudo-random sequence.
103  *
104  * @return a boolean which is either true or false
105  */
106  bool getBool();
107 
108  /**
109  * Put a list in random order.
110  *
111  * Since kdelibs 4.11, this function uses a more efficient
112  * algorithm (Fisher-Yates). Therefore, the order of the items in
113  * the randomized list is different from the one in earlier
114  * versions if the same seed value is used for the random
115  * sequence.
116  *
117  * @param list the list whose order will be modified
118  * @note modifies the list in place
119  *
120  * @deprecated Since 5.75, use KRandom::shuffle
121  */
122  template<typename T>
123  KCOREADDONS_DEPRECATED_VERSION(5, 75, "Use KRandom::shuffle")
124  void randomize(QList<T> &list)
125  {
126  // Fisher-Yates algorithm
127  for (int index = list.count() - 1; index > 0; --index) {
128  const int swapIndex = getInt(index + 1);
129  qSwap(list[index], list[swapIndex]);
130  }
131  }
132 
133  /**
134  * Modulate the random sequence.
135  *
136  * If S(i) is the sequence of numbers that will follow
137  * given the current state after calling modulate(i),
138  * then S(i) != S(j) for i != j and
139  * S(i) == S(j) for i == j.
140  *
141  * This can be useful in game situation where "undo" restores
142  * the state of the random sequence. If the game modulates the
143  * random sequence with the move chosen by the player, the
144  * random sequence will be identical whenever the player "redo"-s
145  * his or hers original move, but different when the player
146  * chooses another move.
147  *
148  * With this scenario "undo" can no longer be used to repeat a
149  * certain move over and over again until the computer reacts
150  * with a favorable response or to predict the response for a
151  * certain move based on the response to another move.
152  * @param i the sequence identified
153  */
154  void modulate(int i);
155 
156 private:
158 };
159 
160 #endif
161 
162 #endif
A class to create a pseudo-random sequence.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Apr 18 2021 23:02:02 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.