pcg-random/.scratch/pcg-random.d.ts

Implementation of the PCG random number generator for JavaScript

/**
 * A random number generator that implements the PCG32 algorithm, as described
 * here: <http://www.pcg-random.org>.
 *
 * ## Caveats
 *
 * Note that this is not a cryptographically secure random number generator.
 * Please Do not use this generator in cryptographically sensitive applications.
 */
declare class PcgRandom {
	/**
	 * Construct a {@linkcode PcgRandom} with a random seed and the default
	 * incrementor.
	 */
	constructor();

	/**
	 * Construct a {@linkcode PcgRandom} with the provided 64 bit seed and the
	 * default incrementor.
	 *
	 * @param {number} seedLo32 The lower (least significant) 32 bits of the seed.
	 * @param {number} [seedHi32 = 0] The upper (most significant) 32 bits of the seed.
	 */
	constructor(seedLo32: number, seedHi32?: number);

	/**
	 * Construct a {@linkcode PcgRandom} with the provided 64 bit seed and
	 * incrementor.
	 *
	 * @param seedLo32 The lower (least significant) 32 bits of the seed.
	 * @param seedHi32 The upper (most significant) 32 bits of the seed.
	 * @param incLo32 The lower 32 bits of the incrementor.
	 * @param incHi32 The upper 32 bits of the incrementor.
	 */
	constructor(seedLo32: number, seedHi32: number, incLo32: number, incHi32: number);

	/**
	 * Construct a {@linkcode PcgRandom} with the provided seed and optionally
	 * the incrementor, provided as bigints.
	 *
	 * @param {bigint} seed The seed as a bigint (only 64 bits will be used)
	 * @param {bigint} [inc] The incrementor as a bigint.
	 *
	 * (This overload requires support for bigints, although the library itself
	 * does not).
	 */
	constructor(seed: bigint, inc?: bigint);

	/**
	 * Construct a {@linkcode PcgRandom} copying from the provided state
	 * directly.
	 *
	 * @param state The state to copy from.
	 *
	 * The state should be an array of 4 numbers. The state should be laid out
	 * the same as the format returned by {@linkcode PcgRandom#getState},
	 * specifically:
	 *
	 * - `state[0]`: Lower 32 bits of seed.
	 * - `state[1]`: Upper 32 bits of seed.
	 * - `state[2]`: Lower 32 bits of incrementor.
	 * - `state[3]`: Upper 32 bits of incrementor.
	 *
	 * @throws {TypeError} State must have 4 numbers.
	 */
	constructor(state: Uint32Array | [number, number, number, number]);

	/**
	 * Randomize the seed of this {@linkcode PcgRandom}. The incrementor is left
	 * unchanged.
	 */
	setSeed();

	/**
	 * Set the seed of this {@linkcode PcgRandom} to the provided 32 bit value.
	 * The incrementor is left unchanged.
	 *
	 * @param seedLo32 The lower 32 bits of the (64 bit) seed.
	 */
	setSeed(seedLo32: number);

	/**
	 * Set the seed of this {@linkcode PcgRandom} to the provided 64 bit value.
	 * The incrementor is left unchanged.
	 *
	 * @param {number} seedLo32 The lower (least significant) 32 bits of the 64 bit seed.
	 * @param {number} [seedHi32 = 0] The upper (most significant) 32 bits of the 64 bit seed.
	 */
	setSeed(seedLo32: number, seedHi32?: number);

	/**
	 * Set the seed and incrementor of this {@linkcode PcgRandom} to the
	 * provided 64 bit values.
	 *
	 * @param seedHi32 The upper (most significant) 32 bits of the seed.
	 * @param seedLo32 The lower (least significant) 32 bits of the seed.
	 * @param incHi32 The upper 32 bits of the incrementor.
	 * @param incLo32 The lower 32 bits of the incrementor.
	 */
	setSeed(seedHi32: number, seedLo32: number, incHi32: number, incLo32: number);

	/**
	 * Set the state of this {@linkcode PcgRandom} directly.
	 *
	 * @param state The state array to copy from.
	 *
	 * The state should be an array of 4 numbers. The state should be laid out
	 * the same as the format returned by {@linkcode PcgRandom#getState},
	 * specifically:
	 *
	 * - `state[0]`: Upper 32 bits of seed.
	 * - `state[1]`: Lower 32 bits of seed.
	 * - `state[2]`: Upper 32 bits of incrementor.
	 * - `state[3]`: Lower 32 bits of incrementor.
	 *
	 * @throws {TypeError} State must be an array of 4 numbers.
	 */
	setSeed(state: Uint32Array | [number, number, number, number]);

	/**
	 * Construct a {@linkcode PcgRandom} with the provided seed and (optionally)
	 * incrementor, where both are provided as bigints.
	 *
	 * @param seed The seed as a bigint.
	 * @param inc The incrementor as a bigint. If not provided, the incrementor
	 * will not be changed.
	 *
	 * (This overload, of course, requires support for bigints, although the
	 * library itself does not).
	 */
	setSeed(seed: bigint, inc?: bigint);
}