rand

Documentation

Overview

Package rand provides safer defaults and more options than the built-in Go random packages.

Index

• Variables
• func Float64(rng Rand) (r float64, err error)
• func Float64Between(rng Rand, lo, hi float64) (float64, error)
• func Uint64(rng Rand) (r uint64, err error)
• func Uint64Between(rng Rand, lo, hi uint64) (uint64, error)
• func Uint64N(rng Rand, n uint64) (uint64, error)
• type ConstantSeeder
  • func NewConstantSeeder(seed uint64) *ConstantSeeder
  • func (cs *ConstantSeeder) Seed(target Seedable) error
• type DiscreteRand
• type ExpRandFactory
  • func NewExpRandFactory(cons func(seed uint64) exprand.Source, seeder Seeder) *ExpRandFactory
  • func NewPCGFactory(seeder Seeder) *ExpRandFactory
  • func (erf *ExpRandFactory) New() (Rand, error)
• type Factory
• type FactoryFunc
  • func (ff FactoryFunc) New() (Rand, error)
• type LockableRand
• type Rand
  • func ThreadSafe(rng Rand) Rand
• type Seed
  • func (s *Seed) Seed(seed uint64)
• type Seedable
• type Seeder
• type TestFactory
  • func NewTestFactory(seeder Seeder) *TestFactory
  • func (tf *TestFactory) New() (Rand, error)

Variables

var (
	// SecureRand is the system cryptographically-secure random number
	// generator. It is equivalent to the Reader of Go's crypto/rand. SecureRand
	// is safe to use across Goroutines.
	SecureRand Rand = &secureRand{}

	// SecureFactory provides SecureRand as a factory for compatibility with
	// users that expect a factory.
	SecureFactory Factory = FactoryFunc(func() (Rand, error) {
		return SecureRand, nil
	})
)

var DefaultFactory = NewPCGFactory(SecureSeeder)

DefaultFactory is a PCG RNG that is initially seeded by the SecureSeeder.

var (
	// ErrImpossible is returned by discrete functions if an invocation would
	// result in a random number generator faulting because the parameters
	// requested cannot be computed.
	ErrImpossible = errors.New("rand: impossible construction")
)

var OneSeeder = NewConstantSeeder(1)

OneSeeder seeds RNGs with 1 for testing purposes.

var ZeroSeeder = NewConstantSeeder(0)

ZeroSeeder seeds RNGs with 0 for testing purposes.

Functions

func Float64

func Float64(rng Rand) (r float64, err error)

Float64 returns, as a float64, a pseudo-random number in [0.0,1.0).

func Float64Between

func Float64Between(rng Rand, lo, hi float64) (float64, error)

Float64Between returns, as a float64, a pseudo-random number between [lo,hi).

func Uint64

func Uint64(rng Rand) (r uint64, err error)

Uint64 returns a pseudo-random 64-bit integer as a uint64.

func Uint64Between

func Uint64Between(rng Rand, lo, hi uint64) (uint64, error)

Uint64Between returns, as a uint64, a pseudo-random number in [lo,hi).

func Uint64N

func Uint64N(rng Rand, n uint64) (uint64, error)

Uint64N returns, as a uint64, a pseudo-random number in [0,n).

Types

type ConstantSeeder

type ConstantSeeder struct {
	// contains filtered or unexported fields
}

ConstantSeeder seeds RNGs with a fixed value for testing purposes.

func NewConstantSeeder

func NewConstantSeeder(seed uint64) *ConstantSeeder

NewConstantSeeder creates a new seeder with the given fixed seed.

func (*ConstantSeeder) Seed

func (cs *ConstantSeeder) Seed(target Seedable) error

Seed sets the target's seed to the seed of this struct.

type DiscreteRand

type DiscreteRand interface {
	Rand

	// Uint64 returns the next available random integer.
	Uint64() uint64
}

DiscreteRand is a random number generator that natively supports generating integers in addition to producing random byte data.

type ExpRandFactory

type ExpRandFactory struct {
	// contains filtered or unexported fields
}

ExpRandFactory is a Goroutine-safe factory for random number generators that use a source compatible with Go's new experimental rand (golang.org/x/exp/rand) package.

func NewExpRandFactory

func NewExpRandFactory(cons func(seed uint64) exprand.Source, seeder Seeder) *ExpRandFactory

NewExpRandFactory creates a factory for producing RNGs from a source compatible with Go's new experimental rand package initialized with the given seeder.

func NewPCGFactory

func NewPCGFactory(seeder Seeder) *ExpRandFactory

NewPCGFactory creates a factory for producing RNGs using the permuted congruential generator (PCG) algorithm. Each RNG it produces will be seeded using the given seeder.

func (*ExpRandFactory) New

func (erf *ExpRandFactory) New() (Rand, error)

New returns a new RNG for this configuration.

type Factory

type Factory interface {
	// New creates an RNG.
	New() (Rand, error)
}

Factory is a Goroutine-safe factory for constructing and seeding random number generators using a particular algorithm.

type FactoryFunc

type FactoryFunc func() (Rand, error)

FactoryFunc allows a factory to be defined by a function.

func (FactoryFunc) New

func (ff FactoryFunc) New() (Rand, error)

New creates an RNG by calling the function.

type LockableRand

type LockableRand interface {
	Rand

	// ThreadSafe returns a new RNG with the same characteristics as this RNG,
	// but that is also safe to use across Goroutines.
	ThreadSafe() Rand
}

LockableRand is a specialization of Rand that allows implementations to choose their own behavior to become Goroutine-safe.

type Rand

type Rand interface {
	io.Reader
}

Rand defines an instance of a random number generator. Instances of random number generators are generally not safe to use across Goroutines. Exceptions are indicated as such.

func ThreadSafe

func ThreadSafe(rng Rand) Rand

ThreadSafe makes the given RNG safe to use across Goroutines.

type Seed

type Seed uint64

Seed is a Seedable that simply stores the seed value to be retrieved later.

func (*Seed) Seed

func (s *Seed) Seed(seed uint64)

Seed stores the given seed as this type's value.

type Seedable

type Seedable interface {
	// Seed sets this RNG's seed.
	Seed(seed uint64)
}

Seedable is the type of an RNG that is able to be seeded.

type Seeder

type Seeder interface {
	// Seed sets the target's seed using this seeder's algorithm.
	Seed(target Seedable) error
}

Seeder seeds an RNG with a particular value or algorithm.

All implementations of Seeder must be safe for use across concurrent Goroutines.

var SecureSeeder Seeder = &secureSeeder{}

SecureSeeder seeds non-secure RNGs with a value produced by SecureRand.

type TestFactory

type TestFactory struct {
	// contains filtered or unexported fields
}

TestFactory provides an RNG for testing purposes that simply increments the seed value provided to it.

func NewTestFactory

func NewTestFactory(seeder Seeder) *TestFactory

NewTestFactory creates a Goroutine-safe factory for constructing test RNGs that start from a seed provided by the specified seeder.

func (*TestFactory) New

func (tf *TestFactory) New() (Rand, error)

New returns a new RNG for this configuration.