.. index:: single: random_protocol
.. _random_protocol/0:

.. rst-class:: right

**protocol**

``random_protocol``
===================

Random number generator protocol. The predicates are declared as synchronized when the library is compiled using a backend supporting threads.

| **Availability:** 
|    ``logtalk_load(random(loader))``

| **Author:** Paulo Moura
| **Version:** 3:3:0
| **Date:** 2023-11-24

| **Compilation flags:**
|    ``static``


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: random/1
.. _random_protocol/0::random/1:

``random/1``
^^^^^^^^^^^^

Returns a new random float value in the interval ``[0.0, 1.0[``.

| **Compilation flags:**
|    ``static, synchronized``

| **Template:**
|    ``random(Random)``
| **Mode and number of proofs:**
|    ``random(-float)`` - ``one``


------------

.. index:: between/3
.. _random_protocol/0::between/3:

``between/3``
^^^^^^^^^^^^^

Returns a new random integer in the interval ``[Lower, Upper]``. Fails if ``Lower`` or ``Upper`` are not integers or if ``Lower > Upper``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``between(Lower,Upper,Random)``
| **Mode and number of proofs:**
|    ``between(+integer,+integer,-integer)`` - ``zero_or_one``


------------

.. index:: member/2
.. _random_protocol/0::member/2:

``member/2``
^^^^^^^^^^^^

Returns a random member of a list. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``member(Random,List)``
| **Mode and number of proofs:**
|    ``member(-term,+list(term))`` - ``zero_or_one``


------------

.. index:: select/3
.. _random_protocol/0::select/3:

``select/3``
^^^^^^^^^^^^

Returns a random member of a list and the rest of the list. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``select(Random,List,Rest)``
| **Mode and number of proofs:**
|    ``select(-term,+list(term),-list(term))`` - ``zero_or_one``


------------

.. index:: select/4
.. _random_protocol/0::select/4:

``select/4``
^^^^^^^^^^^^

Returns a random member of a list, replacing it with a new element and returning the resulting list.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``select(Random,OldList,New,NewList)``
| **Mode and number of proofs:**
|    ``select(-term,+list(term),@term,-list(term))`` - ``zero_or_one``


------------

.. index:: swap/2
.. _random_protocol/0::swap/2:

``swap/2``
^^^^^^^^^^

Swaps two randomly selected elements of a list. Fails if the list is empty or contains a single element.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``swap(OldList,NewList)``
| **Mode and number of proofs:**
|    ``swap(-term,+list(term))`` - ``zero_or_one``


------------

.. index:: swap_consecutive/2
.. _random_protocol/0::swap_consecutive/2:

``swap_consecutive/2``
^^^^^^^^^^^^^^^^^^^^^^

Swaps two randomly selected consecutive elements of a list. Fails if the list is empty or contains a single element.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``swap_consecutive(OldList,NewList)``
| **Mode and number of proofs:**
|    ``swap_consecutive(-term,+list(term))`` - ``zero_or_one``


------------

.. index:: enumerate/2
.. _random_protocol/0::enumerate/2:

``enumerate/2``
^^^^^^^^^^^^^^^

Enumerates the elements of a list in random order. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``enumerate(List,Random)``
| **Mode and number of proofs:**
|    ``enumerate(+list(term),--term)`` - ``zero_or_more``


------------

.. index:: permutation/2
.. _random_protocol/0::permutation/2:

``permutation/2``
^^^^^^^^^^^^^^^^^

Returns a random permutation of a list.

| **Compilation flags:**
|    ``static, synchronized``

| **Template:**
|    ``permutation(List,Permutation)``
| **Mode and number of proofs:**
|    ``permutation(+list,-list)`` - ``one``


------------

.. index:: sequence/4
.. _random_protocol/0::sequence/4:

``sequence/4``
^^^^^^^^^^^^^^

Returns list of random integers of given length in random order in interval ``[Lower, Upper]``. Fails if ``Length``, ``Lower``, or ``Upper`` are not integers or if ``Lower > Upper``.

| **Compilation flags:**
|    ``static, synchronized``

| **Template:**
|    ``sequence(Length,Lower,Upper,List)``
| **Mode and number of proofs:**
|    ``sequence(+integer,+integer,+integer,-list(integer))`` - ``zero_or_one``


------------

.. index:: set/4
.. _random_protocol/0::set/4:

``set/4``
^^^^^^^^^

Returns ordered set of random integers of given size in interval ``[Lower, Upper]``. Fails if ``Length``, ``Lower``, or ``Upper`` are not integers, if ``Lower > Upper``, or if ``Length > Upper - Lower + 1``.

| **Compilation flags:**
|    ``static, synchronized``

| **Template:**
|    ``set(Length,Lower,Upper,Set)``
| **Mode and number of proofs:**
|    ``set(+integer,+integer,+integer,-list(integer))`` - ``zero_or_one``


------------

.. index:: random/3
.. _random_protocol/0::random/3:

``random/3``
^^^^^^^^^^^^

Returns a new random value in the interval ``[Lower, Upper[``. Fails if ``Lower > Upper``. Deprecated. Use ``between/3`` for integers.

| **Compilation flags:**
|    ``static, synchronized``

| **Template:**
|    ``random(Lower,Upper,Random)``
| **Mode and number of proofs:**
|    ``random(+integer,+integer,-integer)`` - ``zero_or_one``
|    ``random(+float,+float,-float)`` - ``zero_or_one``


------------

.. index:: randseq/4
.. _random_protocol/0::randseq/4:

``randseq/4``
^^^^^^^^^^^^^

Returns list of random values of given length in random order in interval ``[Lower, Upper[``. Fails if ``Lower > Upper`` or if the arguments are neither integers or floats. Deprecated. Use ``sequence/4`` for integers.

| **Compilation flags:**
|    ``static, synchronized``

| **Template:**
|    ``randseq(Length,Lower,Upper,List)``
| **Mode and number of proofs:**
|    ``randseq(+integer,+integer,+integer,-list(integer))`` - ``zero_or_one``
|    ``randseq(+integer,+float,+float,-list(float))`` - ``zero_or_one``


------------

.. index:: randset/4
.. _random_protocol/0::randset/4:

``randset/4``
^^^^^^^^^^^^^

Returns ordered set of random values of given size in interval ``[Lower, Upper[``. Fails if the arguments are neither integers or floats, ``Lower > Upper``, or ``Length > Upper - Lower`` when arguments are integers. Deprecated. Use ``set/4`` for integers.

| **Compilation flags:**
|    ``static, synchronized``

| **Template:**
|    ``randset(Length,Lower,Upper,Set)``
| **Mode and number of proofs:**
|    ``randset(+integer,+integer,+integer,-list(integer))`` - ``zero_or_one``
|    ``randset(+integer,+float,+float,-list(float))`` - ``zero_or_one``


------------

.. index:: maybe/0
.. _random_protocol/0::maybe/0:

``maybe/0``
^^^^^^^^^^^

Succeeds or fails with equal probability.

| **Compilation flags:**
|    ``static``

| **Mode and number of proofs:**
|    ``maybe`` - ``zero_or_one``


------------

.. index:: maybe/1
.. _random_protocol/0::maybe/1:

``maybe/1``
^^^^^^^^^^^

Succeeds with probability ``Probability`` or fails with probability ``1 - Probability``. Fails if ``Probability`` is not a float or is outside the interval ``[0.0, 1.0]``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``maybe(Probability)``
| **Mode and number of proofs:**
|    ``maybe(+probability)`` - ``zero_or_one``


------------

.. index:: maybe/2
.. _random_protocol/0::maybe/2:

``maybe/2``
^^^^^^^^^^^

Succeeds with probability ``K/N`` where ``K`` and ``N`` are integers satisfying the equation ``0 =< K =< N``. Fails otherwise.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``maybe(K,N)``
| **Mode and number of proofs:**
|    ``maybe(+non_negative_integer,+non_negative_integer)`` - ``zero_or_one``


------------

.. index:: maybe_call/1
.. _random_protocol/0::maybe_call/1:

``maybe_call/1``
^^^^^^^^^^^^^^^^

Calls a goal or fails without calling it with equal probability. When the goal is called, it determines if this predicate succeeds once or fails.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``maybe_call(Goal)``
| **Meta-predicate template:**
|    ``maybe_call(0)``
| **Mode and number of proofs:**
|    ``maybe_call(+callable)`` - ``zero_or_one``


------------

.. index:: maybe_call/2
.. _random_protocol/0::maybe_call/2:

``maybe_call/2``
^^^^^^^^^^^^^^^^

Calls a goal or fails without calling it with probability ``Probability``. When the goal is called, it determines if this predicate succeeds once or fails.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``maybe_call(Probability,Goal)``
| **Meta-predicate template:**
|    ``maybe_call(*,0)``
| **Mode and number of proofs:**
|    ``maybe_call(+probability,+callable)`` - ``zero_or_one``


------------

Protected predicates
--------------------

(none)

Private predicates
------------------

(none)

Operators
---------

(none)

.. seealso::

   :ref:`random <random/0>`, :ref:`backend_random <backend_random/0>`, :ref:`fast_random <fast_random/0>`

