# mozz.rng

> A module of mozz_mlake's API.

Xoshiro256++ — fast, seedable, non-cryptographic PRNG.

Implementation of the xoshiro256++ algorithm by Vigna & Blackman (2018).
Period: 2^256 − 1.  Speed: ~1 ns/sample on ARM64.

State is four ``UInt64`` words initialized by running ``splitmix64`` on
the user-supplied seed.  This avoids the degenerate all-zero state.

Example:
    ```mojo
    var rng = Xoshiro256(seed=42)
    var byte = rng.next_byte()          # uniform random UInt8
    var n = rng.next_below(100)         # uniform in [0, 100)
    var buf = List[UInt8](capacity=32)
    for _ in range(32):
        buf.append(0)
    rng.fill(buf)                       # fill with random bytes
    ```

## Structs

### `Xoshiro256`

```mojo
struct Xoshiro256
```

Xoshiro256++ PRNG.

Deterministic when constructed with an explicit nonzero ``seed``.
Passing ``seed=0`` generates entropy from a stack address.

All internal state is ``UInt64``; no heap allocation.

Fields:
    s0, s1, s2, s3: The four 64-bit state words.

Implements: `Copyable`, `ImplicitlyCopyable`, `Movable`

Fields:

- `s0: UInt64`
- `s1: UInt64`
- `s2: UInt64`
- `s3: UInt64`

#### `__init__`

```mojo
def __init__(out self, seed: UInt64 = UInt64(0))
```

Initialize the PRNG from a 64-bit seed.

If ``seed`` is 0 a non-deterministic seed is derived from a stack
address (sufficient entropy for fuzzing, not cryptographic).

Args:

- `seed`: Seed value.  Pass the same value to replay a run.

#### `next_u64`

```mojo
def next_u64(mut self) -> UInt64
```

Return the next uniformly random ``UInt64``.

Advances the internal state by one step.

#### `next_u32`

```mojo
def next_u32(mut self) -> UInt32
```

Return the next uniformly random ``UInt32``.

#### `next_byte`

```mojo
def next_byte(mut self) -> UInt8
```

Return a uniformly random byte in ``[0, 255]``.

#### `next_below`

```mojo
def next_below(mut self, n: UInt64) -> UInt64
```

Return a uniformly random value in ``[0, n)``.

Uses rejection sampling to avoid modulo bias.

Args:

- `n`: Upper bound (exclusive).  Must be > 0.

#### `next_bool`

```mojo
def next_bool(mut self) -> Bool
```

Return a uniformly random boolean (50 % each side).

#### `fill`

```mojo
def fill(mut self, mut buf: List[UInt8])
```

Fill ``buf`` with uniformly random bytes.

Uses a single 8-byte store (``bitcast[UInt64]``) per PRNG call instead
of eight individual byte extractions — avoids 7 shifts, 8 masks, and
8 casts per 8-byte block.

Args:

- `buf`: Destination byte list (modified in-place via unsafe pointer).