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)

## Public predicates

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `maybe/0`

Succeeds or fails with equal probability.

Compilation flags:
`static`
Mode and number of proofs:
`maybe` - `zero_or_one`

### `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`

### `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`

### `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`

### `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)

See also

random, backend_random, fast_random