| Home | Libraries | People | FAQ | More

## Class template linear_congruential_engine

boost::random::linear_congruential_engine

## Synopsis

    // In header: <boost/random/linear_congruential.hpp>

    template<typename IntType, IntType a, IntType c, IntType m>
    class linear_congruential_engine {
    public:
      // types
      typedef IntType result_type;

      // construct/copy/destruct
      linear_congruential_engine();
      explicit linear_congruential_engine(IntType);
      template<typename SeedSeq> explicit linear_congruential_engine(SeedSeq &);
      template<typename It> linear_congruential_engine(It &, It);

      // public member functions
      void seed();
      void seed(IntType);
      template<typename SeedSeq> void seed(SeedSeq &);
      template<typename It> void seed(It &, It);
      IntType operator()();
      template<typename Iter> void generate(Iter, Iter);
      void discard(boost::uintmax_t);

      // public static functions
      static result_type min();
      static result_type max();

      // friend functions
      template<typename CharT, typename Traits>
        friend std::basic_ostream< CharT, Traits > &
        operator<<(std::basic_ostream< CharT, Traits > &,
                   const linear_congruential_engine &);
      template<typename CharT, typename Traits>
        friend std::basic_istream< CharT, Traits > &
        operator>>(std::basic_istream< CharT, Traits > &,
                   linear_congruential_engine &);

      // public data members
      static const bool has_fixed_range;
      static const IntType multiplier;
      static const IntType increment;
      static const IntType modulus;
      static const IntType default_seed;
    };

## Description

Instantiations of class template linear_congruential_engine model a pseudo-random number generator . Linear congruential pseudo-random number generators are described in:

> "Mathematical methods in large-scale computing units", D. H. Lehmer, Proc. 2nd Symposium on Large-Scale Digital Calculating Machines, Harvard University Press, 1951, pp. 141-146

Let x(n) denote the sequence of numbers returned by some pseudo-random number generator. Then for the linear congruential generator, x(n+1) := (a * x(n) + c) mod m. Parameters for the generator are x(0), a, c, m. The template parameter IntType shall denote an integral type. It must be large enough to hold values a, c, and m. The template parameters a and c must be smaller than m.

Note: The quality of the generator crucially depends on the choice of the parameters. User code should use one of the sensibly parameterized generators such as minstd_rand instead.

### `linear_congruential_engine` public construct/copy/destruct

1.     linear_congruential_engine();

   Constructs a ``linear_congruential_engine``, using the default seed

2.     explicit linear_congruential_engine(IntType x0);

   Constructs a ``linear_congruential_engine``, seeding it with `x0`.

3.     template<typename SeedSeq> explicit linear_congruential_engine(SeedSeq & seq);

   Constructs a ``linear_congruential_engine``, seeding it with values produced by a call to `seq.generate()`.

4.     template<typename It> linear_congruential_engine(It & first, It last);

   Constructs a ``linear_congruential_engine`` and seeds it with values taken from the itrator range [first, last) and adjusts first to point to the element after the last one used. If there are not enough elements, throws `std::invalid_argument`.

   first and last must be input iterators.

### `linear_congruential_engine` public member functions

1.     void seed();

   Calls seed(default_seed)

2.     void seed(IntType x0);

   If c mod m is zero and x0 mod m is zero, changes the current value of the generator to 1. Otherwise, changes it to x0 mod m. If c is zero, distinct seeds in the range [1,m) will leave the generator in distinct states. If c is not zero, the range is [0,m).

3.     template<typename SeedSeq> void seed(SeedSeq & seq);

   Seeds a ``linear_congruential_engine`` using values from a SeedSeq.

4.     template<typename It> void seed(It & first, It last);

   seeds a ``linear_congruential_engine`` with values taken from the itrator range [first, last) and adjusts `first` to point to the element after the last one used. If there are not enough elements, throws `std::invalid_argument`.

   `first` and `last` must be input iterators.

5.     IntType operator()();

   Returns the next value of the ``linear_congruential_engine``.

6.     template<typename Iter> void generate(Iter first, Iter last);

   Fills a range with random values

7.     void discard(boost::uintmax_t z);

   Advances the state of the generator by `z`.

### `linear_congruential_engine` public static functions

1.     static result_type min();

   Returns the smallest value that the ``linear_congruential_engine`` can produce.

2.     static result_type max();

   Returns the largest value that the ``linear_congruential_engine`` can produce.

### `linear_congruential_engine` friend functions

1.     template<typename CharT, typename Traits>
         friend std::basic_ostream< CharT, Traits > &
         operator<<(std::basic_ostream< CharT, Traits > & os,
                    const linear_congruential_engine & lcg);

   Writes a ``linear_congruential_engine`` to a `std::ostream`.

2.     template<typename CharT, typename Traits>
         friend std::basic_istream< CharT, Traits > &
         operator>>(std::basic_istream< CharT, Traits > & is,
                    linear_congruential_engine & lcg);

   Reads a ``linear_congruential_engine`` from a `std::istream`.