:orphan:

.. index:: pair: group; Random numbers
.. _doxid-group__te__tools__te__rand:

Random numbers
==============

.. toctree::
	:hidden:

Overview
~~~~~~~~

Definition of API for generating random numbers. :ref:`More...<details-group__te__tools__te__rand>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	
	// global functions

	uintmax_t :ref:`te_rand_unsigned<doxid-group__te__tools__te__rand_1ga7b46b2523dad8f25f00f09917e233581>`(uintmax_t min, uintmax_t max);
	intmax_t :ref:`te_rand_signed<doxid-group__te__tools__te__rand_1ga97df12d26bf145d09fbd51d0dde61e67>`(intmax_t min, intmax_t max);
	static uintmax_t :ref:`te_rand_unsigned_div<doxid-group__te__tools__te__rand_1ga70b65bf709a7d11659567c493b9076c3>`(uintmax_t min, uintmax_t max, unsigned int div, unsigned int rem);
	static intmax_t :ref:`te_rand_signed_div<doxid-group__te__tools__te__rand_1ga8e5af4b13682c21979f6cc3558bfc8a4>`(intmax_t min, intmax_t max, unsigned int div, unsigned int mod);
	int :ref:`te_rand_range_exclude<doxid-group__te__tools__te__rand_1ga5c17718585a1b4f7663c7a22bf677d1b>`(int min, int max, int exclude);

.. _details-group__te__tools__te__rand:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

Definition of API for generating random numbers.

Global Functions
----------------

.. index:: pair: function; te_rand_unsigned
.. _doxid-group__te__tools__te__rand_1ga7b46b2523dad8f25f00f09917e233581:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	uintmax_t te_rand_unsigned(uintmax_t min, uintmax_t max)

Generate a random unsigned number in a given range.

The function uses xoshiro256++ algorithm that is able to generate the full range of 64-bit numbers, see `http://vigna.di.unimi.it/ftp/papers/ScrambledLinear.pdf <http://vigna.di.unimi.it/ftp/papers/ScrambledLinear.pdf>`__.

The PRNG state is seeded based on the standard ``rand()``, so that applications that use ``srand()`` would get reproducible results with this function as well.

Todo The current implementation is not well suited for multithreaded applications, just like the standard ``rand()`` used by rand_range(), however, the algorithm does support creation of robust parallel PRNGs, so it may be implemented, should it ever be needed.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- min

		- Minimum value (inclusive).

	*
		- max

		- Maximum value (inclusive).



.. rubric:: Returns:

The next pseudo-random number between ``min`` and ``max``.

.. index:: pair: function; te_rand_signed
.. _doxid-group__te__tools__te__rand_1ga97df12d26bf145d09fbd51d0dde61e67:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	intmax_t te_rand_signed(intmax_t min, intmax_t max)

Generate a random signed number in a given range.

See :ref:`te_rand_unsigned() <doxid-group__te__tools__te__rand_1ga7b46b2523dad8f25f00f09917e233581>` for details.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- min

		- Minimum value (inclusive).

	*
		- max

		- Maximum value (inclusive).



.. rubric:: Returns:

The next pseudo-random number between ``min`` and ``max``.

.. index:: pair: function; te_rand_unsigned_div
.. _doxid-group__te__tools__te__rand_1ga70b65bf709a7d11659567c493b9076c3:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	static uintmax_t te_rand_unsigned_div(uintmax_t min, uintmax_t max, unsigned int div, unsigned int rem)

Generate a random unsigned number in a given range such that its value modulo ``div`` is ``rem``.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- min

		- Minimum value (inclusive).

	*
		- max

		- Maximum value (inclusive).

	*
		- div

		- Divisor.

	*
		- rem

		- Expected remainder.



.. rubric:: Returns:

A random value such that it's equal to ``rem`` modulo ``div``.

.. index:: pair: function; te_rand_signed_div
.. _doxid-group__te__tools__te__rand_1ga8e5af4b13682c21979f6cc3558bfc8a4:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	static intmax_t te_rand_signed_div(intmax_t min, intmax_t max, unsigned int div, unsigned int mod)

Generate a random signed number in a given range such that its value modulo ``div`` is ``rem``.

If ``rem`` is zero, the value will always be in the range between ``min`` and ``max``. Otherwise, it may fall out of this range if ``min`` or ``max`` themselves are not equal to ``rem`` modulo ``div``.

The function takes into account that in C the remainder is negative if the quotient is negative, so if the result of the function is negative, it will actually be so that: ``te_rand_signed_div(min, max, div, mod) % div == -mod``.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- min

		- Minimum value (inclusive).

	*
		- max

		- Maximum value (inclusive).

	*
		- div

		- Divisor.

	*
		- rem

		- Expected remainder.



.. rubric:: Returns:

A random value such that it's equal to ``rem`` modulo ``div``.

.. index:: pair: function; te_rand_range_exclude
.. _doxid-group__te__tools__te__rand_1ga5c17718585a1b4f7663c7a22bf677d1b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	int te_rand_range_exclude(int min, int max, int exclude)

Choose a random value from a range excluding some value inside that range.

.. note::

	This function will use :ref:`TE_FATAL_ERROR() <doxid-logger__api_8h_1af76bf1098ff84d85ec5428e05b89ed2c>` if it is impossible to choose any value.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- min

		- Range lower limit.

	*
		- max

		- Range upper limit.

	*
		- exclude

		- Value to exclude.



.. rubric:: Returns:

Random number from the range [min, max].