README
¶
randomness
Package randomness provides math/rand dropin replace with secured initialization.
Functions
func ASCII
func ASCII(length int) (string, error)
ASCII returns a securely generated random ASCII string. It reads random numbers from crypto/rand and searches for printable characters. It will return an error if the system's secure random number generator fails to function correctly, in which case the caller must not continue.
Entropy is 6.5 bits per character.
func Alphabet
func Alphabet(length int) (string, error)
Alphabet returns a random string of the given length using the 52 alphabetic characters in the POSIX/C locale (a-z+A-Z).
Entropy is 5.7 bits per character.
func Alphanumeric
func Alphanumeric(length int) (string, error)
Alphanumeric returns a random string of the given length using the 62 alphanumeric characters in the POSIX/C locale (0-9+a-z+A-Z).
Entropy is 5.95 bits per character.
func Bytes
func Bytes(size int) ([]byte, error)
Bytes generates a new byte slice of the given size.
Entropy is 8 bits per byte.
func CryptoSeed
func CryptoSeed() int64
CryptoSeed returns a seed using crypto/rand. On error, the function generates a panic with the error.
// Usign rand.Seed is deprecated since Go 1.20.
// Initialize the concurrent usage safe PRNG math/rand with a CSPRNG sourced random integer.
prng := NewLockedRand(CryptoSeed())
// Generate a random number between 0 and 99
prng.Intn(100)
func ExpFloat64
func ExpFloat64() float64
ExpFloat64 returns an exponentially distributed float64 in the range (0, +math.MaxFloat64] with an exponential distribution whose rate parameter (lambda) is 1 and whose mean is 1/lambda (1) from the default Source. To produce a distribution with a different rate parameter, callers can adjust the output using:
sample = ExpFloat64() / desiredRateParameter
func Float32
func Float32() float32
Float32 returns, as a float32, a pseudo-random number in the half-open interval [0.0,1.0) from the default Source.
func Float64
func Float64() float64
Float64 returns, as a float64, a pseudo-random number in the half-open interval [0.0,1.0) from the default Source.
func Hex
func Hex(length int) (string, error)
Hex returns a random string of the given length using the hexadecimal characters in lower case (0-9+a-f).
Entropy is 4 bits per character.
func Int
func Int() int
Int returns a non-negative pseudo-random int from the default Source.
func Int31
func Int31() int32
Int31 returns a non-negative pseudo-random 31-bit integer as an int32 from the default Source.
func Int31n
func Int31n(n int32) int32
Int31n returns, as an int32, a non-negative pseudo-random number in the half-open interval [0,n) from the default Source. It panics if n <= 0.
func Int63
func Int63() int64
Int63 returns a non-negative pseudo-random 63-bit integer as an int64 from the default Source.
func Int63n
func Int63n(n int64) int64
Int63n returns, as an int64, a non-negative pseudo-random number in the half-open interval [0,n) from the default Source. It panics if n <= 0.
func Intn
func Intn(n int) int
Intn returns, as an int, a non-negative pseudo-random number in the half-open interval [0,n) from the default Source. It panics if n <= 0.
func NormFloat64
func NormFloat64() float64
NormFloat64 returns a normally distributed float64 in the range [-math.MaxFloat64, +math.MaxFloat64] with standard normal distribution (mean = 0, stddev = 1) from the default Source. To produce a different normal distribution, callers can adjust the output using:
sample = NormFloat64() * desiredStdDev + desiredMean
func Number
func Number(length int) (string, error)
Number returns a random string of the given length using the 10 numeric characters in the POSIX/C locale (0-9).
Entropy is 3.32 bits per character.
func Perm
func Perm(n int) []int
Perm returns, as a slice of n ints, a pseudo-random permutation of the integers in the half-open interval [0,n) from the default Source.
func Shuffle
func Shuffle(n int, swap func(i, j int))
Shuffle pseudo-randomizes the order of elements using the default Source. n is the number of elements. Shuffle panics if n < 0. swap swaps the elements with indexes i and j.
func String
func String(length int, chars string) (string, error)
String returns a random string of a given length using the characters in the given string. It splits the string on runes to support UTF-8 characters.
Entropy is log2(len(chars)) bits per character.
func Uint32
func Uint32() uint32
Uint32 returns a pseudo-random 32-bit value as a uint32 from the default Source.
func Uint64
func Uint64() uint64
Uint64 returns a pseudo-random 64-bit value as a uint64 from the default Source.
func VerificationCode
func VerificationCode(length int) (string, error)
VerificationCode returns a random string without vowels and confusing characters (0, O, 1, l, I). It is useful to prevent word generation and more precisely offensive words. It uses the 20 characters in the POSIX/C locale (BCDFGHJKLMNPQRSTVWXYZ).
Entropy is 4.32 bits per character.
Types
type LockedRand
type LockedRand struct { ... }
func NewLockedRand
func NewLockedRand(seed int64) *LockedRand
NewLockedRand implements a threadsafe wrapper to the math/rand.Rand implementation.
func (*LockedRand) ExpFloat64
func (lr *LockedRand) ExpFloat64() (n float64)
ExpFloat64 returns an exponentially distributed float64 in the range (0, +math.MaxFloat64] with an exponential distribution whose rate parameter (lambda) is 1 and whose mean is 1/lambda (1). To produce a distribution with a different rate parameter, callers can adjust the output using:
sample = ExpFloat64() / desiredRateParameter
func (*LockedRand) Float32
func (lr *LockedRand) Float32() (n float32)
Float32 returns, as a float32, a pseudo-random number in [0.0,1.0).
func (*LockedRand) Float64
func (lr *LockedRand) Float64() (n float64)
Float64 returns, as a float64, a pseudo-random number in [0.0,1.0).
func (*LockedRand) Int
func (lr *LockedRand) Int() (n int)
Int returns a non-negative pseudo-random int.
func (*LockedRand) Int31
func (lr *LockedRand) Int31() (n int32)
Int31 returns a non-negative pseudo-random 31-bit integer as an int32.
func (*LockedRand) Int31n
func (lr *LockedRand) Int31n(n int32) (r int32)
Int31n returns, as an int32, a non-negative pseudo-random number in [0,n). It panics if n <= 0.
func (*LockedRand) Int63
func (lr *LockedRand) Int63() (n int64)
Int63 returns a non-negative pseudo-random 63-bit integer as an int64.
func (*LockedRand) Int63n
func (lr *LockedRand) Int63n(n int64) (r int64)
Int63n returns, as an int64, a non-negative pseudo-random number in [0,n). It panics if n <= 0.
func (*LockedRand) Intn
func (lr *LockedRand) Intn(n int) (r int)
Intn returns, as an int, a non-negative pseudo-random number in [0,n). It panics if n <= 0.
func (*LockedRand) NormFloat64
func (lr *LockedRand) NormFloat64() (n float64)
NormFloat64 returns a normally distributed float64 in the range -math.MaxFloat64 through +math.MaxFloat64 inclusive, with standard normal distribution (mean = 0, stddev = 1). To produce a different normal distribution, callers can adjust the output using:
sample = NormFloat64() * desiredStdDev + desiredMean
func (*LockedRand) Perm
func (lr *LockedRand) Perm(n int) (r []int)
Perm returns, as a slice of n ints, a pseudo-random permutation of the integers [0,n).
func (*LockedRand) Shuffle
func (lr *LockedRand) Shuffle(n int, swap func(i, j int))
Shuffle pseudo-randomizes the order of elements. n is the number of elements. Shuffle panics if n < 0. swap swaps the elements with indexes i and j.
func (*LockedRand) Uint32
func (lr *LockedRand) Uint32() (n uint32)
Uint32 returns a pseudo-random 32-bit value as a uint32.
func (*LockedRand) Uint64
func (lr *LockedRand) Uint64() (n uint64)
Uint64 returns a pseudo-random 64-bit value as a uint64.
Documentation
¶
Overview ¶
Package randomness provides `math/rand` dropin replace with secured initialization.
Index ¶
- func ASCII(length int) (string, error)
- func Alphabet(length int) (string, error)
- func Alphanumeric(length int) (string, error)
- func Bytes(size int) ([]byte, error)
- func CryptoSeed() int64
- func ExpFloat64() float64
- func Float32() float32
- func Float64() float64
- func Hex(length int) (string, error)
- func Int() int
- func Int31() int32
- func Int31n(n int32) int32
- func Int63() int64
- func Int63n(n int64) int64
- func Intn(n int) int
- func NormFloat64() float64
- func Number(length int) (string, error)
- func Perm(n int) []int
- func Shuffle(n int, swap func(i, j int))
- func String(length int, chars string) (string, error)
- func Uint32() uint32
- func Uint64() uint64
- func VerificationCode(length int) (string, error)
- type LockedRand
- func (lr *LockedRand) ExpFloat64() (n float64)
- func (lr *LockedRand) Float32() (n float32)
- func (lr *LockedRand) Float64() (n float64)
- func (lr *LockedRand) Int() (n int)
- func (lr *LockedRand) Int31() (n int32)
- func (lr *LockedRand) Int31n(n int32) (r int32)
- func (lr *LockedRand) Int63() (n int64)
- func (lr *LockedRand) Int63n(n int64) (r int64)
- func (lr *LockedRand) Intn(n int) (r int)
- func (lr *LockedRand) NormFloat64() (n float64)
- func (lr *LockedRand) Perm(n int) (r []int)
- func (lr *LockedRand) Shuffle(n int, swap func(i, j int))
- func (lr *LockedRand) Uint32() (n uint32)
- func (lr *LockedRand) Uint64() (n uint64)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ASCII ¶
ASCII returns a securely generated random ASCII string. It reads random numbers from crypto/rand and searches for printable characters. It will return an error if the system's secure random number generator fails to function correctly, in which case the caller must not continue.
Entropy is 6.5 bits per character.
func Alphabet ¶
Alphabet returns a random string of the given length using the 52 alphabetic characters in the POSIX/C locale (a-z+A-Z).
Entropy is 5.7 bits per character.
func Alphanumeric ¶
Alphanumeric returns a random string of the given length using the 62 alphanumeric characters in the POSIX/C locale (0-9+a-z+A-Z).
Entropy is 5.95 bits per character.
func CryptoSeed ¶
func CryptoSeed() int64
CryptoSeed returns a seed using crypto/rand. On error, the function generates a panic with the error.
Example ¶
// Usign rand.Seed is deprecated since Go 1.20. // Initialize the concurrent usage safe PRNG math/rand with a CSPRNG sourced random integer. prng := NewLockedRand(CryptoSeed()) // Generate a random number between 0 and 99 prng.Intn(100)
Output:
func ExpFloat64 ¶
func ExpFloat64() float64
ExpFloat64 returns an exponentially distributed float64 in the range (0, +math.MaxFloat64] with an exponential distribution whose rate parameter (lambda) is 1 and whose mean is 1/lambda (1) from the default Source. To produce a distribution with a different rate parameter, callers can adjust the output using:
sample = ExpFloat64() / desiredRateParameter
func Float32 ¶
func Float32() float32
Float32 returns, as a float32, a pseudo-random number in the half-open interval [0.0,1.0) from the default Source.
func Float64 ¶
func Float64() float64
Float64 returns, as a float64, a pseudo-random number in the half-open interval [0.0,1.0) from the default Source.
func Hex ¶
Hex returns a random string of the given length using the hexadecimal characters in lower case (0-9+a-f).
Entropy is 4 bits per character.
func Int31 ¶
func Int31() int32
Int31 returns a non-negative pseudo-random 31-bit integer as an int32 from the default Source.
func Int31n ¶
Int31n returns, as an int32, a non-negative pseudo-random number in the half-open interval [0,n) from the default Source. It panics if n <= 0.
func Int63 ¶
func Int63() int64
Int63 returns a non-negative pseudo-random 63-bit integer as an int64 from the default Source.
func Int63n ¶
Int63n returns, as an int64, a non-negative pseudo-random number in the half-open interval [0,n) from the default Source. It panics if n <= 0.
func Intn ¶
Intn returns, as an int, a non-negative pseudo-random number in the half-open interval [0,n) from the default Source. It panics if n <= 0.
func NormFloat64 ¶
func NormFloat64() float64
NormFloat64 returns a normally distributed float64 in the range [-math.MaxFloat64, +math.MaxFloat64] with standard normal distribution (mean = 0, stddev = 1) from the default Source. To produce a different normal distribution, callers can adjust the output using:
sample = NormFloat64() * desiredStdDev + desiredMean
func Number ¶
Number returns a random string of the given length using the 10 numeric characters in the POSIX/C locale (0-9).
Entropy is 3.32 bits per character.
func Perm ¶
Perm returns, as a slice of n ints, a pseudo-random permutation of the integers in the half-open interval [0,n) from the default Source.
func Shuffle ¶
Shuffle pseudo-randomizes the order of elements using the default Source. n is the number of elements. Shuffle panics if n < 0. swap swaps the elements with indexes i and j.
func String ¶
String returns a random string of a given length using the characters in the given string. It splits the string on runes to support UTF-8 characters.
Entropy is log2(len(chars)) bits per character.
func Uint32 ¶
func Uint32() uint32
Uint32 returns a pseudo-random 32-bit value as a uint32 from the default Source.
func Uint64 ¶
func Uint64() uint64
Uint64 returns a pseudo-random 64-bit value as a uint64 from the default Source.
func VerificationCode ¶
VerificationCode returns a random string without vowels and confusing characters (0, O, 1, l, I). It is useful to prevent word generation and more precisely offensive words. It uses the 20 characters in the POSIX/C locale (BCDFGHJKLMNPQRSTVWXYZ).
Entropy is 4.32 bits per character.
Types ¶
type LockedRand ¶
type LockedRand struct {
// contains filtered or unexported fields
}
func NewLockedRand ¶
func NewLockedRand(seed int64) *LockedRand
NewLockedRand implements a threadsafe wrapper to the math/rand.Rand implementation.
func (*LockedRand) ExpFloat64 ¶
func (lr *LockedRand) ExpFloat64() (n float64)
ExpFloat64 returns an exponentially distributed float64 in the range (0, +math.MaxFloat64] with an exponential distribution whose rate parameter (lambda) is 1 and whose mean is 1/lambda (1). To produce a distribution with a different rate parameter, callers can adjust the output using:
sample = ExpFloat64() / desiredRateParameter
func (*LockedRand) Float32 ¶
func (lr *LockedRand) Float32() (n float32)
Float32 returns, as a float32, a pseudo-random number in [0.0,1.0).
func (*LockedRand) Float64 ¶
func (lr *LockedRand) Float64() (n float64)
Float64 returns, as a float64, a pseudo-random number in [0.0,1.0).
func (*LockedRand) Int ¶
func (lr *LockedRand) Int() (n int)
Int returns a non-negative pseudo-random int.
func (*LockedRand) Int31 ¶
func (lr *LockedRand) Int31() (n int32)
Int31 returns a non-negative pseudo-random 31-bit integer as an int32.
func (*LockedRand) Int31n ¶
func (lr *LockedRand) Int31n(n int32) (r int32)
Int31n returns, as an int32, a non-negative pseudo-random number in [0,n). It panics if n <= 0.
func (*LockedRand) Int63 ¶
func (lr *LockedRand) Int63() (n int64)
Int63 returns a non-negative pseudo-random 63-bit integer as an int64.
func (*LockedRand) Int63n ¶
func (lr *LockedRand) Int63n(n int64) (r int64)
Int63n returns, as an int64, a non-negative pseudo-random number in [0,n). It panics if n <= 0.
func (*LockedRand) Intn ¶
func (lr *LockedRand) Intn(n int) (r int)
Intn returns, as an int, a non-negative pseudo-random number in [0,n). It panics if n <= 0.
func (*LockedRand) NormFloat64 ¶
func (lr *LockedRand) NormFloat64() (n float64)
NormFloat64 returns a normally distributed float64 in the range -math.MaxFloat64 through +math.MaxFloat64 inclusive, with standard normal distribution (mean = 0, stddev = 1). To produce a different normal distribution, callers can adjust the output using:
sample = NormFloat64() * desiredStdDev + desiredMean
func (*LockedRand) Perm ¶
func (lr *LockedRand) Perm(n int) (r []int)
Perm returns, as a slice of n ints, a pseudo-random permutation of the integers [0,n).
func (*LockedRand) Shuffle ¶
func (lr *LockedRand) Shuffle(n int, swap func(i, j int))
Shuffle pseudo-randomizes the order of elements. n is the number of elements. Shuffle panics if n < 0. swap swaps the elements with indexes i and j.
func (*LockedRand) Uint32 ¶
func (lr *LockedRand) Uint32() (n uint32)
Uint32 returns a pseudo-random 32-bit value as a uint32.
func (*LockedRand) Uint64 ¶
func (lr *LockedRand) Uint64() (n uint64)
Uint64 returns a pseudo-random 64-bit value as a uint64.
Source Files