Documentation
¶
Overview ¶
Package randutil provides random number generation utilities.
The package provides two types of generators:
1. Secure generators using crypto/rand (for security-sensitive applications) 2. Fast generators using math/rand/v2 (for non-security applications)
Secure Random Generation ¶
For cryptographic purposes, password generation, or security tokens:
bytes, err := randutil.SecureBytes(32) str, err := randutil.SecureString(16, randutil.AlphaNumeric) id := randutil.SecureID()
Fast Random Generation ¶
For non-security purposes like tests, sampling, or simulations:
rng := randutil.NewGenerator() n := rng.Int(100) // [0, 100) f := rng.Float64() // [0.0, 1.0) item := rng.Choice(items) // Random element rng.Shuffle(items) // Shuffle in place
Deterministic Generation ¶
For reproducible random sequences in tests:
rng := randutil.NewGeneratorWithSeed(42) // Always produces the same sequence
Character Sets ¶
Predefined character sets for string generation:
Digits - "0123456789" Lowercase - "abcdefghijklmnopqrstuvwxyz" Uppercase - "ABCDEFGHIJKLMNOPQRSTUVWXYZ" Letters - Lowercase + Uppercase AlphaNumeric - Letters + Digits Hex - "0123456789abcdef"
Index ¶
- Constants
- Variables
- func Choice[T any](g *Generator, s []T) T
- func ChoiceN[T any](g *Generator, s []T, n int) []T
- func Range(start, end int) []int
- func RangeStep(start, end, step int) []int
- func Sample[T any](g *Generator, s []T, n int) []T
- func SecureBytes(n int) ([]byte, error)
- func SecureChoice[T any](s []T) (T, error)
- func SecureID() (string, error)
- func SecureInt(max int) (int, error)
- func SecureInt64(max int64) (int64, error)
- func SecureString(length int, charset string) (string, error)
- func Sequence(start, n int) []int
- func Shuffle[T any](g *Generator, s []T)
- func ShuffleCopy[T any](g *Generator, s []T) []T
- type Generator
- func (g *Generator) AlphaNumericString(length int) string
- func (g *Generator) Bool() bool
- func (g *Generator) Bytes(n int) []byte
- func (g *Generator) ChoiceInt(s []int) int
- func (g *Generator) ChoiceString(s []string) string
- func (g *Generator) Float32() float32
- func (g *Generator) Float64() float64
- func (g *Generator) Float64Range(min, max float64) float64
- func (g *Generator) Int(max int) int
- func (g *Generator) Int64(max int64) int64
- func (g *Generator) Int64Range(min, max int64) int64
- func (g *Generator) IntRange(min, max int) int
- func (g *Generator) Probability(p float64) bool
- func (g *Generator) SampleInts(s []int, n int) []int
- func (g *Generator) ShuffleInts(s []int)
- func (g *Generator) ShuffleStrings(s []string)
- func (g *Generator) String(length int, charset string) string
- func (g *Generator) WeightedChoice(weights []float64) int
Constants ¶
const ( Digits = "0123456789" Lowercase = "abcdefghijklmnopqrstuvwxyz" Uppercase = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" Letters = Lowercase + Uppercase AlphaNumeric = Letters + Digits Hex = "0123456789abcdef" Symbols = "!@#$%^&*()_+-=[]{}|;:,.<>?" All = AlphaNumeric + Symbols )
Character sets for random string generation.
Variables ¶
var ( ErrInvalidLength = errors.New("length must be positive") ErrEmptyCharset = errors.New("charset cannot be empty") ErrEmptySlice = errors.New("slice cannot be empty") )
Common errors.
Functions ¶
func SecureBytes ¶
SecureBytes returns n cryptographically secure random bytes.
Example:
key, err := SecureBytes(32) // 32 random bytes
func SecureChoice ¶
SecureChoice returns a cryptographically secure random element from the slice.
func SecureID ¶
SecureID generates a cryptographically secure random ID. Returns a 32-character hex string (128 bits of entropy).
Example:
id := SecureID() // "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
func SecureInt64 ¶
SecureInt64 returns a cryptographically secure random int64 in [0, max).
func SecureString ¶
SecureString returns a cryptographically secure random string of the specified length using characters from the charset.
Example:
password, err := SecureString(16, AlphaNumeric) token, err := SecureString(32, Hex)
func ShuffleCopy ¶
ShuffleCopy returns a new shuffled slice (does not modify original).
Types ¶
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator provides fast (non-cryptographic) random generation. Use NewGenerator() for automatic seeding or NewGeneratorWithSeed() for reproducibility.
func NewGenerator ¶
func NewGenerator() *Generator
NewGenerator creates a new Generator with automatic seeding. Uses a cryptographically secure seed for good randomness.
func NewGeneratorWithSeed ¶
NewGeneratorWithSeed creates a Generator with a specific seed. Useful for reproducible random sequences in tests.
Example:
rng := NewGeneratorWithSeed(42) // Always produces the same sequence
func (*Generator) AlphaNumericString ¶
AlphaNumericString returns a random alphanumeric string.
func (*Generator) ChoiceInt ¶
ChoiceInt returns a random element from an int slice. Panics if slice is empty.
func (*Generator) ChoiceString ¶
ChoiceString returns a random element from a string slice. Panics if slice is empty.
func (*Generator) Float64Range ¶
Float64Range returns a random float64 in [min, max).
func (*Generator) Int64Range ¶
Int64Range returns a random int64 in [min, max].
func (*Generator) Probability ¶
Probability returns true with the given probability (0.0 to 1.0).
Example:
if rng.Probability(0.75) {
// 75% chance of executing
}
func (*Generator) SampleInts ¶
SampleInts returns n random ints from the slice (without replacement). If n > len(s), returns all elements shuffled.
func (*Generator) ShuffleInts ¶
ShuffleInts shuffles an int slice in place.
func (*Generator) ShuffleStrings ¶
ShuffleStrings shuffles a string slice in place.
func (*Generator) String ¶
String returns a random string of the specified length using the charset.
func (*Generator) WeightedChoice ¶
WeightedChoice returns a random index based on weights. Weight values don't need to sum to 1.0.
Source Files