1
0
mirror of https://github.com/vlang/v.git synced 2023-08-10 21:13:21 +03:00
v/vlib/rand
2021-10-13 09:40:14 +03:00
..
config checker: require params attribute to use struct as keyword arguments in function (#11135) 2021-09-14 00:05:30 +03:00
constants rand: refactor string sampling functions to remove redundancy (#8830) 2021-02-19 11:16:02 +02:00
dist fmt: fix unnecessary line break in array init (fix #11448) (#11562) 2021-09-21 16:20:09 +03:00
mt19937 rand: fix leaks with -autofree 2021-09-23 12:24:03 +03:00
musl rand: fix leaks with -autofree 2021-09-23 12:24:03 +03:00
pcg32 rand: fix leaks with -autofree 2021-09-23 12:24:03 +03:00
seed rand: fix leaks with -autofree 2021-09-23 12:24:03 +03:00
splitmix64 rand: fix leaks with -autofree 2021-09-23 12:24:03 +03:00
sys rand: fix leaks with -autofree 2021-09-23 12:24:03 +03:00
util rand.util: workaround for inaccurate v warning in vlib/rand/util/util.v (#10344) 2021-06-04 17:05:58 +03:00
wyrand js: fix rand build, properly use key values on map, add rand.string (#12020) 2021-10-01 21:23:49 +03:00
rand_test.js.v js: fix rand build, properly use key values on map, add rand.string (#12020) 2021-10-01 21:23:49 +03:00
rand.c.v js: fix rand build, properly use key values on map, add rand.string (#12020) 2021-10-01 21:23:49 +03:00
rand.js.v js: implement more functions for JS backend (#12167) 2021-10-13 09:40:14 +03:00
rand.v checker: add an interface check for mutability, fixes #1081, fixes #7038 (#11963) 2021-10-11 15:41:31 +03:00
random_identifiers_test.v time: turn Time.unix to i64, so it can represent times before 1970-01-01, fix time operators, add more tests (#11050) 2021-08-04 13:12:02 +03:00
random_numbers_test.v rand: add PRNG interface and unit-tests (#9083) 2021-03-03 13:41:00 +02:00
README.md rand: update documentation (#9406) 2021-03-21 19:36:17 +02:00

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.

You can change the default generator to a different one. The only requirement is that the generator must implement the PRNG interface. See get_current_rng() and set_rng().

For non-uniform distributions, refer to the rand.dist module which defined functions for sampling from non-uniform distributions. These functions make use of the global RNG.

Note: The global PRNG is not thread safe. It is recommended to use separate generators for separate threads in multi-threaded applications. If you need to use non-uniform sampling functions, it is recommended to generate them before use in a multi-threaded context.

For sampling functions and generating random strings, see string_from_set() and other related functions defined in this top-level module.

For arrays, see rand.util.

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()

There are several additional functions defined in the top-level module that rely on the global RNG. If you want to make use of those functions with a different PRNG, you can can change the global RNG to do so.

Seeding Functions

All the generators are time-seeded. The helper functions publicly available in rand.seed 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.