nupp.random

nupp.random provides unpredictable bytes and reproducible sequences.

local random = require("nupp.random")

const nonce = random.randomBytes(32)

const dice = new random.Xoshiro128(42)

print(dice:integer(20))
print(dice:next())

randomBytes asks the host for cryptographically secure bytes, and is what a key, a nonce, or a token wants. A Xoshiro128 is the opposite: an independent xoshiro128** sequence with nothing hidden in it, so the same seed always draws the same numbers. Omitting the seed picks a fixed one rather than reading a clock. Request a seed explicitly when a sequence must vary between runs.

A seed is one 32-bit word. A generator is mutable and is not safe to share between workers; give each lane its own.

state and setState copy the four signed 32-bit state words. That is the portable checkpoint format: keep them and the next draw is exactly the one that was coming.

Submodules

ModuleDescription
nupp.random.spiImplementation interfaces consumed during ordinary module initialization.

Module contents

Types

TypeKindDescription
Xoshiro128recordAn independent deterministic xoshiro128 sequence.

Values

ValueKindDescription
randomBytesvariableReturns cryptographically secure random bytes from the selected host.

Types#

Xoshiro128record#

record Xoshiro128 ...

An independent deterministic xoshiro128** sequence.

Members

NameKindDescription
s0field
s1field
s2field
s3field
constructorconstructorCreates a generator.
nextmethodReturns the next multiple of 2^-32 in [0, 1).
integermethodReturns an integer in [1, m], or in [m, n] when both are given.
rangemethodReturns the next value in [low, high), or (high, low] when reversed.
shufflemethodShuffles a list in place with Fisher-Yates and returns the same list.
reseedmethodRestarts this generator from a 32-bit seed without changing its identity.
statemethodCopies the four signed 32-bit state words into a fresh array.
setStatemethodRestores exactly four state words.

s0field#

s0: int32
@private

s1field#

s1: int32
@private

s2field#

s2: int32
@private

s3field#

s3: int32
@private

constructorconstructor#

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

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

Arguments
NameTypeDescription
selfany
seedinteger?

nextmethod#

next: function next(self): number

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

Arguments
NameTypeDescription
selfany
Returns
TypeDescription
number

integermethod#

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

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

A range of up to 2^32 values takes one draw, so seeded sequences over small ranges stay what they were. A wider one takes 53 bits from two draws and rejects the uneven tail, so every value in it can come up.

Arguments
NameTypeDescription
selfany
minteger
ninteger?
Returns
TypeDescription
integer
Raises
TypeCondition
string

when the selected range is empty, when a bound is not a finite integer, or when the range holds more than 2^53 values

rangemethod#

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

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

Equal bounds return that bound.

Arguments
NameTypeDescription
selfany
lownumber
highnumber
Returns
TypeDescription
number

shufflemethod#

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

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

Arguments
NameTypeDescription
selfany
values{T}
Returns
TypeDescription
{T}

reseedmethod#

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

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

Arguments
NameTypeDescription
selfany
seedinteger
Returns
TypeDescription
nil

statemethod#

state: function state(self): {integer}

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

Arguments
NameTypeDescription
selfany
Returns
TypeDescription
{integer}

setStatemethod#

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

Restores exactly four state words.

Arguments
NameTypeDescription
selfany
words{integer}
Returns
TypeDescription
nil
Raises
TypeCondition
string

when there are not four words or all four are zero

Values#

randomBytesvariable#

const randomBytes

Returns cryptographically secure random bytes from the selected host.

Raises

TypeCondition
string

when the count is invalid or the host cannot supply randomness