rand

Documentation

Overview

Package rand is the single home for randomness over g types, built on math/rand/v2.

rand.N(10)                    // Int-like value in [0, 10)
rand.Range(5, 10)             // half-open [5, 10)
rand.RangeInclusive(1, 6)     // closed [1, 6]
rand.Float()                  // Float in [0, 1)
rand.Chance(0.25)             // true with probability 0.25
rand.String(10)               // 10 alphanumeric characters
rand.Choice(users)            // Option with a random element
rand.Sample(deck, 5)          // 5 distinct random elements
rand.Shuffle(deck)            // in place; accepts Slice, MapOrd, plain slices
rand.SecureString(32)         // crypto/rand-backed token

Every function is generic over its numeric arguments: integer parameters accept any integer type (int, g.Int, uint32, ...), float parameters any float type, and the result follows the argument's type where one exists.

The container types deliberately carry NO random methods — everything lives here, one way to do it.

The generators come from math/rand/v2 and are NOT cryptographically secure. For keys, tokens and anything security-sensitive use SecureBytes and SecureString, which draw from crypto/rand.

Index

• func Bool() bool
• func Bytes[I constraints.Integer](length I) g.Bytes
• func Chance[T constraints.Float](p T) bool
• func Choice[S ~[]E, E any](sl S) g.Option[E]
• func Choices[S ~[]E, E any, I constraints.Integer](sl S, k I) S
• func Float() g.Float
• func N[T constraints.Integer](n T) T
• func NormFloat() g.Float
• func Perm[T constraints.Integer](n T) g.Slice[T]
• func Range[T constraints.Integer](lo, hi T) T
• func RangeInclusive[T constraints.Integer](lo, hi T) T
• func Sample[S ~[]E, E any, I constraints.Integer](sl S, k I) S
• func SecureBytes[I constraints.Integer](length I) g.Bytes
• func SecureString[I constraints.Integer](length I, letters ...g.String) g.String
• func Shuffle[S ~[]E, E any](sl S)
• func String[I constraints.Integer](length I, letters ...g.String) g.String
• func Uniform[T constraints.Float](lo, hi T) T

Functions

func Bool

func Bool() bool

Bool returns true or false with equal probability.

func Bytes

func Bytes[I constraints.Integer](length I) g.Bytes

Bytes returns length random bytes. NOT cryptographically secure — use SecureBytes for keys and tokens.

func Chance

func Chance[T constraints.Float](p T) bool

Chance returns true with probability p. Values outside [0, 1] clamp to always-false / always-true.

func Choice

func Choice[S ~[]E, E any](sl S) g.Option[E]

Choice returns a random element of the slice. An empty slice yields None. It accepts any slice-shaped type (Slice, MapOrd, plain slices).

func Choices

func Choices[S ~[]E, E any, I constraints.Integer](sl S, k I) S

Choices returns k elements drawn WITH replacement. An empty source or non-positive k yields an empty result.

func Float

func Float() g.Float

Float returns a random Float in [0, 1).

func N

func N[T constraints.Integer](n T) T

N returns a random integer in [0, n). It panics if n <= 0, matching math/rand/v2.N.

func NormFloat

func NormFloat() g.Float

NormFloat returns a normally distributed Float with mean 0 and standard deviation 1.

func Perm

func Perm[T constraints.Integer](n T) g.Slice[T]

Perm returns a random permutation of the integers [0, n) as a Slice of the argument's integer type.

func Range

func Range[T constraints.Integer](lo, hi T) T

Range returns a random integer in the half-open interval [lo, hi). It panics if hi <= lo.

func RangeInclusive

func RangeInclusive[T constraints.Integer](lo, hi T) T

RangeInclusive returns a random integer in the closed interval [lo, hi]. The order of bounds does not matter (it normalizes to [min, max]); it works for negative bounds and the full int64 range without overflow or bias.

func Sample

func Sample[S ~[]E, E any, I constraints.Integer](sl S, k I) S

Sample returns k distinct elements drawn WITHOUT replacement. If k is not less than the slice length, a shuffled copy of the whole slice is returned. The source slice is not modified.

func SecureBytes

func SecureBytes[I constraints.Integer](length I) g.Bytes

SecureBytes returns length cryptographically secure random bytes drawn from crypto/rand. A zero or negative length yields nil.

Unlike the rest of this package, the result is safe for keys, tokens and other security-sensitive material.

func SecureString

func SecureString[I constraints.Integer](length I, letters ...g.String) g.String

SecureString generates a cryptographically secure random String of the specified length, selecting characters from predefined sets. If additional character sets are provided, only those are used; the default set (g.ASCIILetters and g.Digits) is excluded unless explicitly provided.

If length is zero or negative, an empty String is returned. If an explicit letter set is provided but resolves to empty, an empty String is returned as well.

Characters are drawn from crypto/rand with rejection sampling, so the selection is uniform (no modulo bias). Unlike String, the result is safe for tokens, one-time codes and other security-sensitive material.

rand.SecureString(32)          // 32 alphanumeric characters
rand.SecureString(6, g.Digits) // 6-digit one-time code

func Shuffle

func Shuffle[S ~[]E, E any](sl S)

Shuffle permutes the slice in place. It accepts any slice-shaped type (Slice, MapOrd, plain slices).

func String

func String[I constraints.Integer](length I, letters ...g.String) g.String

String generates a random String of the specified length, selecting characters from predefined sets. If additional character sets are provided, only those are used; the default set (g.ASCIILetters and g.Digits) is excluded unless explicitly provided.

If length is zero or negative, an empty String is returned. If an explicit letter set is provided but resolves to empty, an empty String is returned as well.

rand.String(10)          // 10 alphanumeric characters
rand.String(6, g.Digits) // 6-digit code

func Uniform

func Uniform[T constraints.Float](lo, hi T) T

Uniform returns a random value in [lo, hi) of the arguments' float type.