README
¶
Rand
The built-in math/rand library is not very condusive to injection or testability:
- The way the rand.Rand library computes its values differs widely per type (e.g. an Int vs Int31 grabs different halves of the rand.Source's 64-bit field). This makes test fakes very impractical.
- Use of the global rand methods prohibit test injection, but the struct interface isn't goroutine safe.
To fix these, this rand ipmlementation can fully supplant math/rand. The library
performs three primary functions:
- It introduces an interface version of
rand.Randto allow better mocking (see xkcdrand for one such fake) - It allows this interface to be created inline without importing both
inlined/randandmath/randin the same file. - It allows the interface to be created with a goroutine-safe source, preserving
the benefits of the package global
math/randmethods.
The Rand interface implementations in this library are trivial wrappers around
math/rand to avoid any loss of entropy. Since the library does not require a
rand.Source in its constructors, callers should remember to always call Rand.Seed
in production code. This is similar to the math/rand package methods, which also
default to a seed of 1.
Usage
// Create an interface version of math/rand.Rand using the default (fixed) seed.
// Seeds can be changed with Rand.Seed.
rand.New()
// Create an interface version of math/rand.Rand that is goroutine safe, unlike
// math/rand.New()
rand.NewLocked()
Credit
lockedsource.go, while trivial, is inspired directly by the lockedSource
type in math/rand/rand.go.
Documentation
¶
Overview ¶
Package rand allows developers to inject rand.Rand interfaces rather the math/rand.Rand struct. This allows for easier testing with two benefits:
- Developers can inject either a locking or unlocking Rand implementation (the built-in rand locks global methods and does not lock rand.Rand struct methods.
- The rand.Rand interface allows more straightforward faking. The built-in rand.Rand struct has differemt mechanisms for extracting various kinds of ints from bit fields, which can make fakes unnecessarily hard to create. For one such fake, see [xkcdrand](github.com/inlined/xkcdrand).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Rand ¶
type Rand interface {
ExpFloat64() float64
Float32() float32
Float64() float64
Int() int
Int31() int32
Int31n(n int32) int32
Int63() int64
Int63n(n int64) int64
Intn(n int) int
NormFloat64() float64
Perm(n int) []int
Read(p []byte) (n int, err error)
Seed(seed int64)
Shuffle(n int, swap func(i, j int))
Uint32() uint32
Uint64() uint64
}
Rand is an injectable interface that matches the struct of math/rand.Rand
Source Files