libstdc++
uniform_int_dist.h
Go to the documentation of this file.
1 // Class template uniform_int_distribution -*- C++ -*-
2 
3 // Copyright (C) 2009-2016 Free Software Foundation, Inc.
4 //
5 // This file is part of the GNU ISO C++ Library. This library is free
6 // software; you can redistribute it and/or modify it under the
7 // terms of the GNU General Public License as published by the
8 // Free Software Foundation; either version 3, or (at your option)
9 // any later version.
10 
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 // GNU General Public License for more details.
15 
16 // Under Section 7 of GPL version 3, you are granted additional
17 // permissions described in the GCC Runtime Library Exception, version
18 // 3.1, as published by the Free Software Foundation.
19 
20 // You should have received a copy of the GNU General Public License and
21 // a copy of the GCC Runtime Library Exception along with this program;
22 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23 // <http://www.gnu.org/licenses/>.
24 
25 /**
26  * @file bits/uniform_int_dist.h
27  * This is an internal header file, included by other library headers.
28  * Do not attempt to use it directly. @headername{random}
29  */
30 
31 #ifndef _GLIBCXX_BITS_UNIFORM_INT_DIST_H
32 #define _GLIBCXX_BITS_UNIFORM_INT_DIST_H
33 
34 #include <type_traits>
35 #include <limits>
36 
37 namespace std _GLIBCXX_VISIBILITY(default)
38 {
39 
40  namespace __detail
41  {
42 _GLIBCXX_BEGIN_NAMESPACE_VERSION
43  /* Determine whether number is a power of 2. */
44  template<typename _Tp>
45  inline bool
46  _Power_of_2(_Tp __x)
47  {
48  return ((__x - 1) & __x) == 0;
49  };
50 _GLIBCXX_END_NAMESPACE_VERSION
51  }
52 
53 _GLIBCXX_BEGIN_NAMESPACE_VERSION
54 
55  /**
56  * @brief Uniform discrete distribution for random numbers.
57  *
58  * A discrete random distribution on the range @f$[min, max]@f$ with equal
59  * probability throughout the range.
60  *
61  * @ingroup random_distributions_uniform
62  */
63  template<typename _IntType = int>
65  {
67  "template argument not an integral type");
68 
69  public:
70  /** The type of the range of the distribution. */
71  typedef _IntType result_type;
72  /** Parameter type. */
73  struct param_type
74  {
76 
77  explicit
78  param_type(_IntType __a = 0,
79  _IntType __b = std::numeric_limits<_IntType>::max())
80  : _M_a(__a), _M_b(__b)
81  {
82  _GLIBCXX_DEBUG_ASSERT(_M_a <= _M_b);
83  }
84 
85  result_type
86  a() const
87  { return _M_a; }
88 
89  result_type
90  b() const
91  { return _M_b; }
92 
93  friend bool
94  operator==(const param_type& __p1, const param_type& __p2)
95  { return __p1._M_a == __p2._M_a && __p1._M_b == __p2._M_b; }
96 
97  private:
98  _IntType _M_a;
99  _IntType _M_b;
100  };
101 
102  public:
103  /**
104  * @brief Constructs a uniform distribution object.
105  */
106  explicit
107  uniform_int_distribution(_IntType __a = 0,
108  _IntType __b = std::numeric_limits<_IntType>::max())
109  : _M_param(__a, __b)
110  { }
111 
112  explicit
114  : _M_param(__p)
115  { }
116 
117  /**
118  * @brief Resets the distribution state.
119  *
120  * Does nothing for the uniform integer distribution.
121  */
122  void
123  reset() { }
124 
125  result_type
126  a() const
127  { return _M_param.a(); }
128 
129  result_type
130  b() const
131  { return _M_param.b(); }
132 
133  /**
134  * @brief Returns the parameter set of the distribution.
135  */
136  param_type
137  param() const
138  { return _M_param; }
139 
140  /**
141  * @brief Sets the parameter set of the distribution.
142  * @param __param The new parameter set of the distribution.
143  */
144  void
145  param(const param_type& __param)
146  { _M_param = __param; }
147 
148  /**
149  * @brief Returns the inclusive lower bound of the distribution range.
150  */
151  result_type
152  min() const
153  { return this->a(); }
154 
155  /**
156  * @brief Returns the inclusive upper bound of the distribution range.
157  */
158  result_type
159  max() const
160  { return this->b(); }
161 
162  /**
163  * @brief Generating functions.
164  */
165  template<typename _UniformRandomNumberGenerator>
166  result_type
167  operator()(_UniformRandomNumberGenerator& __urng)
168  { return this->operator()(__urng, _M_param); }
169 
170  template<typename _UniformRandomNumberGenerator>
171  result_type
172  operator()(_UniformRandomNumberGenerator& __urng,
173  const param_type& __p);
174 
175  template<typename _ForwardIterator,
176  typename _UniformRandomNumberGenerator>
177  void
178  __generate(_ForwardIterator __f, _ForwardIterator __t,
179  _UniformRandomNumberGenerator& __urng)
180  { this->__generate(__f, __t, __urng, _M_param); }
181 
182  template<typename _ForwardIterator,
183  typename _UniformRandomNumberGenerator>
184  void
185  __generate(_ForwardIterator __f, _ForwardIterator __t,
186  _UniformRandomNumberGenerator& __urng,
187  const param_type& __p)
188  { this->__generate_impl(__f, __t, __urng, __p); }
189 
190  template<typename _UniformRandomNumberGenerator>
191  void
192  __generate(result_type* __f, result_type* __t,
193  _UniformRandomNumberGenerator& __urng,
194  const param_type& __p)
195  { this->__generate_impl(__f, __t, __urng, __p); }
196 
197  /**
198  * @brief Return true if two uniform integer distributions have
199  * the same parameters.
200  */
201  friend bool
203  const uniform_int_distribution& __d2)
204  { return __d1._M_param == __d2._M_param; }
205 
206  private:
207  template<typename _ForwardIterator,
208  typename _UniformRandomNumberGenerator>
209  void
210  __generate_impl(_ForwardIterator __f, _ForwardIterator __t,
211  _UniformRandomNumberGenerator& __urng,
212  const param_type& __p);
213 
214  param_type _M_param;
215  };
216 
217  template<typename _IntType>
218  template<typename _UniformRandomNumberGenerator>
221  operator()(_UniformRandomNumberGenerator& __urng,
222  const param_type& __param)
223  {
224  typedef typename _UniformRandomNumberGenerator::result_type
225  _Gresult_type;
226  typedef typename std::make_unsigned<result_type>::type __utype;
227  typedef typename std::common_type<_Gresult_type, __utype>::type
228  __uctype;
229 
230  const __uctype __urngmin = __urng.min();
231  const __uctype __urngmax = __urng.max();
232  const __uctype __urngrange = __urngmax - __urngmin;
233  const __uctype __urange
234  = __uctype(__param.b()) - __uctype(__param.a());
235 
236  __uctype __ret;
237 
238  if (__urngrange > __urange)
239  {
240  // downscaling
241  const __uctype __uerange = __urange + 1; // __urange can be zero
242  const __uctype __scaling = __urngrange / __uerange;
243  const __uctype __past = __uerange * __scaling;
244  do
245  __ret = __uctype(__urng()) - __urngmin;
246  while (__ret >= __past);
247  __ret /= __scaling;
248  }
249  else if (__urngrange < __urange)
250  {
251  // upscaling
252  /*
253  Note that every value in [0, urange]
254  can be written uniquely as
255 
256  (urngrange + 1) * high + low
257 
258  where
259 
260  high in [0, urange / (urngrange + 1)]
261 
262  and
263 
264  low in [0, urngrange].
265  */
266  __uctype __tmp; // wraparound control
267  do
268  {
269  const __uctype __uerngrange = __urngrange + 1;
270  __tmp = (__uerngrange * operator()
271  (__urng, param_type(0, __urange / __uerngrange)));
272  __ret = __tmp + (__uctype(__urng()) - __urngmin);
273  }
274  while (__ret > __urange || __ret < __tmp);
275  }
276  else
277  __ret = __uctype(__urng()) - __urngmin;
278 
279  return __ret + __param.a();
280  }
281 
282 
283  template<typename _IntType>
284  template<typename _ForwardIterator,
285  typename _UniformRandomNumberGenerator>
286  void
288  __generate_impl(_ForwardIterator __f, _ForwardIterator __t,
289  _UniformRandomNumberGenerator& __urng,
290  const param_type& __param)
291  {
292  __glibcxx_function_requires(_ForwardIteratorConcept<_ForwardIterator>)
293  typedef typename _UniformRandomNumberGenerator::result_type
294  _Gresult_type;
295  typedef typename std::make_unsigned<result_type>::type __utype;
296  typedef typename std::common_type<_Gresult_type, __utype>::type
297  __uctype;
298 
299  const __uctype __urngmin = __urng.min();
300  const __uctype __urngmax = __urng.max();
301  const __uctype __urngrange = __urngmax - __urngmin;
302  const __uctype __urange
303  = __uctype(__param.b()) - __uctype(__param.a());
304 
305  __uctype __ret;
306 
307  if (__urngrange > __urange)
308  {
309  if (__detail::_Power_of_2(__urngrange + 1)
310  && __detail::_Power_of_2(__urange + 1))
311  {
312  while (__f != __t)
313  {
314  __ret = __uctype(__urng()) - __urngmin;
315  *__f++ = (__ret & __urange) + __param.a();
316  }
317  }
318  else
319  {
320  // downscaling
321  const __uctype __uerange = __urange + 1; // __urange can be zero
322  const __uctype __scaling = __urngrange / __uerange;
323  const __uctype __past = __uerange * __scaling;
324  while (__f != __t)
325  {
326  do
327  __ret = __uctype(__urng()) - __urngmin;
328  while (__ret >= __past);
329  *__f++ = __ret / __scaling + __param.a();
330  }
331  }
332  }
333  else if (__urngrange < __urange)
334  {
335  // upscaling
336  /*
337  Note that every value in [0, urange]
338  can be written uniquely as
339 
340  (urngrange + 1) * high + low
341 
342  where
343 
344  high in [0, urange / (urngrange + 1)]
345 
346  and
347 
348  low in [0, urngrange].
349  */
350  __uctype __tmp; // wraparound control
351  while (__f != __t)
352  {
353  do
354  {
355  const __uctype __uerngrange = __urngrange + 1;
356  __tmp = (__uerngrange * operator()
357  (__urng, param_type(0, __urange / __uerngrange)));
358  __ret = __tmp + (__uctype(__urng()) - __urngmin);
359  }
360  while (__ret > __urange || __ret < __tmp);
361  *__f++ = __ret;
362  }
363  }
364  else
365  while (__f != __t)
366  *__f++ = __uctype(__urng()) - __urngmin + __param.a();
367  }
368 
369 _GLIBCXX_END_NAMESPACE_VERSION
370 } // namespace std
371 
372 #endif
uniform_int_distribution(_IntType __a=0, _IntType __b=std::numeric_limits< _IntType >::max())
Constructs a uniform distribution object.
result_type operator()(_UniformRandomNumberGenerator &__urng)
Generating functions.
friend bool operator==(const uniform_int_distribution &__d1, const uniform_int_distribution &__d2)
Return true if two uniform integer distributions have the same parameters.
void param(const param_type &__param)
Sets the parameter set of the distribution.
Uniform discrete distribution for random numbers.
ISO C++ entities toplevel namespace is std.
result_type max() const
Returns the inclusive upper bound of the distribution range.
is_integral
Definition: type_traits:289
param_type param() const
Returns the parameter set of the distribution.
Properties of fundamental types.
Definition: limits:315
void reset()
Resets the distribution state.
result_type min() const
Returns the inclusive lower bound of the distribution range.