<a id="nupp.random"></a>
# `nupp.random`

Deterministic pseudo-random generation with explicit, serializable state.

Each `Random` owns an independent xoshiro128** sequence. A seed is always
interpreted as one 32-bit word, and omitting it chooses a fixed seed rather
than consulting a clock, so every sequence is reproducible. Generators are
mutable and intentionally not safe to share between concurrent workers.

```nupp
local random = require("nupp.random")

local dice = random.newRandom(42)
local d20 = dice:integer(20)
local unit = dice:next()
```

`state` and `setState` copy the four signed 32-bit state words. They are the
portable checkpoint format: preserving them preserves the next draw exactly.

## Constructors

<a id="nupp.random.newRandom"></a>
### `newRandom` _constructor_

```nupp
function newRandom(seed: integer?): Random
```

Creates a generator outside any host or scheduler.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `seed` | `integer?` |  |

#### Returns

| Type | Description |
| --- | --- |
| `Random` |  |

## Types

<a id="nupp.random.Random"></a>
### `Random` _record_

```nupp
record Random
    constructor(self, seed: integer?) end

    function next(self): number end

    function integer(self, m: integer, n: integer?): integer end

    function range(self, low: number, high: number): number end

    function shuffle<T>(self, values: {T}): {T} end

    function reseed(self, seed: integer): nil end

    function state(self): {integer} end

    function setState(self, words: {integer}): nil end
end
```

An independent deterministic xoshiro128** sequence.

#### Methods

<a id="nupp.random.Random.constructor"></a>
##### `constructor`

```nupp
constructor: function constructor(self, seed: integer?)
```

Creates a generator. An omitted seed uses a fixed reproducible value.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |
| `seed` | `integer?` |  |

<a id="nupp.random.Random.next"></a>
##### `next`

```nupp
next: function next(self): number
```

Returns the next multiple of 2^-32 in [0, 1).

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |

###### Returns

| Type | Description |
| --- | --- |
| `number` |  |

<a id="nupp.random.Random.integer"></a>
##### `integer`

```nupp
integer: function integer(self, m: integer, n: integer?): integer
```

Returns an integer in [1, m], or in [m, n] when both are given.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |
| `m` | `integer` |  |
| `n` | `integer?` |  |

###### Returns

| Type | Description |
| --- | --- |
| `integer` |  |

###### Raises

- when the selected range is empty

<a id="nupp.random.Random.range"></a>
##### `range`

```nupp
range: function range(self, low: number, high: number): number
```

Returns the next value in [low, high), or (high, low] when reversed.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |
| `low` | `number` |  |
| `high` | `number` |  |

###### Returns

| Type | Description |
| --- | --- |
| `number` |  |

<a id="nupp.random.Random.shuffle"></a>
##### `shuffle`

```nupp
shuffle: function shuffle<T>(self, values: {T}): {T}
```

Shuffles a list in place with Fisher-Yates and returns the same list.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |
| `values` | `{T}` |  |

###### Returns

| Type | Description |
| --- | --- |
| `{T}` |  |

<a id="nupp.random.Random.reseed"></a>
##### `reseed`

```nupp
reseed: function reseed(self, seed: integer): nil
```

Restarts this generator from a 32-bit seed without changing its identity.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |
| `seed` | `integer` |  |

###### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="nupp.random.Random.state"></a>
##### `state`

```nupp
state: function state(self): {integer}
```

Copies the four signed 32-bit state words into a fresh array.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |

###### Returns

| Type | Description |
| --- | --- |
| `{integer}` |  |

<a id="nupp.random.Random.setState"></a>
##### `setState`

```nupp
setState: function setState(self, words: {integer}): nil
```

Restores exactly four state words.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` |  |
| `words` | `{integer}` |  |

###### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

###### Raises

- when there are not four words or all four are zero