# Random Number Generator Library --- Miscellaneous Decorators

- Class template `random_number_generator`
- Class template `generator_iterator`

## Introduction

These decorator class templates allow adaptation of the random number generators and distribution functions to concepts found in the C++ Standard Library, in particular the RandomNumberGenerator and the InputIterator concepts. The latter adaptation is useful, because the the basic random number generators do not implement the InputIterator requirements per se, in contrast to the distribution functions.

## Synopsis of miscellaneous decorators in header `<boost/random.hpp>`

    namespace boost {
      template<class UniformRandomNumberGenerator, class IntType = long>
      class random_number_generator;
      template<class Generator>
      class generator_iterator;
    } // namespace boost

## Class template `random_number_generator`

### Synopsis

    template<class UniformRandomNumberGenerator, class IntType = long>
    class random_number_generator
    {
    public:
      typedef UniformRandomNumberGenerator base_type;
      typedef IntType argument_type;
      typedef IntType result_type;
      random_number_generator(base_type & rng);
      result_type operator()(argument_type n);
    };

### Description

Instantiations of class template `random_number_generator` model a RandomNumberGenerator (std:25.2.11 [lib.alg.random.shuffle]). On each invocation, it returns a uniformly distributed integer in the range [0..`n`).

The template parameter `IntType` shall denote some integer-like value type.

Note: I consider it unfortunate that the C++ Standard uses the name RandomNumberGenerator for something rather specific.

### Members

    random_number_generator(base_type & rng)

Effects: Constructs a `random_number_generator` functor with the given uniform random number generator as the underlying source of random numbers.

    result_type operator()(argument_type n)

Returns: The value of `uniform_int<base_type>(rng, 0, n-1)()`.

## Class template `generator_iterator`

### Synopsis

    template<class Generator>
    class generator_iterator
      : equality_comparable<generator_iterator<Generator> >,
      incrementable<generator_iterator<Generator> >,
      dereferenceable<generator_iterator<Generator>,
          typename Generator::result_type>
    {
    public:
      typedef typename Generator::result_type value_type;
      typedef std::ptrdiff_t difference_type;
      typedef const typename Generator::result_type * pointer;
      typedef const typename Generator::result_type & reference;
      typedef std::input_iterator_tag iterator_category;

      explicit generator_iterator(Generator & g);
      generator_iterator& operator++();
      reference operator*() const;
      friend bool operator==(const generator_iterator<Generator>& x,
    			 const generator_iterator<Generator>& y);
    };

### Description

Instantiations of class template `generator_iterator` satisfy the input iterator requirements (std:24.1.1 [lib.input.iterators]). It allows iterator-like access to a generator, e.g. a NumberGenerator. Note that all distribution functions now satisfy the input iterator requirements as-is. However, the base generators do not.

### Members

    explicit generator_iterator(Generator & g)

Effects: Constructs a `generator_iterator` with `g` as the underlying generator. Invokes the underlying generator functor.

    generator_iterator& operator++()

Effects: Invokes the underlying generator functor.

Returns: `*this`

    reference operator*() const

Returns: The value of the last invocation of the underlying generator functor.

### Overloaded global operators

    bool operator==(const generator_iterator<Generator>& x,
    	         const generator_iterator<Generator>& y)

Returns: `true` if and only if the `x` and `y` have been initialized with a reference to the same generator functor and `*x == *y`.

### Example

The following program shows how `generator_iterator` transforms a generator into an input iterator.

    #include <iostream>
    #include <boost/random.hpp>

    class my_generator
    {
    public:
      typedef int result_type;
      my_generator() : state(0) { }
      int operator()() { return ++state; }
    private:
      int state;
    };

    int main()
    {
      my_generator gen;
      boost::generator_iterator<my_generator> it(gen);
      for(int i = 0; i < 10; ++i, ++it)
        std::cout << *it << std::endl;
    }

Jens Maurer, 2001-01-30