Go package for random numbers with a simple API
The package tsrand provides a simple interface for random numbers. Each interface function returns a rnd.Rand for a specified random number generator. A returned rnd.Rand instance uses the specified random number generator to provide random numbers over its interface. The package exposes the random number generators math/rand and crypto/rand from the Go standard library as well as builtin example random number generators SimpleSource, MT32Source, and MT64Source. Also, the interface enables the use of a custom random number generator source with function New.
- Simple: Without configuration, just function calls
- Easy to use: Retrieve random numbers with rnd.Rand
- Tested: Unit tests with high code coverage.
- Dependencies: Only depends on the Go Standard Library, tserr and lpstats
The package is installed with
go get github.com/thorstenrie/tsrand
In the Go app, the package is imported with
import "github.com/thorstenrie/tsrand"
Each interface function returns a rnd.Rand for a specified random number generator. A returned rnd.Rand instance uses the specified random number generator to provide random numbers over its interface.
- Cryptographically secure random number generator based on crypto/rand
- Pseudo-random number generator based on math/rand
- Deterministic pseudo-random number generator based on math/rand
- A custom implementation of a random number generator Source with New. It is the responsibility of the source to be safe for concurrent use by multiple goroutines.
- Example of a very simple pseudo-random number generator SimpleSource based on an very simple example from Wikipedia
- Example pseudo-random number generator MT32Source based on the 32-bit Mersenne Twister
- Example pseudo-random number generator MT64Source based on the 64-bit Mersenne Twister
Except for the cryptographically secure random number generator, the output of the pseudo-random number generators might be easily predictable and is unsuitable for security-sensitive services.
Results from linux, amd64, AMD Ryzen 5 2600X Six-Core Processor
| Source | Benchmark |
|---|---|
| crypto/rand | ~500 ns/op |
| math/rand | ~7 ns/op |
| SimpleSource | ~35 ns/op |
| MT32Source | ~12 ns/op |
| MT64Source | ~6 ns/op |
package main
import (
"fmt"
"github.com/thorstenrie/tsrand"
)
func main() {
fmt.Println("Rolling a dice...")
rnd, _ := tsrand.NewCryptoRand()
fmt.Println(rnd.Intn(6) + 1)
rnd, _ = tsrand.NewPseudoRandomRand()
fmt.Println(rnd.Intn(6) + 1)
rnd, _ = tsrand.New(tsrand.NewSimpleSource())
fmt.Println(rnd.Intn(6) + 1)
}
Each Test function generates (pseudo-)random numbers using the defined source of the test. It generates random values of types integer, unsigned integer, and float64. The Test functions compare for each type the arithmetic mean and variance of the retrieved random numbers with the expected values for mean and variance. If the arithmetic mean and variance of the retrieved random numbers differ more than the constant maxDiff from expected values, the test fails. Therefore, the Test functions provide an indication if the sources for random number generators are providing random values in expected boundaries. The Test functions do not evaluate the quality of retrieved random numbers and implementation of the random number generator source. The output of the random number generator sources might be easily predictable and unsuitable for security-sensitive services.