ACE/tests/randomize.h

   1 // -*- C++ -*-
   2
   3 // ============================================================================
   4 /**
   5  * @file randomize.h
   6  *
   7  * Randomize the contents of an array.
   8  *
   9  * @author Ossama Othman
  10  *
  11  * @note Based on code originally found in test_config.h and Test_Output.cpp
  12  */
  13 // ============================================================================
  14
  15 #ifndef ACE_TESTS_RANDOMIZE_H
  16 #define ACE_TESTS_RANDOMIZE_H
  17
  18 #include "ace/OS_NS_stdlib.h"
  19
  20 #include <algorithm>
  21 #include <functional>
  22
  23 namespace
  24 {
  25   /**
  26    * @class randomize_index
  27    *
  28    * @brief Functor that randomly swaps the order of two array
  29    *        elements.
  30    *
  31    * @internal Do not directly use this class.  Use the @c randomize()
  32    *           function template found below instead.
  33    *
  34    * This functor generates random array index using high-order bits (e.g.,
  35    * MAX_VAL * rand() / (RAND_MAX + 1.0)) rather than low-order ones
  36    * (e.g. rand() % MAX_VAL) to improve randomness.  The array element
  37    * reference by that index is then swapped with the array element
  38    * provided to the functor.
  39    *
  40    * @note The improved randomness may be overkill for this functor's
  41    *       intended use cases, but it is a good thing to practice/have
  42    *       nonetheless.
  43    *
  44    * @see Numerical Recipes in C: The Art of Scientific Computing
  45    *      (William H. Press, Brian P. Flannery, Saul A. Teukolsky,
  46    *      William T. Vetterling; New York: Cambridge University Press,
  47    *      1992 (2nd ed., p. 277).
  48    */
  49   template<typename T>
  50   class randomize_element
  51     : public std::unary_function<T &, void>
  52   {
  53   public:
  54
  55     randomize_element (T * array, size_t size, unsigned int seed)
  56       : array_ (array)
  57       , coefficient_ (static_cast<double> (size) / (RAND_MAX + 1.0f))
  58       , seed_ (seed)
  59     {
  60     }
  61
  62     void
  63     operator() (T & value)    // We need this to be a reference!
  64     {
  65       size_t const index =
  66         static_cast<size_t> (
  67           this->coefficient_ * ACE_OS::rand_r (&this->seed_));
  68
  69       // Swap rather than assign so that we don't lose the original
  70       // value.
  71       std::swap (value, this->array_[index]);
  72     }
  73
  74   private:
  75
  76     // The array.
  77     T * const array_;
  78
  79     // Factor out the constant coefficient.
  80     double const coefficient_;
  81
  82     // Random number generator seed value.
  83     unsigned int seed_;
  84
  85   };
  86
  87   /**
  88    * @fn randomize
  89    *
  90    * @brief Randomize the order of elements in an array.
  91    *
  92    * @param array The array whose elements will be reordered
  93    *              randomly.
  94    * @param size  The number of elements in the array.
  95    * @param seed  The random number generator seed value.  A default
  96    *              value is provided so that the generated random
  97                   number order may be "repeatable" if so desired.
  98    *
  99    * This function template randomizes the order of elements in an
 100    * array of any type.  It is also reentrant (unless the array itself
 101    * is accessed by multiple threads).
 102    * @par
 103    * Sample usage:
 104    * @par
 105    * \verbatim
 106      static size_t const NUM_TIMES = 100;
 107      ACE_Time_Value times[NUM_TIMES] = { ... };
 108      randomize (times,
 109                 NUM_TIMES,
 110                 static_cast<unsigned int> (ACE_OS::time (0L)));
 111     \endverbatim
 112    */
 113   template<typename T>
 114   void
 115   randomize (T * array, size_t size, unsigned int seed = 0)
 116   {
 117     // Randomize all elements of the array.
 118     std::for_each (array,
 119                    array + size,
 120                    randomize_element<T> (array, size, seed));
 121   }
 122 }
 123
 124 #endif  /* !ACE_TESTS_RANDOMIZE_H */