> ## Random functions (C++ SDK)

> Fetch the complete documentation index at: https://antithesis.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---

## Random functions

Random functions request both structured and unstructured randomness from the Antithesis platform. They are part of the [Antithesis C++ SDK](/docs/reference/sdk/cpp/).

These functions should not be used to seed a conventional PRNG, and should not have their return values stored and used to make a decision at a later time. Doing either of these things makes it much harder for the Antithesis platform to control the history of your program's execution, and also makes it harder for Antithesis to learn which inputs, provided at which times, are most fruitful. Instead, you should call a function from the random package every time your program or [test template](/docs/product/test_templates/) needs to make a decision -- at the moment that you need to make the decision.

These functions are also safe to call outside the Antithesis environment, where they will fall back on values from the [standard library's random](https://en.cppreference.com/w/cpp/header/random). If you want to override this default behavior, then `#define` `ANTITHESIS_RANDOM_OVERRIDE`. If this is defined, then the SDK will use the provided function when run locally. (This setting is ignored when run in the Antithesis environment.)

> **Note**
>
> To use this override, define `ANTITHESIS_RANDOM_OVERRIDE` before including `antithesis_sdk.h`:
>
> ```cpp
> #define ANTITHESIS_RANDOM_OVERRIDE my_random
> #include "antithesis_sdk.h"
>
>  // ...
>
> uint64_t my_random() {
>     // Do something and return a random number
> }
> ```

## Functions

### Get random

```cpp
uint64_t get_random()
```

Returns a `uint64_t` value chosen by Antithesis.

You should use this value immediately rather than using it later. If you delay, then it is possible for the simulation to branch in between receiving the random data and using it. These branches will have the same random value, which defeats the purpose of branching.

Similarly, do not use the value to seed a pseudo-random number generator. The PRNG will produce a deterministic sequence of pseudo-random values based on the seed, so if the simulation branches, the PRNG will use the same sequence of values in all branches.

The function is called using the Antithesis namespace:
`antithesis::get_random()`

### Random choice

```cpp
template <typename Iter>
Iter random_choice(Iter begin, Iter end)
```

Returns a randomly chosen item from a list of options.

You should use this value immediately rather than using it later. If you delay, then it is possible for the simulation to branch in between receiving the random data and using it. These branches will have the same random value, which defeats the purpose of branching.

Similarly, do not use the value to seed a pseudo-random number generator. The PRNG will produce a deterministic sequence of pseudo-random values based on the seed, so if the simulation branches, the PRNG will use the same sequence of values in all branches.

Internally, this function gets its randomness from `get_random()`.

This function is not purely for convenience. Signaling to the Antithesis platform that you intend to use a random value in a structured way enables it to provide more interesting choices over time.

The function is called using the Antithesis namespace:
`antithesis::random_choice(begin, end)`

#### Template parameters

**Iter**
`Iter` should be a [random-access iterator](https://en.cppreference.com/w/cpp/iterator/random_access_iterator) type.

**Example**

```cpp
std::string in {"ABCDEFGHIJK"};
char random_character = *antithesis::random_choice(in.begin(), in.end());
```