Manual
======

RandomIterator is a header-only library with no dependencies. So, it is only
necessary to drop the ``random_iterator`` directory, which contains the library
source code somewhere reachable to the compiler and include the `random_iterator/Stream.cpp`_
in the project code. All classes, functions and typedefs of the API are declared in the 
`namespace random_iterator`_. 

The primary object of RandomIterator's API is `random_iterator::Stream<Distribution, Engine>`_. These
objects represent streams of pseudorandom numbers distributed according with the template parameter
``Distribution``, and generated by the algorithm speficied in ``Engine``. 

.. _random_iterator::Stream<Distribution, Engine>: https://randomiterator.readthedocs.io/en/latest/doxygen/html/classrandom__iterator_1_1_stream.html
.. _random_iterator/Stream.cpp: https://randomiterator.readthedocs.io/en/latest/doxygen/html/_stream_8hpp.html
.. _namespace random_iterator: https://randomiterator.readthedocs.io/en/latest/doxygen/html/namespacerandom__iterator.html

Suported Distribution 
---------------------

All statistical distrucions implemented in the C++ standard library are supported, as well as 
distrucions implemented elsewhere, following the same interface guide lines. 
Addicionally, the distrucions are required to be thread-safe.

Example of suported distrucions:

* ``std::uniform_int_distribution``
* ``std::uniform_real_distribution``
* ``std::bernoulli_distribution``
* ``std::binomial_distribution``
* ``std::negative_binomial_distribution``
* ``std::geometric_distribution``
* ``std::poisson_distribution``
* ``std::exponential_distribution``
* ``std::gamma_distribution``
* ``std::weibull_distribution``
* ``std::extreme_value_distribution``
* ``std::normal_distribution``
* ``std::lognormal_distribution``
* ``std::chi_squared_distribution``
* ``std::cauchy_distribution``
* ``std::fisher_f_distribution``
* ``std::student_t_distribution``
* ``std::discrete_distribution``
* ``std::piecewise_constant_distribution``
* ``std::piecewise_linear_distribution``

Detailed information on how on these distributions is available on the page `Pseudo-random number generation`_

.. _Pseudo-random number generation: https://en.cppreference.com/w/cpp/numeric/random

Supported counter-based pseudorandom number generators (CBPRNGs) 
---------------------------------------------------------------

`random_iterator::Stream<Distribution, Engine>`_ class template can be instatiaded with the CBPRNGs :

* `random_iterator::ars`_
* `random_iterator::philox`_
* `random_iterator::threefry`_
* `random_iterator::squares3_128`_
* `random_iterator::squares4_128`_
* `random_iterator::squares3_64`_
* `random_iterator::squares4_64`_

``ars``, ``philox`` and ``threefry`` are implemented in `Random123: <https://ieeexplore.ieee.org/abstract/document/6114424>`_. 
``squares3_128``, ``squares4_128``, ``random_iterator::squares3_64`` and ``random_iterator::squares4_64`` are natively implemented.

.. _random_iterator::ars:
.. _random_iterator::philox: https://randomiterator.readthedocs.io/en/latest/doxygen/html/namespacerandom__iterator.html#a63c0422feddfbd54007ee050c7eac7cb
.. _random_iterator::threefry: https://randomiterator.readthedocs.io/en/latest/doxygen/html/namespacerandom__iterator.html#aba0429dca19021398e1cc6ddef59f50e
.. _random_iterator::squares3_128: https://randomiterator.readthedocs.io/en/latest/doxygen/html/namespacerandom__iterator.html#a2a07e2f3824d9d6abcd731a07a9aabc1
.. _random_iterator::squares4_128: https://randomiterator.readthedocs.io/en/latest/doxygen/html/namespacerandom__iterator.html#a5e03723f398c510ea7a826c26380fa46
.. _random_iterator::squares3_64: https://randomiterator.readthedocs.io/en/latest/doxygen/html/namespacerandom__iterator.html#a4a6ab1cbc602c55961a80ec71d689192
.. _random_iterator::squares4_64: https://randomiterator.readthedocs.io/en/latest/doxygen/html/namespacerandom__iterator.html#a6ad07dc60c4a28f7a2caa0e9852b7900


Exemplos
--------


Sequential access
~~~~~~~~~~~~~~~~~


.. code-block:: cpp
   :linenos:
   
   #include <random_iterator/Stream.hpp>
   #include <random>
   
   ...

   random_iterator::squares4_128        rng(0x548c9decbce65295);
   std::uniform_int_distribution<double> distribution(0.0, 1.0);
   
   auto stream = random_iterator::make_stream( distribution, rng, 0 );

   for(size_t i=0; i<10; ++i)
      std::cout << stream() << std::endl;


Access using iterators
~~~~~~~~~~~~~~~~~~~~~~


.. code-block:: cpp
   :linenos:
   
   #include <random_iterator/Stream.hpp>
   #include <random>
   
   ...

   random_iterator::squares4_128        rng(0x548c9decbce65295);
   std::uniform_int_distribution<double> distribution(0.0, 1.0);
   
   auto its = random_iterator::make_stream( distribution, rng, 0 ).begin();
   
   for(size_t i=0; i<10; ++i)
      std::cout << *(its++) << std::endl;



Access using range semantics 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~


.. code-block:: cpp
   :linenos:
   
   #include <random_iterator/Stream.hpp>
   #include <random>
   
   ...

   random_iterator::squares4_128        rng(0x548c9decbce65295);
   std::uniform_int_distribution<double> distribution(0.0, 1.0);
   
   auto stream = random_iterator::make_stream( distribution, rng, 0 );
   size_t i=0;
   for(auto x: stream )
   {
      std::cout << x << std::endl;
      if( ++i > 10) break;
   }