rand #

Quickstart

The V rand module provides two main ways in which users can generate pseudorandom numbers:

  1. Through top-level functions in the rand module.
    • import rand - Import the rand module.
    • rand.seed(seed_data) to seed (optional).
    • Use rand.int(), rand.u32n(max), etc.
  2. Through a generator of choice. The PRNGs are included in their respective submodules.
    • import rand.pcg32 - Import the module of the PRNG required.
    • mut rng := pcg32.PCG32RNG{} - Initialize the struct. Note that the mut is important.
    • rng.seed(seed_data) - optionally seed it with an array of u32 values.
    • Use rng.int(), rng.u32n(max), etc.

General Background

A PRNG is a Pseudo Random Number Generator. Computers cannot generate truly random numbers without an external source of noise or entropy. We can use algorithms to generate sequences of seemingly random numbers, but their outputs will always be deterministic. This is often useful for simulations that need the same starting seed.

If you need truly random numbers that are going to be used for cryptography, use the crypto.rand module.

Guaranteed functions

The following 21 functions are guaranteed to be supported by rand as well as the individual PRNGs.

  • seed(seed_data) where seed_data is an array of u32 values. Different generators require different number of bits as the initial seed. The smallest is 32-bits, required by sys.SysRNG. Most others require 64-bits or 2 u32 values.
  • u32(), u64(), int(), i64(), f32(), f64()
  • u32n(max), u64n(max), intn(max), i64n(max), f32n(max), f64n(max)
  • u32_in_range(min, max), u64_in_range(min, max), int_in_range(min, max), i64_in_range(min, max), f32_in_range(min, max), f64_in_range(min, max)
  • int31(), int63()

Utility Functions

All the generators are time-seeded. The helper functions publicly available in rand.util module are:

  1. time_seed_array() - returns a []u32 that can be directly plugged into the seed() functions.
  2. time_seed_32() and time_seed_64() - 32-bit and 64-bit values respectively that are generated from the current time.

Caveats

Note that the sys.SysRNG struct (in the C backend) uses C.srand() which sets the seed globally. Consequently, all instances of the RNG will be affected. This problem does not arise for the other RNGs. A workaround (if you must use the libc RNG) is to:

  1. Seed the first instance.
  2. Generate all values required.
  3. Seed the second instance.
  4. Generate all values required.
  5. And so on...

Notes

Please note that math interval notation is used throughout the function documentation to denote what numbers ranges include. An example of [0, max) thus denotes a range with all posible values between 0 and max including 0 but excluding max.

fn byte #

fn byte() byte

byte returns a uniformly distributed pseudorandom 8-bit unsigned positive byte.

fn f32 #

fn f32() f32

f32 returns a uniformly distributed 32-bit floating point in range [0, 1).

fn f32_in_range #

fn f32_in_range(min f32, max f32) f32

f32_in_range returns a uniformly distributed 32-bit floating point in range [min, max).

fn f32n #

fn f32n(max f32) f32

f32n returns a uniformly distributed 32-bit floating point in range [0, max).

fn f64 #

fn f64() f64

f64 returns a uniformly distributed 64-bit floating point in range [0, 1).

fn f64_in_range #

fn f64_in_range(min f64, max f64) f64

f64_in_range returns a uniformly distributed 64-bit floating point in range [min, max).

fn f64n #

fn f64n(max f64) f64

f64n returns a uniformly distributed 64-bit floating point in range [0, max).

fn i64 #

fn i64() i64

i64 returns a uniformly distributed pseudorandom 64-bit signed (possibly negative) i64.

fn i64_in_range #

fn i64_in_range(min i64, max i64) i64

i64_in_range returns a uniformly distributed pseudorandom 64-bit signed i64 in range [min, max).

fn i64n #

fn i64n(max i64) i64

i64n returns a uniformly distributed pseudorandom 64-bit signed positive i64 in range [0, max).

fn int #

fn int() int

int returns a uniformly distributed pseudorandom 32-bit signed (possibly negative) int.

fn int31 #

fn int31() int

int31 returns a uniformly distributed pseudorandom 31-bit signed positive int.

fn int63 #

fn int63() i64

int63 returns a uniformly distributed pseudorandom 63-bit signed positive i64.

fn int_in_range #

fn int_in_range(min int, max int) int

int_in_range returns a uniformly distributed pseudorandom 32-bit signed int in range [min, max). Both min and max can be negative, but we must have min < max.

fn intn #

fn intn(max int) int

intn returns a uniformly distributed pseudorandom 32-bit signed positive int in range [0, max).

fn new_default #

fn new_default(config PRNGConfigStruct) &wyrand.WyRandRNG

new_default returns a new instance of the default RNG. If the seed is not provided, the current time will be used to seed the instance.

fn seed #

fn seed(seed []u32)

seed sets the given array of u32 values as the seed for the default_rng.

fn string #

fn string(len int) string

string returns a string of length len containing random characters in range [a-zA-Z].

fn u32 #

fn u32() u32

u32 returns a uniformly distributed u32 in range [0, 2³²).

fn u32_in_range #

fn u32_in_range(min u32, max u32) u32

u32_in_range returns a uniformly distributed pseudorandom 32-bit unsigned u32 in range [min, max).

fn u32n #

fn u32n(max u32) u32

u32n returns a uniformly distributed pseudorandom 32-bit signed positive u32 in range [0, max).

fn u64 #

fn u64() u64

u64 returns a uniformly distributed u64 in range [0, 2⁶⁴).

fn u64_in_range #

fn u64_in_range(min u64, max u64) u64

u64_in_range returns a uniformly distributed pseudorandom 64-bit unsigned u64 in range [min, max).

fn u64n #

fn u64n(max u64) u64

u64n returns a uniformly distributed pseudorandom 64-bit signed positive u64 in range [0, max).

fn ulid #

fn ulid() string

ulid generates an Unique Lexicographically sortable IDentifier. See https://github.com/ulid/spec . NB: ULIDs can leak timing information, if you make them public, because you can infer the rate at which some resource is being created, like users or business transactions. (https://news.ycombinator.com/item?id=14526173)

fn ulid_at_millisecond #

fn ulid_at_millisecond(unix_time_milli u64) string

ulid_at_millisecond does the same as ulid but takes a custom Unix millisecond timestamp via unix_time_milli.

fn uuid_v4 #

fn uuid_v4() string

uuid_v4 generates a random (v4) UUID See https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)

struct PRNGConfigStruct #

struct PRNGConfigStruct {
	seed []u32 = seed.time_seed_array(2)
}

PRNGConfigStruct is a configuration struct for creating a new instance of the default RNG.